blackbox-qa-agent

O que blackbox-qa-agent faz?

Agente de QA blackbox autônomo para Claude Code. Realiza auditoria de cada rota × viewport × navegador do seu web app, detecta defeitos e cria tickets de bug no Azure DevOps com capturas de tela anotadas.

Visão Geral

O blackbox-qa-agent é uma skill do Claude Code que transforma o Claude em um engenheiro de QA autônomo. Ele navega sistematicamente por todas as rotas definidas do seu aplicativo web, testa em múltiplas viewports e navegadores, tira screenshots, compara com capturas de referência para detectar regressões visuais e relata defeitos diretamente no Azure DevOps.

Funcionalidades

• Auditoria de Rotas: Testa automaticamente todas as rotas configuradas do seu aplicativo.
• Teste Multi-Viewport: Simula diferentes tamanhos de tela (desktop, tablet, mobile) para capturar problemas de responsividade.
• Teste Multi-Navegador: Suporta Chromium, Firefox e WebKit (via Playwright).
• Detecção de Defeitos Visuais: Usa comparação de screenshots para identificar diferenças entre o estado atual e o esperado.
• Anotação de Screenshots: Destaca visualmente as áreas com defeitos nas capturas de tela.
• Integração com Azure DevOps: Cria automaticamente tickets de bug com título, descrição, passos para reproduzir, screenshots anotados e logs do console.
• Configurável: Permite configurar a lista de rotas, viewports, navegadores, e as credenciais do Azure DevOps.

Pré-requisitos

• Claude Code (versão mais recente)
• Node.js (v18 ou superior)
• Uma conta no Azure DevOps
• Um Personal Access Token (PAT) do Azure DevOps com permissão para criar itens de trabalho

Instalação

1. Certifique-se de ter o Claude Code instalado e configurado.

2. Em um diretório de projeto, execute:

   claude add skill Luqman-Ud-Din/blackbox-qa-agent
   

3. Configure as variáveis de ambiente (veja a seção de Configuração).

Configuração

Defina as seguintes variáveis de ambiente no seu ambiente de execução do Claude Code (por exemplo, no arquivo .env do projeto):

Variável	Descrição	Valor Padrão	Obrigatório
AZURE_ORG_URL	URL da sua organização no Azure DevOps (ex: https://dev.azure.com/sua-org)	-	Sim
AZURE_PROJECT_NAME	Nome do projeto no Azure DevOps	-	Sim
AZURE_PAT	Personal Access Token do Azure DevOps	-	Sim
AZURE_TEAM_AREA_PATH	Caminho da área de equipe (opcional, padrão é o projeto)	Projeto	Não
QA_ROUTES	Lista de rotas a testar, separadas por vírgula (ex: /home,/about,/contact)	/	Não
QA_VIEWPORTS	Lista de viewports no formato larguraxaltura (ex: 1280x720,390x844)	1280x720,390x844	Não
QA_BROWSERS	Lista de navegadores (ex: chromium,firefox,webkit)	chromium	Não
QA_BASE_URL	URL base do aplicativo sob teste (ex: http://localhost:3000)	http://localhost:3000	Não

Uso

Após a instalação e configuração, inicie a auditoria com o seguinte comando no Claude Code:

Iniciar auditoria de QA blackbox.

O Claude irá:

1. Ler as configurações das variáveis de ambiente.
2. Iniciar o navegador (ou navegadores) configurado.
3. Para cada rota × viewport × navegador:
   • Navegar até a URL.
   • Aguardar o carregamento completo da página.
   • Tirar uma screenshot.
   • Comparar com a screenshot de referência (se existir).
   • Se houver diferenças significativas, anotar a screenshot e registrar o defeito.
4. Para cada defeito detectado:
   • Capturar o log do console do navegador (erros e avisos).
   • Criar um ticket de bug no Azure DevOps com:
     • Título: [QA] Defeito visual em {rota} ({viewport}, {navegador})
     • Descrição detalhada com os passos para reproduzir.
     • Screenshot anotado anexado.
     • Logs do console relevantes.
5. Gerar um resumo de toda a auditoria, listando as rotas testadas e os bugs criados.

Exemplo de Saída

Após uma execução bem-sucedida, você verá algo como:

✅ Auditoria de QA concluída.

Rotas testadas: /, /about, /contact
Viewports testadas: 1280x720, 390x844
Navegadores testados: chromium, firefox

Defeitos encontrados:
  1. /about (390x844, chromium) - Botão de chamada para ação sobreposto
  2. /contact (1280x720, firefox) - O formulário não está centralizado

Tickets criados no Azure DevOps: 2

Solução de Problemas

• Erro de autenticação do Azure DevOps: Verifique se o AZURE_PAT está correto e tem as permissões adequadas.
• Navegador não encontrado: Certifique-se de que o Playwright está instalado corretamente (npx playwright install).
• Screenshots não são comparadas: A primeira execução cria as screenshots de referência. Execute novamente para ver as comparações.

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests no repositório do GitHub.

Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para mais detalhes.