uxsentinel 1.1.3

Agente Universal de QA Visual, Auditoria de UX e Proteção de Regras de Negócio

O UXSentinel é um agente autônomo e inteligente projetado para auditar qualquer aplicação web (Odoo, React, Vue, Angular, Django, SaaS e portais corporativos). Ele opera abrindo o navegador em modo visível na sua tela, navegando como um usuário humano rigoroso com velocidade cadenciada e inspecionando visualmente cada tela com Modelos Multimodais de IA (Visão Computacional).

---

⚡ Instalação Rápida via PyPI

Você pode instalar o UXSentinel diretamente do PyPI em qualquer ambiente Python 3.12+:

# Instalação padrão via pip
pip install uxsentinel

# Instalar os navegadores do Playwright
playwright install chromium

Após a instalação, o executável uxsentinel estará disponível globalmente no seu terminal:

uxsentinel --help

---

🌟 Principais Recursos

• Acompanhamento Visual ao Vivo (Human-in-the-Loop): O navegador abre na sua tela (headless: false) com ritmo humano (slow_mo) e efeitos visuais animados (cursor virtual e halo luminoso no elemento clicado ou focado).
• Inspeção de Console e DevTools Chromium Acoplado: Abra a janela do navegador com o painel DevTools / Console ativado (--devtools) para auditoria ao vivo de erros JavaScript (console.error), avisos (warn), exceções não capturadas e falhas de rede HTTP (status 4xx e 5xx).
• Telemetria de Performance W3C: Mede com precisão métricas reais de carregamento via W3C Navigation Timing API (TTFB, Dom Interactive, Page Load time e tamanho transferido da página).
• Universalidade Real com Perfis de Framework:
  • Perfil generic: Opera sobre qualquer aplicação web baseada em HTML5 padrão.
  • Perfil odoo: Especializado em ecossistemas Odoo (versões 16 a 19 e OWL Framework), com sincronização inteligente com o loader .o_loading, detecção de modais .o_dialog e captura de erros silenciosos.
• Navegação Declarativa e Ações Semânticas em YAML: Escreva cenários de teste sem código Playwright complexo e use ações cognitivas em linguagem natural como ai_click, ai_fill e ai_assert com auto-recuperação (Self-Healing).
• Auditoria Rigorosa por IA (Mixture of Evaluators & Árbitro Reverso):
  • 🌐 Linguist Agent (i18n): Detecta botões, mensagens, abas e labels em inglês em telas brasileiras, respeitando glossário corporativo.
  • 🚫 Leakage Sentinel: Identifica identificadores de banco em snake_case (ex: user_id, created_at), IDs crus, prefixos de framework (x_studio_) e stacktraces.
  • 📐 Layout & Modal Agent: Avalia centralização, botões de ação cortados no rodapé, overflow e quebras de viewport.
  • 📋 Domain QA Agent: Valida cognitivamente o comportamento de negócio esperado contra o que está visível.
  • ⚖️ Devil's Advocate Arbiter: Árbitro reverso que desafia apontamentos críticos para garantir assertividade acima de 95% e eliminação de falsos positivos.
• Baseline Visual com Slider Comparativo (Antes vs Depois): Detecção automática de regressões visuais pixel a pixel com componente interativo split-view deslizante (estilo Percy/Applitools) e atualização rápida com --update-baseline.
• Auditoria de Acessibilidade com Axe-Core (WCAG 2.2 AA): Motor determinístico Axe-Core integrado (--axe) com cálculo de A11y Score (0 a 100%) e catálogo de violações com nós DOM afetados.
• Auditoria de Responsividade Multi-Viewport: Teste em matriz de resoluções (--viewports desktop,tablet,mobile ou customizadas como 1920x1080) com filtros no relatório.
• Gravação Nativa de Sessão em Vídeo e GIF: Gravação integral da navegação em vídeo (--video) com player HTML5 acoplado e anexo automático no Jira.
• Inteligência Artificial Flexível: Alternância transparente via CLI (-p) ou config.yaml entre:
  • APIs Cloud: Anthropic Claude, OpenAI GPT-4o, Google Gemini.
  • Modelos Locais (On-Premise): Ollama com Qwen2-VL ou LLaVA (privacidade total sem envio para nuvens externas).
  • Gateways Corporativos com SSO: Proxies com tokens corporativos e headers customizados.
