# Agentes, skills e comandos para testes automatizados

Componentes para escrever, correr e avaliar testes com o Claude Code.

Numa base de código sem testes, cada alteração obriga a verificar à mão aquilo que já funcionava. O problema costuma aparecer quando a equipa cresce ou quando uma correção antiga volta a partir. Os testes automatizados são a rede que apanha essas regressões antes do utilizador, mas escrevê-los é trabalho lento: é preciso perceber o código, inventar casos-limite, preparar dados de teste e manter tudo isso vivo à medida que o projeto muda.

Os componentes desta página passam parte desse trabalho para o Claude Code. Uns leem um ficheiro de origem e devolvem o ficheiro de teste correspondente, com mocks e casos-limite já pensados. Outros analisam a cobertura existente e apontam os ramos que ninguém exercita. Há ainda automações que correm a suite sempre que um ficheiro é editado, e conetores que abrem um browser real para validar percursos completos de utilizador.

Comece pelo problema que tem hoje. Se o projeto já tem testes e quer aumentar a cobertura, um comando de geração e um relatório de cobertura chegam para as primeiras semanas. Se está a arrancar com uma funcionalidade nova, vale mais adotar o ciclo teste primeiro. Se o que falha são fluxos de interface, salte para o grupo de ponta a ponta. Instale poucos componentes de cada vez e mantenha só os que realmente usa.


## Escrever testes para código que já existe

O caso mais comum: há código em produção e pouca ou nenhuma cobertura. Estes componentes leem o que existe e produzem testes unitários e de integração alinhados com as convenções do projeto.

