dogfood

Overview

What the dogfood skill does

A skill dogfood automatiza testes exploratórios de aplicações web usando o cliente agent-browser. Ela explora de forma sistemática um site ou app alvo, procura defeitos na interface visual, funcionalidade, UX, performance, console e acessibilidade, e produz um relatório de QA estruturado com:

• Títulos e categorias de issues claros
• Níveis de severidade (critical, high, medium, low)
• Passos de reprodução que qualquer pessoa do time consegue seguir
• Screenshots passo a passo
• Vídeos de repro para issues interativas quando necessário

Isso torna dogfood especialmente útil quando pedem para você “dogfoodar”, fazer "QA", "exploratory test", "bug hunt" ou "testar este app/site/plataforma" e você precisa de evidências que possam ser entregues diretamente para engenheiros, designers ou product managers.

Who dogfood is for

Use a skill dogfood se você é:

• QA engineer ou SDET que quer execuções exploratórias repetíveis e evidências ricas de repro.
• Engenheiro frontend ou full‑stack querendo fazer um sanity-check das mudanças antes do release.
• Product manager ou designer que precisa de feedback rápido de UX e UI com exemplos concretos.
• Startup ou time pequeno sem uma função de QA dedicada, mas que ainda precisa de uma forma sistemática de encontrar problemas.

When dogfood is a good fit

Dogfood é uma boa escolha quando:

• O alvo é um app ou site web baseado em browser (domínio público ou localhost).
• Você quer explorar fluxos ponta a ponta em vez de rodar um único teste scriptado.
• Você se importa tanto com acabamento de UX e UI quanto com bugs puramente funcionais.
• Você precisa de saídas fáceis de compartilhar (screenshots, vídeos e relatórios em markdown) que se encaixem no seu fluxo de trabalho atual.

Ela é menos adequada quando:

• O alvo principal é uma API de backend pura sem interface em browser.
• Você só precisa de unit tests ou testes de integração de baixo nível, e não de verificações de comportamento voltadas ao usuário.
• Você precisa de load testing formal ou benchmarks de performance sintéticos além do que a interação exploratória consegue revelar.

How dogfood works at a high level

A partir do repositório vercel-labs/agent-browser, dogfood configura o cliente agent-browser com:

• Uma target URL para abrir no browser
• Session naming, scope e output directory opcionais
• Passos de autenticação opcionais quando for necessário fazer login
• Uma issue taxonomy de referência (references/issue-taxonomy.md) para manter os achados consistentes
• Um report template (templates/dogfood-report-template.md) para estruturar o relatório final de QA

Em seguida, a skill controla o browser para percorrer fluxos-chave de usuário, capturando screenshots e vídeos conforme encontra issues, e registrando tudo em um formato consistente.

How to Use

Prerequisites

Para usar dogfood de forma efetiva, você deve ter:

• Acesso ao cliente agent-browser do repositório vercel-labs/agent-browser
• Uma URL do app ou site que você quer testar, por exemplo https://example.com ou http://localhost:3000
• (Opcional) Credenciais de teste se o app exigir autenticação

A skill foi projetada em torno do binário agent-browser direto mencionado na documentação principal, não de npx agent-browser. Isso garante que você aproveite o client em Rust, mais rápido.

Installing the dogfood skill

Instale a skill no seu ambiente de agent skills com:

npx skills add https://github.com/vercel-labs/agent-browser --skill dogfood

Esse comando baixa a definição da skill dogfood a partir de skills/dogfood no repositório vercel-labs/agent-browser, incluindo:

• SKILL.md – descrição principal e expectativas de runtime
• references/issue-taxonomy.md – como classificar issues de forma consistente
• templates/dogfood-report-template.md – template em markdown para os relatórios finais

Após a instalação, abra a aba Files ou o checkout local para revisar esses arquivos antes da primeira execução.

Core configuration: required and optional inputs

A skill dogfood foi pensada para iniciar rápido com defaults razoáveis, para que você possa começar a testar imediatamente.