• Relatórios Duplos Ricos: Gera tanto o Dashboard HTML interativo quanto o documento Markdown (.md) formatado e alinhado especificamente para os editores MarkText e Obsidian.
• Padrão PyPI & PEPs: Estruturado conforme PEP 517/518/621 no pyproject.toml, utilizando Python 3.12 nativo e formatado via Ruff.

---

📋 Requisitos do Sistema

• Sistema Operacional: Linux, macOS ou Windows.
• Python: Versão 3.12 ou superior (com ambiente virtual dedicado).
• Navegadores: Chromium (gerenciado automaticamente pelo Playwright).

---

🚀 Instalação Passo a Passo

O projeto utiliza o ambiente virtual configurado na pasta ambiente/:

1. Clonar e Acessar o Repositório

git clone <url-do-repositorio> UXSentinel
cd UXSentinel

2. Criar e Ativar o Ambiente Virtual (Python 3.12)

Caso a pasta ambiente/ ainda não exista:

python3.12 -m venv ambiente

Ative o ambiente (ou execute os binários diretamente via ambiente/bin/python3):

source ambiente/bin/activate
# No Windows: ambiente\Scripts\activate

3. Instalar as Dependências do Projeto

ambiente/bin/pip install -r requirements.txt
ambiente/bin/pip install -e .

4. Instalar o Navegador Chromium do Playwright

ambiente/bin/playwright install chromium

---

🐳 Execução em Container com Ubuntu Desktop (noVNC)

Se você preferir executar o UXSentinel de forma 100% isolada em container Docker sem instalar dependências no host, incluímos um ambiente completo com Ubuntu 24.04 Desktop (XFCE4 + noVNC):

1. Iniciar o Container

docker compose up -d

2. Acompanhar a Interface Gráfica no Navegador

Abra no seu navegador web: 👉 http://localhost:6080/vnc.html (clique em Connect)
(Ou utilize um cliente VNC nativo em localhost:5901)

3. Disparar Cenários pelo Terminal do Container

# Executa o agente abrindo o Chromium na tela do Desktop virtual:
docker exec -it uxsentinel_desktop uxsentinel --scenario scenarios/exemplo_web_geral.yaml --slowmo 350

Os relatórios e capturas gerados dentro do container serão salvos automaticamente na pasta ./scenarios/report do seu computador.

---

⚙️ Configuração Sem Privilégios de Administrador (Sem Sudo)

Ao instalar via pip install uxsentinel, você não precisa de sudo para configurar o agente. A configuração do usuário fica localizada no diretório padrão XDG: 👉 ~/.config/uxsentinel/config.yaml

1. Inicializar a Configuração Padrão do Usuário

Execute em qualquer terminal:

uxsentinel --init-config

(Esse comando cria automaticamente a pasta ~/.config/uxsentinel/ e o arquivo config.yaml pronto para edição, caso ainda não existam).

2. Prioridade de Carregamento de Configuração:

1. Argumento explícito: --config /caminho/meu_config.yaml
2. Variável de ambiente: export UXSENTINEL_CONFIG_PATH=/meu/caminho
3. Configuração do Projeto Alvo (se existir no diretório atual): ./uxsentinel.yaml, ./.uxsentinel.yaml ou ./config/config.yaml
4. Configuração Global do Usuário: ~/.config/uxsentinel/config.yaml (sem sudo)

No arquivo de configuração, você pode definir o provedor de IA ativo, opções de viewport e delay visual:

