wally-dev 0.4.0

CLI para desenvolvimento local de casos de teste de acessibilidade da plataforma Wally

Wally Dev CLI

Wally Dev é uma ferramenta de linha de comando (CLI) para desenvolvimento local de casos de teste de acessibilidade da plataforma Wally.

🚀 Instalação

Opção 1: pipx (Recomendado)

# Instalar pipx (se necessário)
sudo apt install pipx
pipx ensurepath

# Instalar wally-dev
pipx install wally-dev

Opção 2: pip com virtual environment

# Criar e ativar virtual environment
python3 -m venv ~/.venvs/wally-dev
source ~/.venvs/wally-dev/bin/activate

# Instalar
pip install wally-dev

Opção 3: pip direto (sistemas sem proteção PEP 668)

pip install wally-dev

Requisitos

• Python 3.9 ou superior
• Conta ativa na plataforma Wally

📋 Comandos Disponíveis

Comando	Descrição
wally-dev login	Autenticar na plataforma Wally
wally-dev logout	Remover credenciais e desbloquear normas
wally-dev status	Mostrar status do workspace local
wally-dev norms list	Listar normas disponíveis
wally-dev rules list	Listar regras de uma norma
wally-dev checkout	Baixar casos de teste para desenvolvimento
wally-dev run	Executar casos de teste localmente
wally-dev push	Enviar alterações para o servidor
wally-dev upgrade	Verificar e instalar atualizações

🔐 Autenticação

# Login interativo
wally-dev login

# Com parâmetros
wally-dev login --username [e-mail] --org-id <organization-id>

🔄 Atualizações

O comando upgrade verifica e instala a versão mais recente do wally-dev automaticamente.

# Atualizar interativamente (pergunta antes de instalar)
wally-dev upgrade

# Verificar se há nova versão (exit code 1 = upgrade disponível)
wally-dev upgrade --check

# Atualizar automaticamente sem confirmação (ideal para CI/CD)
wally-dev upgrade --yes

# Atualizar para versão específica
wally-dev upgrade --version 0.2.0

Detecção automática: O comando detecta se você instalou via pipx ou pip e usa o método correto para atualizar.

Exit Codes:

Código	Significado
0	Sucesso (atualizado ou já está na última versão)
1	Upgrade disponível (com --check)
7	Erro durante o upgrade

📦 Workflow de Desenvolvimento

1. Listar normas disponíveis

wally-dev norms list

Saída:

╭────────────────── 📋 Normas (3) ──────────────────╮
│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓ │
│ ┃ ID                       ┃ Nome              ┃ │
│ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩ │
│ │ 6954434ffdd23615c0e5d85d │ NBR 17225         │ │
│ │ 695c46a91dd6a5bae0e4863b │ Community         │ │
│ └──────────────────────────┴───────────────────┘ │
╰───────────────────────────────────────────────────╯

2. Fazer checkout de uma norma

wally-dev checkout --norm-id <norm-id>

Isso irá:

• Bloquear a norma no servidor (impede edições simultâneas)
• Baixar todos os casos de teste e exemplos para ./workspace/

3. Estrutura do Workspace

./workspace/
  <norm-id>/
    testCases/
      <testcase-id>/
        testcase.json     # Metadados do caso de teste
        code/
          finder.py       # Função que encontra elementos
          validator.py    # Função que valida elementos
        examples/
          compliant/
            example.html  # HTML que deve passar
          non-compliant/
            example.html  # HTML que deve falhar

4. Desenvolver o caso de teste

finder.py

from bs4 import BeautifulSoup

def find(html_content: str):
    """
    Encontra elementos HTML para validação.
    
    Args:
        html_content: String com o HTML a ser analisado
        
    Yields:
        Elementos encontrados para validação
    """
    soup = BeautifulSoup(html_content, "html.parser")
    for img in soup.find_all("img"):
        yield img

validator.py

def validate(element) -> bool:
    """
    Valida se um elemento está em conformidade.
    
    Args:
        element: Elemento HTML encontrado pelo finder
        
    Returns:
        True se o elemento está em conformidade, False caso contrário
    """
    alt = element.get("alt", "")
    return bool(alt and alt.strip())

5. Executar testes localmente

# Executar todos os exemplos de um caso de teste
wally-dev run --testcase <testcase-id>

# Executar um exemplo específico
wally-dev run --testcase <testcase-id> --example compliant/example.html

# Modo debug (mostra elementos encontrados e validações)
wally-dev run --testcase <testcase-id> --debug

Saída com --debug:

╭───────────────────── 🔍 Debug Output ─────────────────────╮
│ Execução bem sucedida                                     │
│                                                           │
│ Elementos encontrados: 2                                  │
│ Tempo finder: 0.35ms                                      │
│ Tempo total: 0.40ms                                       │
╰───────────────────────────────────────────────────────────╯

📋 Elementos e Validações:
┏━━━┳━━━━━━━┳━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ # ┃ Linha ┃ Tag ┃ validate() ┃ Snippet                     ┃
┡━━━╇━━━━━━━╇━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 0 │    10 │ img │   ✓ True   │ <img alt="" src="img.jpg"/> │
│ 1 │    12 │ img │   ✓ True   │ <img aria-hidden="true"/>   │
└───┴───────┴─────┴────────────┴─────────────────────────────┘

6. Enviar alterações

wally-dev push --norm-id <norm-id>

🧪 Lógica de Validação

Os casos de teste seguem a convenção:

• Exemplos compliant/: Todos os elementos encontrados pelo finder devem retornar True no validator
• Exemplos non-compliant/: Pelo menos um elemento deve retornar False no validator

⚙️ Configuração

A CLI armazena configurações em ~/.config/wally-dev/.wally-dev.json:

{
  "access_token": "...",
  "refresh_token": "...",
  "user_email": "[e-mail]",
  "organization_id": "...",
  "backend_url": "https://api.wally.equallyze.com/backend/services/v0.0.1"
}

Variáveis de Ambiente

Variável	Descrição	Default
WALLY_DEV_BACKEND_URL	URL da API backend	https://api.wally.equallyze.com/...
WALLY_DEV_CONFIG_DIR	Diretório de configuração	~/.config/wally-dev

🛠️ Desenvolvimento

Instalação para desenvolvimento

git clone https://gitlab.com/AcessibilidadeParaTodos/wally/wally-dev.git
cd wally-dev

# Criar virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Instalar em modo editável com dependências de dev
pip install -e ".[dev]"

Executar testes

pytest
pytest --cov=wally_dev --cov-report=html

Formatação e linting

black wally_dev tests
isort wally_dev tests
ruff check wally_dev tests
mypy wally_dev

📄 Licença

Este software é propriedade da Equallyze Tecnologia LTDA. Todos os direitos reservados. Consulte o arquivo LICENSE para mais detalhes.

🔗 Links

• Plataforma Wally
• Documentação
• Equallyze
• Repositório

🤝 Suporte

Para suporte, abra uma issue no GitLab ou entre em contato através de [e-mail].