vercel-labs/dogfood

Dogfood (Teste Exploratório)

Explore sistematicamente uma aplicação web, encontre problemas e produza um relatório com evidências completas de reprodução para cada descoberta.

Configuração

Apenas a URL de Destino é obrigatória. Todo o resto tem valores padrão sensatos — use-os, a menos que o usuário forneça explicitamente uma substituição.

Parâmetro	Padrão	Substituição de exemplo
URL de Destino	(obrigatório)	vercel.com, http://localhost:3000
Nome da Sessão	Domínio slugificado (ex.: vercel.com -> vercel-com)	--session minha-sessao
Diretório de Saída	./dogfood-output/	Diretório de saída: /tmp/qa
Escopo	Aplicação completa	Foco na página de cobrança
Autenticação	Nenhum	Faça login em [email protected]

Se o usuário disser algo como "dogfood vercel.com", inicie imediatamente com os padrões. Não faça perguntas de esclarecimento, a menos que a autenticação seja mencionada, mas as credenciais estejam faltando.

Sempre use agent-browser diretamente — nunca npx agent-browser. O binário direto usa o cliente Rust rápido. O npx roteia pelo Node.js e é significativamente mais lento.

Fluxo de Trabalho

1. Inicializar     Configurar sessão, diretórios de saída, arquivo de relatório
2. Autenticar      Fazer login se necessário, salvar estado
3. Orientar        Navegar até o ponto de partida, tirar snapshot inicial
4. Explorar        Visitar páginas sistematicamente e testar funcionalidades
5. Documentar      Capturar tela e gravar cada problema conforme encontrado
6. Finalizar       Atualizar contagens de resumo, fechar sessão

1. Inicializar

mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos

Copie o template do relatório para o diretório de saída e preencha os campos do cabeçalho:

cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md

Inicie uma sessão nomeada:

agent-browser --session {SESSION} open {TARGET_URL}
agent-browser --session {SESSION} wait --load domcontentloaded

2. Autenticar

Se a aplicação exigir login:

agent-browser --session {SESSION} snapshot -i
# Identifique as referências do formulário de login, preencha credenciais
agent-browser --session {SESSION} fill @e1 "{EMAIL}"
agent-browser --session {SESSION} fill @e2 "{SENHA}"
agent-browser --session {SESSION} click @e3
# Substitua pela URL pós-login, texto ou condição JS da aplicação alvo:
agent-browser --session {SESSION} wait --url "{POST_LOGIN_URL_PATTERN}"
# Ou:
# agent-browser --session {SESSION} wait --text "{POST_LOGIN_TEXT}"
# agent-browser --session {SESSION} wait --fn "{POST_LOGIN_CONDITION}"

Para códigos OTP/e-mail: pergunte ao usuário, aguarde a resposta e insira o código.

Após o login bem-sucedido, salve o estado para possível reutilização:

agent-browser --session {SESSION} state save {OUTPUT_DIR}/auth-state.json

3. Orientar

Tire uma captura de tela anotada inicial e um snapshot para entender a estrutura da aplicação:

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/initial.png
agent-browser --session {SESSION} snapshot -i

Identifique os principais elementos de navegação e mapeie as seções a visitar.

4. Explorar

Leia references/issue-taxonomy.md para a lista completa do que procurar e a lista de verificação de exploração.

Estratégia — trabalhe na aplicação sistematicamente:

• Comece pela navegação principal. Visite cada seção de nível superior.
• Dentro de cada seção, teste elementos interativos: clique em botões, preencha formulários, abra menus suspensos/modais.
• Verifique casos de borda: estados vazios, tratamento de erros, entradas de limite.
• Tente fluxos de trabalho realistas de ponta a ponta (criar, editar, excluir).
• Verifique o console do navegador periodicamente em busca de erros.

Em cada página:

agent-browser --session {SESSION} snapshot -i
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/{nome-da-pagina}.png
agent-browser --session {SESSION} errors
agent-browser --session {SESSION} console

Use seu julgamento sobre quão fundo ir. Gaste mais tempo em funcionalidades principais e menos em páginas periféricas. Se encontrar um grupo de problemas em uma área, investigue mais a fundo.

5. Documentar Problemas (Reprodução Primeiro)

As etapas 4 e 5 acontecem juntas — explore e documente em uma única passagem. Quando encontrar um problema, pare de explorar e documente-o imediatamente antes de continuar. Não explore toda a aplicação primeiro e documente depois.

Cada problema deve ser reproduzível. Quando encontrar algo errado, não apenas anote — prove com evidências. O objetivo é que alguém lendo o relatório possa ver exatamente o que aconteceu e repeti-lo.

Escolha o nível certo de evidência para o problema:

Problemas interativos/comportamentais (funcionais, UX, erros de console em ação)

Esses exigem interação do usuário para reproduzir — use reprodução completa com vídeo e capturas de tela passo a passo:

1. Inicie um vídeo de reprodução antes de reproduzir:

agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm

2. Percorra as etapas no ritmo humano. Pause 1-2 segundos entre as ações para que o vídeo seja assistível. Tire uma captura de tela em cada etapa:

agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
sleep 1
# Realize a ação (clicar, preencher etc.)
sleep 1
agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
sleep 1
# ...continue até o problema se manifestar