# Provedor ativo: anthropic_cloud, openai_cloud, gemini_cloud, ollama_local ou corporate_gateway
active_provider: "anthropic_cloud"
fallback_provider: "ollama_local"

browser:
  headless: false              # 'false' para acompanhar o browser abrindo na tela
  slow_mo_ms: 350              # Delay em milissegundos entre passos (ritmo humano)
  viewport:
    width: 1440
    height: 900
  highlight_clicks: true       # Efeito visual no ponto do clique

reporting:
  output_dir: "scenarios/report"
  generate_html: true
  generate_json: true

2. Configuração de Chaves de IA (Opcional)

Se você for utilizar provedores de IA Cloud pagos (Anthropic Claude, OpenAI, Gemini), você pode salvar suas chaves diretamente no seu arquivo de configuração ~/.config/uxsentinel/config.yaml ou exportá-las no seu shell:

export GEMINI_API_KEY="AIzaSy..."
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-api03-..."

---

🧠 Suporte a Múltiplos Provedores de IA (Gemini, Claude, GPT, Ollama)

O UXSentinel permite alternar com total liberdade entre diferentes modelos de visão multimodal, garantindo flexibilidade de custos, precisão e privacidade.

📋 Catálogo de Provedores Mapeados

Provedor	Identificador no UXSentinel	Modelo Padrão	Protocolo / Integração
Google Gemini Cloud	gemini_cloud	gemini-1.5-pro	REST API Google Gemini com API Key
Google Gemini SSO	gemini_sso	gemini-1.5-pro	Google Gemini via OAuth2 / Bearer Token SSO corporativo
Anthropic Claude Cloud	anthropic_cloud	claude-3-5-sonnet-latest	REST API Anthropic Messages com API Key
Anthropic Claude SSO	claude_sso	claude-3-5-sonnet-latest	Anthropic Messages via OAuth2 / Bearer Token SSO corporativo
OpenAI GPT	openai_cloud	gpt-4o	REST API OpenAI Chat Completions com Vision
Ollama Local	ollama_local	qwen2-vl:7b ou llava	Endpoint local /api/generate (Privacidade 100% local)
vLLM / Compatível	vllm_local	Qwen/Qwen2-VL-7B	API local compatível com padrão OpenAI Chat
Gateway Corporativo	corporate_gateway	Customizado	SSO / Headers empresariais customizados

---

🎯 Formas de Seleção e Ordem de Precedência

O UXSentinel adota a seguinte ordem de precedência para definir qual modelo auditará a tela:

1. Flag na Linha de Comando (-p / --provider) (prioridade máxima)
2. Campo provider dentro do arquivo .yaml do cenário
3. Configuração ativa do usuário (~/.config/uxsentinel/config.yaml)

1. Via Linha de Comando (CLI)

Defina o provedor diretamente ao disparar o teste:

# Executar auditoria visual com Google Gemini Cloud (API Key)
uxsentinel -s scenarios/meu_cenario.yaml -p gemini_cloud

# Executar com Google Gemini via SSO Corporativo (Bearer Token OAuth2)
uxsentinel -s scenarios/meu_cenario.yaml -p gemini_sso

# Executar com Anthropic Claude Cloud (API Key)
uxsentinel -s scenarios/meu_cenario.yaml -p anthropic_cloud

# Executar com Anthropic Claude via SSO Corporativo (Bearer Token OAuth2)
uxsentinel -s scenarios/meu_cenario.yaml -p claude_sso

# Executar com OpenAI GPT-4o
uxsentinel -s scenarios/meu_cenario.yaml -p openai_cloud

# Executar 100% localmente sem envio de dados para fora (Ollama)
uxsentinel -s scenarios/meu_cenario.yaml -p ollama_local

2. Definido Diretamente no Arquivo de Cenário (.yaml)

Se um cenário específico exigir um modelo com características particulares, defina provider no cabeçalho:

