# Specsfy 06 Tdd Bdd > Use quando o usuário pede TDD, BDD, testes derivados do Gherkin de referência da especificação, rastreabilidade entre `spec.md` e testes, ou um ciclo RED-GREEN-REFACTOR. Use também quando uma transição automática pedir materialização, RED ou verificação de testes. Use para editar as seções 11–13 e executar testes; `specsfy-07-implement` continua responsável pelas tarefas de produção na seção 14 do mesmo arquivo. - Skill: `promovaweb/specsfy-06-tdd-bdd` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add promovaweb/specsfy-06-tdd-bdd` - Raw SKILL.md: https://api.skillmd.com/api/skills/promovaweb/specsfy-06-tdd-bdd/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: promovaweb (https://skillmd.com/u/promovaweb) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/promovaweb/specsfy-06-tdd-bdd --- # Executar TDD orientado pelo BDD da especificação ## Preparação obrigatória Antes de executar esta skill, carregue obrigatoriamente `$specsfy-setup` na raiz do projeto. Em handoff automático, carregue-o de novo antes desta etapa. Reutilize a raiz confirmada na conversa e não prossiga se o setup apontar uma pendência. ## Modo de interação Modo de interação: `perguntas`. Antes de formular qualquer pergunta, leia e aplique o `Contrato de perguntas numeradas` de `.specsfy/Spec.md`. Leia o BDD como referência e converta o comportamento especificado em testes TDD executáveis e evidência rastreável. O Gherkin ajuda o usuário e o agente a entender contexto, ação e resultado; ele próprio não é uma suíte de testes. ## Proteção obrigatória do banco Antes de executar qualquer teste focal, suíte ou regressão, confira o comando e o ambiente: ```bash node .agents/skills/specsfy-setup/scripts/check_database_safety.mjs \ --project --command "" ``` Em Laravel, a conferência exige `.env.testing`, `APP_ENV=testing` e um banco explicitamente diferente do banco de desenvolvimento registrado no `.env`. Não execute nenhum teste enquanto o resultado for `PENDING`. Corrija o ambiente de testes, repita a conferência e prossiga somente depois de `SAFE`. Trate `IGNORED` como descarte obrigatório do comando. Não execute, não adapte com `--force` e não peça autorização para rodar `migrate:fresh`, `migrate:refresh`, `migrate:reset`, `migrate:rollback`, `db:wipe`, `schema:drop`, `prisma migrate reset`, `DROP DATABASE`, `DROP SCHEMA`, `DROP TABLE`, `TRUNCATE` ou equivalentes. Não use `RefreshDatabase` nem `DatabaseMigrations`; em Laravel, prefira `DatabaseTransactions` e factories que criem somente os registros usados pelo caso. ## Orquestrar a conversa Ao concluir esta etapa ou detectar trabalho de outra etapa, anuncie `Pendência detectada: — ação: resolvendo nesta etapa` e resolva-a quando pertencer ao próprio escopo. Quando houver troca de responsabilidade, anuncie `Transição automática: $specsfy-06-tdd-bdd → $ — motivo: — resultado esperado: ` e carregue imediatamente a skill de destino, sem pedir confirmação nem repetir o comando. Continue na mesma conversa. Depois de uma correção necessária a esta etapa, anuncie `Retomada automática: $ → $specsfy-06-tdd-bdd — pendência resolvida: ` e retome-a imediatamente. Reavalie o estado após cada handoff para evitar ciclos. Não peça confirmação para o handoff; ações sensíveis continuam exigindo autorização específica. ## Escolher o modo - `prepare`: antes da implementação, criar o próximo teste/scenario e provar RED sem escrever código de produção. - `cycle`: executar RED → GREEN → REFACTOR para uma fatia explicitamente escolhida. - `verify`: executar suites e auditar rastreabilidade sem criar comportamento novo. Se o usuário não indicar o modo, use `prepare` quando a seção 14 ainda não estiver em execução e `cycle` quando houver uma tarefa ativa. ## Preparar 1. Leia `specs//-/spec.md`, testes e configuração do projeto. 2. Exija `Formato: Specsfy/2.0` e `Definition Gate: Passed`. No modo `prepare`, use `Status: Defined` e `Plan Gate: Pending`; nos modos `cycle` e `verify`, use `Status: Planned` ou `Implementing`. 3. Selecione uma fatia vertical pequena: um `AC` Gherkin e seus `FR/NFR`. 4. Resolva o runner de testes pela stack antes de escrever testes: - projeto PHP (`composer.json` ou `artisan`), inclusive PHP + Node: use Pest; - projeto Node sem PHP: pergunte ao usuário qual runner adotar antes de instalar ou configurar; recomende Vitest por padrão; - outra stack: preserve o runner de testes existente ou pergunte quando não houver decisão reproduzível. 5. Confira o ambiente e o comando com `check_database_safety.mjs`. Se o estado não for `SAFE`, não execute teste algum e mantenha a etapa pendente. 6. Em Node, considere a decisão materializada quando `package.json` expuser o script `test:tdd`; não escolha nem instale dependência silenciosamente. 7. Leia `references/test-levels.md` para escolher o nível mais baixo que ainda prova o comportamento. ## Usar o BDD para escrever TDD - Use o bloco Gherkin do `AC` em `spec.md` como contrato de referência sem mudar seu significado. - Não crie, copie nem execute arquivos `.feature` ou step definitions. Os termos Given/When/Then permanecem apenas na `spec.md`. - Em PHP, escreva o teste TDD com Pest em `tests/Feature/` ou `tests/Unit/`, no menor nível que prova o comportamento. Marque cada caso executável, imediatamente junto à sua definição, com: ```php // SPECSFY: US-001 FR-001 AC-001 ``` - Em Node, depois da resposta do usuário, escreva o teste TDD no runner escolhido e use `SPECSFY: US-001 FR-001 AC-001`. - Materialize no mínimo três casos TDD distintos para a feature inteira e para cada `US`, `FR` e `NFR`: caminho feliz, regra/variação crítica e falha ou limite material. Um único marcador `SPECSFY:` compartilhado pelo arquivo conta como um caso, mesmo que o arquivo contenha vários testes. - Cubra cada `AC` com ao menos um caso TDD, sem multiplicar casos equivalentes. - Escolha unidade, integração, contrato ou browser conforme a fronteira descrita pelo BDD; não crie uma segunda suíte apenas para rotulá-la como BDD. - Não use mocks para remover justamente a fronteira que o cenário pretende provar. ## Ciclo obrigatório ### RED 1. Leia o BDD de referência e escreva o menor teste TDD que prova o `AC` e seus requisitos. 2. Execute o teste TDD; nunca execute Gherkin. 3. Confirme falha pelo comportamento ausente ou incorreto. 4. Se falhar por sintaxe, fixture, importação ou ambiente, corrija o teste e repita. 5. Se passar antes da mudança, o teste não demonstra o gap: refine-o ou prove que a funcionalidade já existe. No modo `prepare`, pare após o RED válido, registre evidência e conclua o checklist da tarefa `[TEST]` correspondente. Não altere `Plan Gate`; anuncie e retorne automaticamente para `$specsfy-05-tasks`, que valida todos os predecessores antes de promover a spec para `Planned`. Registre a linha correspondente na tabela `Evidência RED-GREEN-REFACTOR` com o RED observado. ### GREEN No modo `cycle`, escreva o mínimo de código de produção que satisfaça o cenário. Execute primeiro o teste focal e depois a suite relacionada. Não generalize antes de haver um exemplo que exija generalização. Atualize a mesma linha de evidência com o GREEN observado. ### REFACTOR Com tudo verde, elimine duplicação e melhore nomes/estrutura sem alterar comportamento. Execute novamente as suites relacionadas. Registre o comando de regressão na seção 11 e a evidência na matriz da seção 12. ## Auditar rastreabilidade Execute: ```bash node .agents/skills/specsfy-06-tdd-bdd/scripts/check_traceability.mjs specs//-/spec.md . ``` Trate como gap cada feature, `US`, `FR` ou `NFR` com menos de três casos TDD e cada `AC` sem ao menos um caso. Para `NFR` verificado manualmente ou por observabilidade, cite a evidência sem dispensar os três casos automatizáveis; quando necessário, ajuste `--kinds` sem remover IDs aplicáveis. Em specs com `Evidence Contract: 1`, acrescente `--full-chain` para exigir `US/FR/NFR/AC → teste → tarefa → evidência`. Durante execução, mantenha `Delivery Gate: In Progress` e atualize o `Gate do Ato III — Entrega` da seção 13. Use `Passed` somente quando não houver gap obrigatório, todas as tarefas estiverem concluídas e a Definition of Done estiver comprovada. ## Disciplina sob pressão | Tentação | Regra | | --- | --- | | “É uma mudança pequena.” | Mudanças pequenas recebem testes pequenos; tamanho não substitui RED. | | “O código já está pronto.” | Escreva um teste de caracterização; não altere produção para fabricar RED. Para comportamento novo, escolha um caso ainda não atendido. | | “O prazo permite pular RED.” | Sem falha observada não há prova de que o teste protege o requisito. | | “O líder autorizou.” | Autoridade pode mudar escopo, não transformar ausência de evidência em TDD. | | “Testar depois é equivalente.” | Test-first guia o contrato e prova sensibilidade antes da implementação. | Em uma tarefa de teste, atualize `PREP`, `EXECUTE`, `VERIFY`, `VISUAL`, `EVIDENCE` e `IMPROVE` conforme cada etapa acontecer. O item `VISUAL` também é obrigatório para confirmar se o teste toca uma interface; quando não tocar, registre `Não aplicável` e o motivo. Não marque o pai como concluído sem arquivo, marcador, RED válido, comando/evidência e revisão do processo. Não escreva código de produção antes que o predecessor TDD informado pelo BDD da mesma fatia esteja concluído e com RED registrado na spec. ## Auditar QA Depois de executar os runners pertencentes ao repositório, registre `Passed` ou a falha na coluna Evidência da seção 12 e audite: ```bash node .agents/skills/specsfy-06-tdd-bdd/scripts/verify_acceptance.mjs \ specs//-/spec.md . ``` O auditor não executa comandos extraídos de Markdown. AC manual exige método, responsável e evidência; AC sem resultado impede `Delivery Gate: Passed`. Quando houver atestação do runner, repita com `--attestation PATH`: o auditor exige exatamente o check `acceptance:` aprovado, detail JSON válido e cobertura de todos os ACs. Texto `Passed` isolado não substitui essa prova. ## Relatar evidência Informe a fatia, IDs cobertos, arquivo do teste, comando RED, causa da falha, comando GREEN quando aplicável, suite de regressão e gaps de rastreabilidade. ## Especialistas sob demanda Leia [references/specialists.md](references/specialists.md) quando o runner, boundary ou oráculo de teste for específico de uma tecnologia. O especialista complementa; esta skill preserva RED/GREEN e rastreabilidade.