wally-dev 0.3.0
CLI para desenvolvimento local de casos de teste de acessibilidade da plataforma Wally
Requires Python: >=3.9
Keywords: accessibility, a11y, testing, cli, wally, equallyze, acessibilidade, nbr17225

# Wally Dev CLI

[![PyPI version](https://img.shields.io/pypi/v/wally-dev.svg)](https://pypi.org/project/wally-dev/)
[![Python versions](https://img.shields.io/pypi/pyversions/wally-dev.svg)](https://pypi.org/project/wally-dev/)
[![Pipeline](https://gitlab.com/AcessibilidadeParaTodos/wally/wally-dev/badges/main/pipeline.svg)](https://gitlab.com/AcessibilidadeParaTodos/wally/wally-dev/-/pipelines)

**Wally Dev** é uma ferramenta de linha de comando (CLI) para desenvolvimento local de casos de teste de acessibilidade da plataforma [Wally](https://acessibilidade.global).

## 🚀 Instalação

### Opção 1: pipx (Recomendado)

```bash
# 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

```bash
# 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)

```bash
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

```bash
# Login interativo
wally-dev login

# Com parâmetros
wally-dev login --username user@example.com --org-id <organization-id>
```

## 🔄 Atualizações

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

```bash
# 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

```bash
wally-dev norms list
```

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

### 2. Fazer checkout de uma norma

```bash
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`

```python
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`

```python
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

```bash
# 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

```bash
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`:

```json
{
  "access_token": "...",
  "refresh_token": "...",
  "user_email": "user@example.com",
  "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

```bash
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

```bash
pytest
pytest --cov=wally_dev --cov-report=html
```

### Formatação e linting

```bash
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](https://equallyze.com). 
Todos os direitos reservados. Consulte o arquivo [LICENSE](LICENSE) para mais detalhes.

## 🔗 Links

- [Plataforma Wally](https://acessibilidade.global)
- [Documentação](https://acessibilidade.global/documentacao)
- [Equallyze](https://equallyze.com)
- [Repositório](https://gitlab.com/AcessibilidadeParaTodos/wally/wally-dev)

## 🤝 Suporte

Para suporte, abra uma issue no [GitLab](https://gitlab.com/AcessibilidadeParaTodos/wally/wally-dev/-/issues) ou entre em contato através de [contato@equallyze.com](mailto:contato@equallyze.com).