version: "1.0"
id: "auditoria_faturamento"
title: "Auditoria Visual do Módulo Financeiro"
profile: "generic"
provider: "gemini_sso"   # <-- Fixa o uso do Gemini SSO para este cenário

variables:
  base_url: "https://sistema.exemplo.com.br"

steps:
  - action: "goto"
    url: "{{ base_url }}/financeiro"
  - action: "inspect_visual"
    checkpoint: "validacao_dashboard"
    expected: "Gráficos de receita visíveis e sem textos em inglês"

3. No Arquivo de Configuração Global (~/.config/uxsentinel/config.yaml)

Você pode definir os modelos padrão e suas respectivas chaves de API ou tokens de SSO:

active_provider: "gemini_sso"        # Provedor principal
fallback_provider: "ollama_local"    # Contingência automática

providers:
  gemini_cloud:
    type: "api"
    service: "gemini"
    model: "gemini-1.5-pro"
    api_key: "${GEMINI_API_KEY}"
    temperature: 0.1
    max_tokens: 2000

  gemini_sso:
    type: "sso"
    service: "gemini"
    model: "gemini-1.5-pro"
    api_key: "${GEMINI_SSO_TOKEN}"
    headers:
      Authorization: "Bearer ${GEMINI_SSO_TOKEN}"
    temperature: 0.1
    max_tokens: 2000

  anthropic_cloud:
    type: "api"
    service: "anthropic"
    model: "claude-3-5-sonnet-latest"
    api_key: "${ANTHROPIC_API_KEY}"
    temperature: 0.1
    max_tokens: 2000

  claude_sso:
    type: "sso"
    service: "anthropic"
    model: "claude-3-5-sonnet-latest"
    api_key: "${CLAUDE_SSO_TOKEN}"
    headers:
      Authorization: "Bearer ${CLAUDE_SSO_TOKEN}"
    temperature: 0.1
    max_tokens: 2000

  openai_cloud:
    type: "api"
    service: "openai"
    model: "gpt-4o"
    api_key: "${OPENAI_API_KEY}"
    temperature: 0.1
    max_tokens: 2000

  ollama_local:
    type: "local"
    service: "ollama"
    base_url: "http://localhost:11434"
    model: "qwen2-vl:7b"
    temperature: 0.1
    timeout: 60

---

🛡️ Fallback Automático de Alta Disponibilidade

Caso o provedor principal sofra falha de rede, timeout ou atinja o limite de requisições (rate limit da API), o UnifiedVisionClient do UXSentinel automaticamente aciona o fallback_provider configurado (padrão: ollama_local), garantindo que seus testes não sejam interrompidos.

---

🕹️ Como Usar

Você pode executar o agente via ambiente/bin/python3 main.py ou diretamente através do comando de pacote uxsentinel.

🏢 Executando o UXSentinel a Partir de Qualquer Projeto Cliente

O UXSentinel foi projetado para analisar aplicações a partir da própria pasta do projeto alvo (por exemplo, na pasta de módulos do Odoo da Gotryx, ou no repositório de um portal React/Django):

1. Coloque os cenários dentro do projeto cliente: Crie uma pasta scenarios/ na raiz do projeto alvo (ex: /caminho/meu-projeto/scenarios/fluxo_vendas.yaml). As URLs e credenciais de acesso ficam gravadas diretamente dentro do próprio arquivo .yaml do cenário, sem exigir nenhum .env.

2. Regras Obrigatórias de Resolução de Cenário:

   • Argumento Explícito: Você pode passar o cenário pela flag -s / --scenario ou como argumento posicional direto:

     uxsentinel -s scenarios/fluxo_vendas.yaml
     uxsentinel scenarios/fluxo_vendas.yaml
     

   • Execução Sem Argumento (uxsentinel):
     • O UXSentinel verifica se o diretório scenarios/ existe na pasta atual.
     • ❌ Se a pasta scenarios/ NÃO existir (ou estiver vazia): O comando aborta com erro orientando você a fornecer o caminho do cenário ou criar a pasta.
     • ❌ Se a pasta scenarios/ contiver MÚLTIPLOS cenários: O comando aborta com erro para evitar ambiguidades, exigindo que você informe qual cenário deseja rodar ou use uxsentinel --list-scenarios.
     • ✅ Se a pasta scenarios/ contiver EXATAMENTE 1 cenário: O UXSentinel detecta e executa automaticamente esse único cenário!