3. Capture o estado quebrado. Pause para que o visualizador possa vê-lo e tire uma captura de tela anotada:

sleep 2
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png

4. Pare o vídeo:

agent-browser --session {SESSION} record stop

5. Escreva etapas de reprodução numeradas no relatório, cada uma referenciando sua captura de tela.

Problemas estáticos/visíveis no carregamento (erros de digitação, texto placeholder, texto cortado, desalinhamento, erros de console no carregamento)

Estes são visíveis sem interação — uma única captura de tela anotada é suficiente. Sem vídeo, sem reprodução de várias etapas:

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png

Escreva uma breve descrição e faça referência à captura de tela no relatório. Defina Vídeo de Reprodução como N/A.

---

Para todos os problemas:

1. Anexe ao relatório imediatamente. Não agrupe problemas para depois. Escreva cada um conforme o encontra, para que nada seja perdido se a sessão for interrompida.

2. Incremente o contador de problemas (ISSUE-001, ISSUE-002, ...).

6. Finalizar

Procure encontrar 5 a 10 problemas bem documentados e depois finalize. A profundidade da evidência importa mais do que a quantidade total — 5 problemas com reprodução completa valem mais do que 20 com descrições vagas.

Após explorar:

1. Releia o relatório e atualize as contagens de severidade do resumo para que correspondam aos problemas reais. Cada bloco ### ISSUE- deve ser refletido nos totais.
2. Feche a sessão:

agent-browser --session {SESSION} close

3. Informe ao usuário que o relatório está pronto e resuma as descobertas: total de problemas, distribuição por severidade e os itens mais críticos.

Orientação

• Reprodução é tudo. Cada problema precisa de prova — mas combine a evidência com o problema. Bugs interativos precisam de vídeo e capturas de tela passo a passo. Bugs estáticos (erros de digitação, texto placeholder, falhas visuais visíveis no carregamento) precisam apenas de uma única captura de tela anotada.
• Verifique a reprodutibilidade antes de coletar evidências. Antes de gravar vídeo ou tirar capturas de tela, verifique se o problema é reproduzível com pelo menos uma nova tentativa. Se não puder ser reproduzido consistentemente, não é um problema válido.
• Não grave vídeo para problemas estáticos. Um erro de digitação ou texto cortado não se beneficia de um vídeo. Reserve o vídeo para problemas que envolvam interação do usuário, temporização ou mudanças de estado.
• Para problemas interativos, tire capturas de tela de cada etapa. Capture o antes, a ação e o depois — para que alguém possa ver a sequência completa.
• Escreva etapas de reprodução que mapeiem as capturas de tela. Cada etapa numerada no relatório deve fazer referência à sua captura de tela correspondente. Um leitor deve ser capaz de seguir as etapas visualmente sem tocar no navegador.
• Use o comando de snapshot correto.
  • snapshot -i — para encontrar elementos clicáveis/preenchíveis (botões, entradas, links)
  • snapshot (sem sinalizador) — para ler conteúdo da página (texto, cabeçalhos, listas de dados)
• Seja completo, mas use julgamento. Você não está seguindo um script de teste — você está explorando como um usuário real faria. Se algo parecer estranho, investigue.
• Escreva as descobertas incrementalmente. Anexe cada problema ao relatório conforme o descobre. Se a sessão for interrompida, as descobertas são preservadas. Nunca agrupe todos os problemas para o final.
• Nunca exclua arquivos de saída. Não execute rm em capturas de tela, vídeos ou o relatório no meio da sessão. Não feche a sessão e reinicie. Trabalhe para frente, não para trás.
• Nunca leia o código-fonte da aplicação alvo. Você está testando como um usuário, não auditando código. Não leia HTML, JS ou arquivos de configuração da aplicação sob teste. Todas as descobertas devem vir do que você observa no navegador.
• Verifique o console. Muitos problemas são invisíveis na interface, mas aparecem como erros de JS ou requisições com falha.
• Teste como um usuário, não como um robô. Tente fluxos de trabalho comuns de ponta a ponta. Clique em coisas que um usuário real clicaria. Insira dados realistas.
• Digite como um humano. Ao preencher campos de formulário durante a gravação de vídeo, use type em vez de fill — ele digita caractere por caractere. Use fill apenas fora da gravação de vídeo, quando a velocidade importa.
• Espaçe os vídeos de reprodução para humanos. Adicione sleep 1 entre as ações e sleep 2 antes da captura de tela do resultado final. Os vídeos devem ser assistíveis em velocidade 1x — um humano revisando o relatório precisa ver o que aconteceu, não um borrão de mudanças instantâneas de estado.
• Seja eficiente com comandos. Agrupe múltiplos comandos agent-browser em uma única chamada de shell quando forem independentes (ex.: agent-browser ... screenshot ... && agent-browser ... console). Use agent-browser --session {SESSION} scroll down 300 para rolar — não use key ou evaluate para rolar.

Referências

Referência	Quando Ler
references/issue-taxonomy.md	Início da sessão — calibrar o que procurar, níveis de severidade, lista de verificação de exploração

Templates

Modelo	Propósito
templates/dogfood-report-template.md	Copiar para o diretório de saída como o arquivo de relatório