Repository navigation
Hook tdd runner
Esta página explica o hook tdd_runner.py de forma didática. Se algum termo for novo, consulte o Glossário.
Um hook (gancho automático) é um pequeno programa que dispara sozinho em um momento específico, sem você pedir. Ele aplica regras de qualidade automaticamente. O bigtech traz 6 hooks; este é um deles.
O tdd-runner roda a suite de testes (o conjunto de todos os testes do projeto) automaticamente, logo depois que um arquivo de código ou de teste é salvo. Em seguida, ele grava o resultado (passou ou falhou) num arquivo de estado.
O nome significa "executor de TDD". Ele é a peça que mantém sempre atualizada a resposta para a pergunta "os testes estão passando agora?".
Ele dispara no evento PostToolUse, ou seja, logo depois de o assistente salvar ou editar um arquivo. Por isso o nome "post" (depois), em contraste com o tdd-guard, que age "pre" (antes).
Para que a disciplina de TDD funcione de forma automática, alguém precisa rodar os testes a cada mudança e anotar o resultado. É isso que o tdd-runner faz. O resultado que ele grava é lido pelo tdd-guard, que então decide se o próximo código de produção pode ser escrito. Sem o runner, o guard não teria em que se basear.
Depois de um arquivo ser salvo, o runner faz o seguinte:
- Descobre a raiz do projeto (a pasta principal).
- Olha o tipo do arquivo. Se não for de produção nem de teste, não faz nada (nada relevante mudou).
- Roda o comando de teste do projeto. Se houver um comando rápido configurado (um subconjunto dos testes), ele usa esse, para ser mais ágil.
- Grava o resultado num arquivo de estado: se passou ou falhou, quantos testes passaram, e as últimas linhas da saída.
O resultado fica guardado em uma pasta de estado dentro da sua própria configuração do Claude Code, separada por projeto.
Assim como o guard, este hook é opt-in (adesão voluntária). Ele só roda em projetos que têm o arquivo .claude/tdd-guard.json na raiz, que diz qual é o comando de teste. Sem esse arquivo, o runner fica inerte e nenhum projeto é afetado.
O comando de teste vem desse arquivo do próprio projeto. Isso tem a mesma confiança de rodar make test ou npm test no repositório. Por isso, ao trabalhar com projetos de terceiros que você não conhece, vale conferir qual comando está configurado antes.
O runner foi feito para nunca interromper o fluxo do Claude Code. Ele sempre termina sem erro, mesmo quando os testes falham (afinal, teste falhando é justamente o que o TDD espera no início). Se o comando de teste não puder rodar (por exemplo, o programa de teste não está instalado, ou demorou demais), ele apenas anota "não rodou" e segue, sem bloquear. Esse comportamento seguro se chama fail-open (veja o Glossário).
Para facilitar, o TDD vem com presets (configurações prontas) para várias tecnologias, de modo que você não precisa escrever o comando de teste na mão. Há presets para Python, PHP, Node (JavaScript e TypeScript), Go, C++ e .NET, entre outros. Você escolhe o preset no arquivo de configuração e o comando certo já vem definido. Se quiser, pode sobrescrever com um comando próprio.
O tdd-runner roda os testes e anota o resultado; o tdd-guard lê esse resultado e decide se libera o próximo código. Os dois são um par: um executa e anota, o outro lê e julga.
Detalhe técnico: os dois hooks de TDD compartilham um arquivo auxiliar interno chamado
tdd_common.py, que guarda a lógica comum (presets de tecnologia, classificação de arquivos, leitura e escrita do estado). Você não precisa mexer nele.
Veja também o tdd-guard e o agente de qualidade qa-engineer. Voltar para a Home.