3. Relatórios Salvos Localmente:

   • O dashboard visual HTML e as capturas são salvos automaticamente dentro da pasta scenarios/report/ do próprio projeto cliente!

---

1. Consultar a Versão Instalada

uxsentinel --version   # ou: uxsentinel -v

2. Listar os Cenários Disponíveis

Exibe os cenários do projeto local onde você está e os cenários da biblioteca interna:

uxsentinel --list-scenarios

3. Executar um Cenário no Navegador Visível (Padrão)

A janela do Chromium se abrirá na tela e você acompanhará cada ação com cursor animado e destaques visuais:

uxsentinel -s scenarios/meu_cenario.yaml
# Ou passando diretamente como argumento:
uxsentinel scenarios/meu_cenario.yaml

4. Customizar o Diretório de Relatórios (-o / --output-dir / --report-dir)

Por padrão, relatórios e screenshots são salvos em scenarios/report/. Caso queira salvar em outro local, use o parâmetro opcional:

# Salvar em uma pasta específica:
uxsentinel -s scenarios/meu_cenario.yaml -o ./meus_relatorios/qa
# Ou usando --report-dir:
uxsentinel -s scenarios/meu_cenario.yaml --report-dir /tmp/uxsentinel_reports

5. Executar Cenário Especializado para Odoo (OWL)

Aguardando estabilização do loader .o_loading e modais OWL:

uxsentinel -s scenarios/cenario_odoo.yaml --profile odoo

6. Ajustar a Velocidade do Acompanhamento Visual (--slowmo)

Para apresentações ou auditorias minuciosas, aumente o delay (ex: 500ms):

uxsentinel -s scenarios/meu_cenario.yaml --slowmo 500

7. Alternar o Provedor de IA via Linha de Comando (-p / --provider)

Substitua o provedor na hora da execução sem mexer no arquivo de configuração:

# Usar Google Gemini via SSO Corporativo (Bearer Token)
uxsentinel -s scenarios/meu_cenario.yaml -p gemini_sso

# Usar Anthropic Claude via SSO Corporativo (Bearer Token)
uxsentinel -s scenarios/meu_cenario.yaml -p claude_sso

# Usar Google Gemini 1.5 Pro via Cloud API Key
uxsentinel -s scenarios/meu_cenario.yaml -p gemini_cloud

# Usar Anthropic Claude 3.5 Sonnet via Cloud API Key
uxsentinel -s scenarios/meu_cenario.yaml -p anthropic_cloud

# Usar OpenAI GPT-4o
uxsentinel -s scenarios/meu_cenario.yaml -p openai_cloud

# Usar inferência local com Ollama (100% privado, sem nuvem)
uxsentinel -s scenarios/meu_cenario.yaml -p ollama_local

8. Testar Conexão com o Provedor de IA (--check-ai)

Você pode validar se o provedor de IA e suas credenciais estão funcionando antes de disparar qualquer teste:

# Testa a conectividade com o provedor configurado como ativo:
uxsentinel --check-ai

# Testa especificamente o Google Gemini via SSO:
uxsentinel --check-ai -p gemini_sso

# Testa o Anthropic Claude via SSO corporativo:
uxsentinel --check-ai -p claude_sso

# Testa a instância local do Ollama:
uxsentinel --check-ai -p ollama_local

9. Autenticação SSO Interativa no Navegador (--login-sso)

