wally-dev 0.5.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 execução local de casos de teste de acessibilidade da plataforma Wally.

Trabalha diretamente com o repositório wally-norms sem necessidade de autenticação ou conexão com backend.

🚀 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
• Repositório wally-norms clonado localmente

📋 Comandos Disponíveis

Comando	Descrição
wally-dev list	Listar testcases disponíveis no repositório
wally-dev run	Executar testcases localmente
wally-dev upgrade	Verificar e instalar atualizações

⚙️ Configuração

A única configuração necessária é o caminho para o repositório wally-norms:

# Via variável de ambiente
export WALLY_NORMS_PATH=~/repos/equallyze/wally/wally-norms

# Ou via parâmetro
wally-dev list --norms-path ~/repos/equallyze/wally/wally-norms

Default: ~/repos/equallyze/wally/wally-norms

📦 Estrutura do Repositório wally-norms

wally-norms/
  {NormName}/                    # Ex: "NBR 17225"
    {RuleName}/                  # Ex: "1.1.1 Non-text Content"
      {technology}/              # Ex: "html", "react", "angular"
        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

📋 Listar Testcases

# Listar todos os testcases
wally-dev list

# Listar em formato de árvore
wally-dev list --tree

# Mostrar resumo
wally-dev list --summary

# Filtrar por norma
wally-dev list --norm "NBR 17225"

# Filtrar por regra
wally-dev list --rule "1.1.1"

# Filtrar por tecnologia
wally-dev list --tech html

Saída exemplo:

╭────────────────── 📋 Testcases (42) ──────────────────╮
│ ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━┓ │
│ ┃ Norm           ┃ Rule              ┃ Tech   ┃ ✓   ┃ │
│ ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━┩ │
│ │ NBR 17225      │ 1.1.1 Non-text    │ html   │ ✓ ✓ │ │
│ │ NBR 17225      │ 1.2.1 Audio-only  │ html   │ ✓ ✓ │ │
│ │ NBR 17225      │ 5.2.1 Keyboard    │ html   │ ✓ ✓ │ │
│ └────────────────┴───────────────────┴────────┴─────┘ │
╰───────────────────────────────────────────────────────╯

🧪 Executar Testcases

# Executar todos os testcases
wally-dev run

# Executar testcase específico
wally-dev run "1.1.1/html"
wally-dev run "NBR 17225/1.1.1 Non-text Content/html"

# Filtrar por norma
wally-dev run --norm "NBR 17225"

# Filtrar por regra
wally-dev run --rule "5.2.1"

# Filtrar por tecnologia
wally-dev run --tech html

# Modo verbose (mais detalhes)
wally-dev run --verbose

# Modo debug (mostra elementos encontrados)
wally-dev run --debug

Saída exemplo:

╭────────────────────── 🔍 Caso de Teste ──────────────────────╮
│ 1.1.1 Non-text Content                                       │
│ Tecnologia: html                                             │
│ Exemplos: 4                                                  │
╰──────────────────────────────────────────────────────────────╯

┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
┃ Exemplo                  ┃ Esperado  ┃ Resultado ┃ Status  ┃ Tempo  ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩
│ compliant/example.html   │ compliant │ compliant │ ✓ PASS  │ 1.2ms  │
│ compliant/decorative.html│ compliant │ compliant │ ✓ PASS  │ 0.8ms  │
│ non-compliant/no-alt.html│ non-comp. │ non-comp. │ ✓ PASS  │ 0.9ms  │
│ non-compliant/empty.html │ non-comp. │ non-comp. │ ✓ PASS  │ 1.1ms  │
└──────────────────────────┴───────────┴───────────┴─────────┴────────┘

✓ Todos os 4 exemplos passaram

🔄 Atualizações

# Verificar e instalar atualizações
wally-dev upgrade

# Verificar sem instalar (exit code 1 = upgrade disponível)
wally-dev upgrade --check

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

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

📝 Desenvolvendo Testcases

finder.py

from bs4 import BeautifulSoup

def find(source: 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(source, "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())

🧪 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

🛠️ 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

# Testes com cobertura
pytest --cov=wally_dev --cov-report=term-missing

# Testes rápidos
pytest -x -v

Formatação e Linting

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

📊 Exit Codes

Código	Significado
0	Sucesso
1	Erro de configuração
4	Testcase não encontrado
5	Erro de execução do testcase
6	Falha nos testes (exemplos não passaram)

📄 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].