- **generate-tests** (Comandos): Indique um ficheiro ou o nome de um componente e receba o ficheiro de teste completo, já alinhado com o framework detetado no projeto (Jest, Vitest, Mocha ou Jasmine). [ficha](https://doutorai.pt/componentes/commands__generate-tests)
- **write-tests** (Comandos): Serve quando quer decidir o tipo de teste à partida: aceita unitário, integração, ponta a ponta ou componente como argumento, e trata do mocking e da configuração de cobertura. [ficha](https://doutorai.pt/componentes/commands__write-tests)
- **testing-patterns** (Skills): Para quem escreve em Jest e quer convenções estáveis: funções de fábrica para dados falsos, estratégias de mocking e a disciplina de testar comportamento em vez de implementação. [ficha](https://doutorai.pt/componentes/skills__testing-patterns)
- **python-testing-patterns** (Skills): O equivalente do lado do Python, com pytest, fixtures, parametrização e mocking de dependências externas, incluindo código assíncrono. Escolha-o se a suite vive em pytest. [ficha](https://doutorai.pt/componentes/skills__python-testing-patterns)
- **test-automator** (Agentes): Indicado quando não existe suite nenhuma e é preciso montar as três camadas de uma vez, incluindo dados de teste, fábricas e a configuração do pipeline de CI. [ficha](https://doutorai.pt/componentes/agents__test-automator)
- **test-engineer** (Agentes): Trabalha um nível acima do ficheiro: define a estratégia, distribui o esforço pela pirâmide de testes e fixa limiares de qualidade antes de alguém escrever a primeira asserção. [ficha](https://doutorai.pt/componentes/agents__test-engineer)

## Trabalhar em TDD, teste primeiro

Quando a funcionalidade ainda não existe, escrever o teste antes do código muda o desenho do resultado. Estes componentes impõem o ciclo vermelho, verde, refatoração em vez de deixar o modelo saltar diretamente para a implementação.

- **tdd-workflow** (Skills): A referência curta do ciclo, com as três leis do TDD e as regras de cada fase. Útil para manter o assistente dentro da disciplina durante sessões longas. [ficha](https://doutorai.pt/componentes/skills__tdd-workflow)
- **tdd-red** (Agentes): Escreve os testes que falham a partir do contexto de um issue no GitHub, extraindo requisitos, critérios de aceitação e casos-limite antes de existir qualquer implementação. [ficha](https://doutorai.pt/componentes/agents__tdd-red)
- **tdd-green** (Agentes): A fase seguinte: implementa apenas o mínimo para os testes passarem e resiste de forma explícita a alargar o âmbito para além do que o issue pede. [ficha](https://doutorai.pt/componentes/agents__tdd-green)
- **tdd-refactor** (Agentes): Fecha o ciclo com remoção de duplicação, melhorias de desenho e boas práticas de segurança, sempre com a condição de manter todos os testes verdes. [ficha](https://doutorai.pt/componentes/agents__tdd-refactor)

## Ponta a ponta, browser e regressão visual

Testes unitários não apanham um botão que deixou de submeter o formulário. Este grupo cobre percursos reais de utilizador num browser e as diferenças visuais entre versões.

- **e2e-setup** (Comandos): Para quem ainda não decidiu entre Cypress, Playwright, WebDriver ou Puppeteer: analisa o projeto, escolhe o framework e liga a suite ao sistema de CI que já existe. [ficha](https://doutorai.pt/componentes/commands__e2e-setup)
- **playwright-e2e-builder** (Skills): Vai mais fundo em Playwright, com Page Object Model, persistência do estado de autenticação, fixtures próprias e paralelização, começando por uma entrevista sobre os fluxos críticos. [ficha](https://doutorai.pt/componentes/skills__playwright-e2e-builder)
- **playwright-mcp-server** (Conetores): Dá ao Claude Code um browser a sério para navegar, tirar capturas de ecrã e executar JavaScript na página, útil para reproduzir um bug antes de o transformar em teste. [ficha](https://doutorai.pt/componentes/mcps__playwright-mcp-server)
- **setup-visual-testing** (Comandos): Quando a regressão é visual e não funcional: configura comparação de imagens entre browsers, em vários tamanhos de ecrã, ao nível do componente ou da página inteira. [ficha](https://doutorai.pt/componentes/commands__setup-visual-testing)

## Cobertura, qualidade da suite e execução automática

Ter testes não chega, é preciso saber se valem alguma coisa e garantir que correm. Aqui ficam a análise de cobertura, as técnicas que testam os próprios testes e a rotina de execução.

- **test-coverage** (Comandos): Separa cobertura de linha, de ramo, de função e de instrução, e mostra onde estão os buracos, em vez de uma percentagem única que esconde o que falta. [ficha](https://doutorai.pt/componentes/commands__test-coverage)
- **test-quality-analyzer** (Comandos): Uma suite grande também pode ser má. Avalia eficácia, manutenibilidade e tempo de execução dos testes existentes e sugere o que cortar ou reescrever. [ficha](https://doutorai.pt/componentes/commands__test-quality-analyzer)
- **add-mutation-testing** (Comandos): Introduz mutações no código para ver se algum teste as apanha, com Stryker, PIT, mutmut ou cargo-mutants. É a forma mais honesta de perceber se a cobertura significa alguma coisa. [ficha](https://doutorai.pt/componentes/commands__add-mutation-testing)
- **add-property-based-testing** (Comandos): Em vez de exemplos escolhidos à mão, identifica invariantes e gera entradas com fast-check, Hypothesis, QuickCheck ou proptest. Compensa em lógica de domínio cheia de casos-limite. [ficha](https://doutorai.pt/componentes/commands__add-property-based-testing)
- **test-runner** (Automações): Automação PostToolUse que corre os testes relevantes assim que um ficheiro é editado, reconhecendo projetos JavaScript, Python e Ruby sem configuração adicional. [ficha](https://doutorai.pt/componentes/hooks__test-runner)
- **senior-qa** (Skills): Traz scripts próprios para gerar suites, analisar cobertura e montar o esqueleto dos testes de ponta a ponta, orientados a aplicações React, Next.js e Node.js. [ficha](https://doutorai.pt/componentes/skills__senior-qa)
- **qa-test-planner** (Skills): Cobre o lado manual do QA: planos de teste, casos escritos, suites de regressão e relatórios de bug, com validação de ecrãs contra ficheiros do Figma. [ficha](https://doutorai.pt/componentes/skills__qa-test-planner)

## Onde é que cada tipo de componente se instala

Cada categoria tem um sítio próprio. Os agentes são ficheiros markdown em .claude/agents/ dentro do projeto, ou em ~/.claude/agents/ se quiser tê-los em todos os projetos. As skills ficam em .claude/skills/<nome>/SKILL.md e são carregadas quando o pedido corresponde à descrição. Os comandos ficam em .claude/commands/<nome>.md e invocam-se com barra, por exemplo /generate-tests src/auth.ts. As automações (hooks) são blocos de configuração no settings.json, com o evento e o comando de shell a executar. Os conetores MCP registam-se na configuração de servidores MCP e arrancam por npx quando a sessão começa. Instale ao nível do projeto sempre que a configuração dependa do framework de testes usado nesse repositório.

## Como encadear geração, cobertura e execução

Um encadeamento que funciona em código existente: corra primeiro o comando de cobertura para saber que ficheiros estão descobertos, depois gere testes ficheiro a ficheiro pelos módulos mais críticos, e só no fim ligue a automação que corre a suite a cada edição. Assim evita ter uma automação a falhar em todas as gravações enquanto a suite ainda está incompleta. Para os módulos onde um erro custa dinheiro ou dados, acrescente testes de mutação: se as mutações sobreviverem, os testes existem mas não verificam nada. Em funcionalidade nova, o encadeamento é outro: skill de TDD, agente da fase vermelha, agente da fase verde, agente de refatoração.

## O que estes componentes não resolvem

Testes gerados a partir de código existente descrevem o comportamento atual, incluindo os bugs. Se o objetivo é validar requisitos, alguém tem de rever cada asserção e confirmar que descreve o que deveria acontecer, não o que acontece. A percentagem de cobertura também não é qualidade: dá para chegar a números altos sem uma única asserção útil, e é por isso que a análise de mutação existe. Nos testes de ponta a ponta conte com lentidão e falhas intermitentes, sobretudo em ecrãs com animações ou dados variáveis. E nenhum destes componentes decide o que é crítico no seu produto, essa parte continua a ser sua.

## Perguntas frequentes

### Preciso de instalar todos estes componentes?

Não, e não é aconselhável. Cada skill e cada agente ocupam contexto e competem entre si quando fazem coisas parecidas. Escolha um componente por necessidade real: um para gerar testes, um para medir cobertura, e acrescente os de ponta a ponta apenas quando tiver fluxos de interface que valha a pena cobrir.

### Os testes gerados automaticamente são de confiança?

São um ponto de partida, não um resultado final. O modelo escreve as asserções a partir do código que lê, por isso um comportamento errado tende a ficar registado como se fosse correto. Reveja sempre os casos-limite e apague os testes que só repetem a implementação linha a linha, porque esses partem a cada refatoração.

### Qual é a diferença entre um agente, uma skill e um comando neste contexto?

Um comando é uma ação que o próprio utilizador dispara com barra, útil para tarefas pontuais como gerar um ficheiro de teste. Uma skill é conhecimento que o Claude Code carrega quando o pedido encaixa na descrição, por exemplo convenções de pytest. Um agente corre em contexto separado e é indicado para trabalho longo, como montar uma suite inteira.

### Isto funciona com a linguagem que uso no projeto?

Depende do componente. Vários detetam o framework a partir dos ficheiros de configuração e cobrem JavaScript, TypeScript e Python. Os comandos de mutação e de testes baseados em propriedades aceitam ainda Java, Rust, Go, C# e outras. Para pytest e para Jest existem skills dedicadas nesta página, com padrões específicos de cada uma.

### Vale a pena adotar TDD num projeto já a meio?

Vale, se o aplicar só ao código novo. Reescrever o histórico em TDD raramente compensa. A abordagem prática é usar os agentes de fase vermelha, verde e refatoração em cada funcionalidade nova ou correção de bug, e tratar o código antigo com geração de testes e análise de cobertura, que é mais rápido.


Fonte: https://doutorai.pt/para/testes-automatizados - Doutor AI, selecao feita a mao da biblioteca tecnica.