Quando for utilizar modelos corporativos via SSO (gemini_sso, claude_sso ou gateways internos), o UXSentinel abre o navegador para permitir a autenticação rápida e segura:

# Abre o navegador padrão para login SSO no Google Gemini:
uxsentinel --login-sso -p gemini_sso

# Abre o navegador padrão para login SSO no Anthropic Claude:
uxsentinel --login-sso -p claude_sso

# Limpa o token salvo em cache (logout):
uxsentinel --logout-sso

(O token é gravado com permissões restritas em ~/.config/uxsentinel/sso_cache.json e reaproveitado automaticamente nos próximos testes sem exigir novo login).

10. Executar em Background / Modo Headless (Esteiras CI/CD)

uxsentinel -s scenarios/meu_cenario.yaml --headless
# Ou utilizando os aliases equivalentes:
uxsentinel -s scenarios/meu_cenario.yaml --no-gui

11. Inspecionar ao Vivo com DevTools / Console do Chromium Acoplado (--devtools)

Quando você precisa depurar erros de JavaScript, avisos, exceções não tratadas ou falhas de requisições HTTP (4xx e 5xx), ative o DevTools acoplado ao navegador:

uxsentinel -s scenarios/meu_cenario.yaml --devtools
# Ou utilizando os aliases equivalentes:
uxsentinel -s scenarios/meu_cenario.yaml --console
uxsentinel -s scenarios/meu_cenario.yaml --inspect

(O agente inicia o Chromium com o painel de desenvolvedor aberto e coleta automaticamente todos os logs da aplicação, falhas de endpoints e métricas de carregamento W3C Navigation Timing).

12. Gerar Relatório em Markdown para MarkText e Obsidian (--md / --markdown)

Gera um documento .md puro, perfeitamente compatível com o editor visual MarkText e o Obsidian:

uxsentinel -s scenarios/meu_cenario.yaml --md
# Ou:
uxsentinel -s scenarios/meu_cenario.yaml --markdown

(O arquivo gerado em scenarios/report/<id>_report.md contém tabelas GFM alinhadas, badges visuais, tabela de métricas W3C, logs de console e violações WCAG 2.2 formatadas em pt-BR).

13. Auditoria de Responsividade Multi-Viewport (--viewports)

Valide a responsividade da sua aplicação em múltiplos dispositivos e resoluções na mesma execução:

# Executa nos presets Desktop (1440x900), Tablet (768x1024) e Mobile (375x812):
uxsentinel -s scenarios/meu_cenario.yaml --viewports desktop,tablet,mobile

# Ou com resoluções customizadas no formato LARGURAxALTURA:
uxsentinel -s scenarios/meu_cenario.yaml --viewports 1920x1080,1280x720,375x812

14. Baseline Visual com Slider Comparativo Antes vs Depois (--update-baseline)

Para proteger telas contra qualquer quebra acidental de layout, aprove ou compare capturas com a baseline de referência:

# 1. Homologar e salvar os screenshots atuais como nova referência visual (baseline):
uxsentinel -s scenarios/meu_cenario.yaml --update-baseline

# 2. Em execuções seguintes, o agente compara pixel a pixel automaticamente:
uxsentinel -s scenarios/meu_cenario.yaml

# 3. É possível ajustar o limiar percentual de tolerância visual (padrão: 0.1%):
uxsentinel -s scenarios/meu_cenario.yaml --diff-threshold 0.5

(No relatório HTML, um componente interativo split-view slider estilo Percy/Applitools permite arrastar a barra divisória para comparar a imagem de referência contra a tela atual).

15. Gravação Integral da Sessão em Vídeo (--video)

Grave um vídeo completo de toda a navegação do agente para apresentações, evidências ou compliance:

uxsentinel -s scenarios/meu_cenario.yaml --video

(O vídeo em formato .webm é salvo no diretório de relatórios e disponibilizado em um player HTML5 no topo do dashboard).