Parâmetro obrigatório

• Target URL – o app ou site web que você quer dogfoodar
  Exemplos: vercel.com, https://example.com, http://localhost:3000

Parâmetros opcionais com defaults

• Session name
  Default: domínio convertido em slug (por exemplo, vercel.com → vercel-com)
  Exemplo de override: --session my-first-dogfood-run

• Output directory
  Default: ./dogfood-output/
  Exemplo de override: Output directory: /tmp/qa

• Scope
  Default: app completo
  Exemplo de override: Focus on the billing page, Only test onboarding and settings, Ignore marketing pages

• Authentication
  Default: none
  Exemplo de override: Sign in to user@example.com (você então fornece as credenciais pelo seu canal seguro normal)

Se alguém disser “dogfood vercel.com”, a skill foi feita para começar imediatamente com os defaults. Ela não deve parar para pedir esclarecimentos, a menos que seja preciso fazer login e as credenciais não tenham sido fornecidas.

Typical dogfood workflow

Use a sequência abaixo como ponto de partida confiável para cada app web que você testar:

1. Initialize a dogfood session

Decida o que você quer cobrir e onde guardar os resultados. Por exemplo, você pode:

• Escolher uma target URL (http://localhost:3000 para desenvolvimento local ou um domínio de staging).
• Opcionalmente escolher um session name para diferenciar execuções.
• Opcionalmente customizar o output directory se quiser resultados em uma pasta compartilhada.

Rode seu agent com a skill dogfood habilitada e forneça esses parâmetros no prompt ou na configuração, conforme descrito em SKILL.md.

2. Authenticate if needed

Se o seu app exigir login:

• Forneça instruções claras, por exemplo: Sign in to qa-user@example.com.
• Garanta que credenciais de teste estejam disponíveis pelo seu processo seguro usual.

A skill dogfood vai tratar a autenticação como parte do fluxo exploratório, para que as issues também sejam encontradas em páginas autenticadas.

3. Explore key user journeys

Dentro do escopo selecionado, dogfood controla o browser para percorrer fluxos representativos, como:

• Onboarding ou signup de novos usuários
• Login e gerenciamento de conta
• Ações centrais do produto (criar, editar, excluir entidades)
• Navegação entre seções principais
• Páginas de configurações, billing ou perfil

Durante essa exploração, ela usa a issue taxonomy de references/issue-taxonomy.md para identificar e classificar problemas de forma consistente.

4. Capture issues with evidence

Para cada issue, dogfood busca coletar:

• Um issue title curto e descritivo
• Severity: critical, high, medium, low
• Category: visual, functional, ux, content, performance, console, accessibility
• A URL em que o problema ocorre
• Caminho do Repro video (para issues interativas) ou N/A para falhas estáticas
• Screenshots passo a passo para que qualquer pessoa consiga acompanhar visualmente

A estrutura espelha o formato de templates/dogfood-report-template.md.

5. Generate the dogfood report

Quando a exploração termina, a skill gera um relatório em markdown seguindo templates/dogfood-report-template.md:

• Uma summary table com contagem por severidade
• Uma seção detalhada de Issues, em que cada issue inclui descrição e passos de repro anotados com screenshots

Você pode armazenar esse relatório junto ao codebase, anexá‑lo a tickets ou compartilhá‑lo diretamente com o time.

Customizing dogfood for your workflow

Embora os defaults funcionem direto "out of the box", você pode adaptar dogfood ao seu processo de QA:

• Use um output directory específico do time, por exemplo /tmp/qa ou um volume de rede compartilhado.
• Restrinja o scope para focar em áreas de maior risco, como billing, checkout ou novas features.
• Alinhe as definições de severidade e categorias com seus padrões internos de QA revisando e usando references/issue-taxonomy.md como referência.
• Pós-processe o relatório em markdown gerado para o seu bug tracker copiando issues individuais ou anexando o relatório inteiro.

Files worth reviewing in the repository

Para entender a skill dogfood em profundidade, comece por:

• SKILL.md – a descrição definitiva de como a skill se comporta e quais ferramentas ela pode invocar.
• references/issue-taxonomy.md – define níveis de severidade, categorias e um checklist de exploração, garantindo que seus achados sejam consistentes entre execuções.
• templates/dogfood-report-template.md – mostra exatamente como as issues e o resumo da sessão são formatados no relatório final.

FAQ

Is dogfood a unit test or end-to-end test framework?

Não. A skill dogfood é voltada principalmente para QA exploratório orientado ao usuário em aplicações web. Ela controla um browser via agent-browser para se comportar como um testador humano, explorando fluxos e registrando defeitos com evidências. Ela não substitui unit tests, integration tests ou frameworks em nível de código; em vez disso, complementa essas camadas ao capturar problemas visuais, de UX e de interação.

What kinds of issues can dogfood detect?

Dogfood foi projetada em torno de uma issue taxonomy definida em references/issue-taxonomy.md. Ela incentiva você a registrar problemas como:

• Visual / UI issues – quebras de layout, texto sobreposto, problemas de responsividade, contraste de cor, falhas em ícones ou imagens.
• Functional bugs – links quebrados, botões que não funcionam, formulários com falha, redirects incorretos, perda de estado, problemas de upload/download de arquivos.
• UX issues – navegação confusa, falta de feedback, rótulos pouco claros, interações lentas ou pouco responsivas.
• Content issues – erros de digitação, terminologia inconsistente, textos desatualizados.
• Performance issues – páginas ou interações perceptivelmente lentas observadas durante a exploração.
• Console issues – erros ou warnings no console do browser durante o uso.
• Accessibility issues – ausência de alt text, keyboard traps, foco mal gerenciado e problemas observáveis semelhantes.

Essa taxonomy deixa as sessões com dogfood mais sistemáticas e comparáveis entre execuções.

How do I start a quick dogfood run against a new site?

Quando alguém pedir “dogfood example.com”, você pode:

1. Garantir que a skill dogfood esteja instalada a partir de vercel-labs/agent-browser.
2. Invocar o seu agent com a skill dogfood e fornecer apenas a Target URL.
3. Deixar a skill usar os defaults para session name, scope (app completo) e output directory, a menos que você queira overrides específicos.

A ideia é começar a testar imediatamente, sem uma longa fase de configuração.

Does dogfood require authentication to work?

Não. Dogfood funciona normalmente em sites públicos e páginas de marketing sem qualquer login.

Se o seu app exigir autenticação para fluxos importantes, você deve:

• Mencionar que a autenticação é necessária (por exemplo: Sign in to user@example.com).
• Fornecer credenciais pelo seu canal seguro padrão.

A skill então trata o login como parte da sessão, para que consiga explorar as áreas autenticadas.

Where can I see how issues are categorized and reported?

Dois arquivos importantes no repositório vercel-labs/agent-browser mostram isso:

• references/issue-taxonomy.md – explica os severity levels, as issue categories e traz um exploration checklist.
• templates/dogfood-report-template.md – mostra a estrutura do Dogfood Report, incluindo a summary table e os blocos de issues individuais com campos como Severity, Category, URL, Repro Video, Description e Repro Steps com screenshots.

Revisar esses arquivos antes da primeira execução ajuda você a interpretar e customizar os relatórios produzidos pela skill dogfood.

When is dogfood not the right tool?

A skill dogfood não é ideal quando:

• Você está testando sistemas que não rodam em browser (ferramentas de CLI, apps desktop, serviços de backend) com os quais o agent-browser não consegue interagir.
• Você precisa de load testing ou métricas de performance sintéticas além de observações qualitativas.
• Você quer testes codificados em nível fino embutidos no seu pipeline de CI; nesse caso, use frameworks de teste tradicionais em conjunto com dogfood.

Nesses cenários, trate dogfood como uma camada complementar focada em comportamento real de browser, e não como substituto de outras ferramentas de teste.