16. Auditoria de Acessibilidade com Axe-Core WCAG 2.2 AA (--axe)

Execute uma varredura determinística de acessibilidade web de padrão mundial:

uxsentinel -s scenarios/meu_cenario.yaml --axe

(Mede o A11y Score de 0 a 100% e cataloga violações de contraste, atributos aria, rótulos e estrutura de tags).

17. Integração e Abertura Automática de Cards no Jira (--jira)

Crie cards/issues automaticamente no Jira para inconformidades encontradas durante o teste:

# Configuração interativa de credenciais e URL do Jira:
uxsentinel --set-jira-token

# Executar criando cards no projeto especificado:
uxsentinel -s scenarios/meu_cenario.yaml --jira --jira-project PROJ

18. Gerar Prompt de Correção para IAs (--fix-prompt)

Gera um documento Markdown contendo instruções técnicas prontas para colar em ferramentas como Claude Code, Cursor ou Copilot:

uxsentinel -s scenarios/meu_cenario.yaml --fix-prompt

---

📝 Como Criar um Novo Cenário de Teste (YAML)

Crie um arquivo .yaml dentro de uxsentinel/scenarios/library/meu_fluxo.yaml:

version: "1.0"
id: "emissao_fatura_cliente"
title: "Fluxo de Emissão de Fatura e Verificação de Modal"
profile: "generic"    # 'generic' ou 'odoo'
tags: ["financeiro", "faturamento"]

env:
  base_url: "${APP_BASE_URL:-http://localhost:8000}"

steps:
  - action: "goto"
    url: "${base_url}/invoices/new"
    description: "Navega para a tela de nova fatura"

  - action: "fill"
    selector: "input#cliente_nome"
    value: "Empresa de Demonstração Ltda"
    description: "Informa o cliente"

  - action: "click"
    selector: "button#btn-emitir"
    description: "Clica para emitir"

  - action: "wait_modal"
    timeout: 8000
    description: "Aguarda abertura do modal de confirmação"

  # Checkpoint onde o agente para, fotografa e audita com IA
  - action: "checkpoint"
    name: "modal_confirmacao_emissao"
    description: "Auditoria do modal de confirmação de fatura"
    expected_behavior: >
      O modal de confirmação deve abrir centralizado, sem sobreposição de campos.
      O valor total da fatura e os botões 'Confirmar Envio' e 'Cancelar' devem estar
      visíveis no rodapé. Nenhum texto em inglês deve ser exibido.

Ações Suportadas no Roteiro:

• goto: Navega até a URL especificada.
• click: Clica em um seletor CSS com efeito luminoso.
• fill: Preenche texto em um input ou textarea.
• select: Seleciona opção em listas dropdown (<select>).
• press: Dispara tecla física (ex: Enter, Escape, Tab).
• hover: Passa o mouse sobre um elemento para abrir tooltips ou menus.
• scroll: Rola a página (direction: "down" ou "up").
• wait_until_ready: Aguarda o término de requisições ativas e loaders.
• wait_modal: Aguarda a renderização de diálogos/modais.
• wait_modal_close: Aguarda o fechamento completo do modal.
• pause: Pausa temporária em segundos para visualização.
• checkpoint: Ponto de inspeção visual, captura de tela e julgamento pela IA.
• ai_click: Clique inteligente resolvido por acessibilidade e visão em linguagem natural com auto-recuperação (ex: ai_click: "o botão azul de salvar").
• ai_fill: Preenchimento semântico em linguagem natural (ex: ai_fill: "campo de e-mail do cliente", value: "admin@empresa.com").
• ai_assert: Asserção declarativa visual avaliada cognitivamente pelo modelo multimodal.

---

📊 Relatórios de Execução

Ao término de cada execução, os resultados são salvos no diretório configurado (padrão: scenarios/report/ ou no caminho passado via -o / --report-dir):

1. Dashboard Visual HTML (scenarios/report/<id>_report.html):
   • Página interativa independente e responsiva com galeria de capturas de tela.
   • Painel de telemetria W3C: Tempos de carregamento (TTFB, Dom Interactive, Page Load) e tamanho transferido.
   • Painel de Console & Rede: Logs de JavaScript (error, warn, info) e falhas de requisição HTTP (status 4xx/5xx).
   • Componente interativo split-view slider "Antes vs Depois" para comparação de baseline visual.
   • Player de vídeo HTML5 integrado para reprodução da sessão gravada.
   • Gauge e catálogo completo de acessibilidade Axe-Core (WCAG 2.2 AA).
   • Detalhamento de cada checkpoint com categorização de severidade (Bloqueante, Alta, Média, Baixa) e recomendações acionáveis.
2. Relatório em Markdown Puro para MarkText e Obsidian (scenarios/report/<id>_report.md):
   • Formatado estritamente para os editores MarkText e Obsidian.
   • Tabelas CommonMark/GFM alinhadas com cabeçalhos estruturados.
   • Seção dedicada de Telemetria de Carregamento W3C e Console Logs.
   • Catálogo de acessibilidade WCAG 2.2 formatado em português.
   • Imagens de checkpoints e evidências visuais referenciadas com caminhos relativos portáveis.
3. Gravação de Vídeo da Sessão (scenarios/report/videos/<id>_session.webm):
   • Arquivo de vídeo completo reproduzindo todo o percurso e interações do agente.
4. Relatório Estruturado JSON (scenarios/report/<id>_report.json):
   • Contém métricas brutas, timestamps, contagem de falhas e telemetria para fácil integração com esteiras de CI/CD (GitHub Actions, GitLab CI, Jenkins).
5. Screenshots em Alta Resolução (scenarios/report/<id>_<checkpoint>.png):
   • Imagens completas capturadas no momento exato de cada checkpoint.

---

🛡️ Qualidade de Código, PEPs e Linter Ruff

O projeto segue estritamente as convenções das PEPs do Python 3.12 e utiliza o Ruff com configuração dedicada no arquivo ruff.toml:

# Verificar regras de linting (PEP 8, isort, pyupgrade, bugbear)
ambiente/bin/ruff check .

# Aplicar correções automáticas
ambiente/bin/ruff check --fix .

# Aplicar formatação de código no padrão PEP 8
ambiente/bin/ruff format .

# Validar se o código já está perfeitamente formatado
ambiente/bin/ruff format --check .

---

🧪 Executar Testes Internos do Motor

Para validar todos os componentes (configurações, parsers, geradores de relatórios e Playwright) com o interpretador do venv:

ambiente/bin/python3 tests/test_engine.py

---

📚 Documentação Técnica Completa

Para aprofundar na arquitetura e especificações do projeto, consulte a pasta docs/:

Documento	Assunto
📖 01. Visão Geral e Arquitetura Universal	Arquitetura em camadas, fluxo de orquestração e neutralidade de frameworks.
🔍 02. Heurísticas Universais de QA e UX	Critérios de i18n, prevenção de jargões técnicos, geometria de modais e severidades.
🕹️ 03. Motor do Agente: Navegação e Visão	Modo visível, highlights em tela, estabilização assíncrona e loop de IA.
📝 04. Especificação de Cenários (YAML)	Sintaxe dos arquivos de teste e definição de checkpoints de regras de negócio.
🤖 05. Configuração de LLMs e Provedores	Especificação do config.yaml para alternar entre Cloud, Local (Ollama) e SSO/Gateway.
🔌 06. Perfis e Plugins de Frameworks	Detalhes do perfil universal e do plugin especializado para Odoo (OWL).
🚀 07. Guia de Releases e PyPI	Guia oficial para criar releases no GitHub e publicação automatizada no PyPI.
🤖 Skill do Projeto (.gemini/skills)	Skill interna para agentes de IA atuarem com máxima consistência no repositório.