tdd-guide

Visão geral da skill tdd-guide

Para que serve a tdd-guide

tdd-guide é uma skill de Test Driven Development para gerar testes unitários, encontrar lacunas de cobertura, criar fixtures e mocks e orientar o ciclo red-green-refactor em stacks comuns. Ela é mais útil quando você quer que um assistente de IA faça mais do que “escrever alguns testes”: a skill conduz a conversa para o código-fonte, os requisitos, o framework-alvo, os relatórios de cobertura e os critérios de validação.

Usuários e projetos mais indicados

A skill tdd-guide atende bem equipes de engenharia, desenvolvedores solo e pessoas com foco em QA que trabalham com TypeScript, JavaScript, Python ou Java. Ela é especialmente relevante para fluxos com Jest, Pytest, JUnit, Vitest e Mocha. Use quando estiver adicionando testes a código existente, começando uma nova funcionalidade com testes primeiro, melhorando a cobertura até um limite definido ou padronizando a saída de testes em uma equipe.

O que a diferencia de um prompt genérico de testes

Um prompt genérico pode gerar testes plausíveis, mas muitas vezes deixa passar convenções do framework, casos de borda, prioridades de cobertura ou o próprio ciclo de TDD. tdd-guide inclui estrutura de workflow, exemplos de entrada, padrões esperados de saída, tooling para análise de cobertura, geração de fixtures, adaptação por framework e referências para integração com CI. Isso a torna mais adequada para trabalho de engenharia repetível do que para experimentos pontuais com prompts.

Quando tdd-guide pode não ser suficiente

tdd-guide for Test Driven Development não substitui o entendimento do comportamento de domínio. Se você não consegue fornecer resultados esperados, dependências, regras de erro ou detalhes do framework, os testes gerados podem ficar superficiais. Ela também não garante automaticamente que os testes vão compilar no seu repositório; você ainda precisa executar o comando local de testes e ajustar imports, arquivos de setup, mocks e configurações específicas do ambiente.

Como usar a skill tdd-guide

Instalação da tdd-guide e prévia do repositório

Instale a skill em um ambiente compatível com Claude Skills usando:

npx skills add alirezarezvani/claude-skills --skill tdd-guide

Depois, revise a pasta upstream da skill em engineering-team/skills/tdd-guide. Comece por SKILL.md para ver regras de ativação e workflows, depois leia HOW_TO_USE.md para exemplos de invocação. Se você precisa de configuração específica por framework, consulte references/framework-guide.md; se o objetivo é aplicar verificações no build, leia references/ci-integration.md; se quer melhorar hábitos de TDD, revise references/tdd-best-practices.md.

Entradas que melhoram o uso da tdd-guide

A skill funciona melhor quando você fornece quatro elementos: o código ou requisito da funcionalidade, a linguagem, o framework de testes e o comportamento esperado. Boas entradas incluem fluxos felizes, casos de erro, valores de borda, dependências externas e metas de cobertura.

Um prompt fraco seria: “Write tests for my auth service.”

Um prompt mais forte seria: “Use tdd-guide to generate Jest tests for src/auth/password-validator.ts. Cover valid password, too short password, missing uppercase, missing number, missing special character, and null or empty input. Target 90% branch coverage. Use existing project style: describe, beforeEach, and expect(...).toBe(...).”

Workflow prático com tdd-guide

Para código existente, use esta sequência:

1. Cole ou referencie o arquivo-fonte.
2. Especifique language, framework e a convenção de nome do arquivo de teste.
3. Peça testes agrupados por prioridade: comportamento P0, casos de borda P1, regressões P2.
4. Execute os testes gerados localmente.
5. Cole de volta no assistente erros de compilação, assertions que falharam ou saída de cobertura.
6. Peça à skill para refinar imports, mocks, fixtures e branches ausentes.

Para uma nova funcionalidade, use red-green-refactor: primeiro peça testes que falhem a partir dos critérios de aceite, implemente o menor código que faça os testes passarem e depois peça melhorias seguras para refatoração mantendo os testes verdes.

Arquivos e scripts úteis para inspecionar primeiro

O repositório contém arquivos práticos de apoio que vale a pena ler antes de um uso mais sério:

• assets/sample_input_python.json e assets/sample_input_typescript.json mostram o nível de entrada estruturada que melhora a qualidade da saída.
• assets/expected_output.json mostra o tipo de resumo de testes, cobertura e qualidade que a skill foi projetada para produzir.
• scripts/test_generator.py dá suporte a padrões de geração de testes.
• scripts/coverage_analyzer.py é relevante quando você tem dados de cobertura em LCOV, JSON ou XML.
• scripts/fixture_generator.py, framework_adapter.py e tdd_workflow.py indicam como a skill pensa sobre mocks, convenções de framework e fases de TDD.

FAQ da skill tdd-guide

tdd-guide é boa para iniciantes?

Sim, desde que a pessoa iniciante tenha uma funcionalidade ou função concreta para testar. A skill tdd-guide pode ensinar o ritmo de red, green e refactor enquanto produz exemplos utilizáveis. Ainda assim, iniciantes devem executar todos os testes gerados e ler as falhas. O valor de aprendizado vem da comparação entre comportamento esperado, assertions geradas e implementação real.

Quais frameworks a tdd-guide atende melhor?

O melhor encaixe é com Jest, Pytest, JUnit e Vitest, com Mocha também mencionado na descrição da skill. A referência de framework incluída cobre padrões de TypeScript/JavaScript, Python e Java. Se você usa um framework menos comum, forneça um arquivo de teste de exemplo do seu repositório para que a skill consiga acompanhar imports, nomenclatura, hooks de setup e estilo de assertions.

Ela consegue analisar relatórios de cobertura?

Sim. tdd-guide foi pensada para trabalhar com relatórios de cobertura como LCOV, JSON e XML. Para obter melhores resultados, cole os arquivos e branches relevantes que ficaram descobertos, em vez de informar apenas uma porcentagem. Um prompt como “coverage is 65%” é menos útil do que compartilhar coverage/lcov.info, intervalos de linhas sem cobertura e os arquivos-fonte associados a essas lacunas.

Quando eu não deveria usar tdd-guide?

Não use como a única barreira de qualidade para comportamentos críticos de segurança, finanças, saúde ou conformidade regulatória. Ela pode ajudar a rascunhar testes e expor lacunas, mas não consegue confirmar a correção de negócio sem regras autoritativas. Também é uma má escolha quando o codebase não pode ser compartilhado, quando não há comportamento público definido ou quando o projeto depende fortemente de ambientes de integração ocultos.

Como melhorar a skill tdd-guide

Melhore os resultados da tdd-guide com prompts melhores

A forma mais rápida de melhorar a saída de tdd-guide é fornecer comportamento, não apenas código. Inclua exemplos de entrada válida, entrada inválida, exceções esperadas, valores de borda e quaisquer convenções de teste existentes. Se forem necessários mocks, nomeie a dependência e defina o que deve ser stubado versus o que deve ser exercitado de verdade.

Adições úteis ao prompt incluem:

• “Do not mock the pure calculation function.”
• “Mock the payment gateway and assert it is called once.”
• “Use parameterized Pytest cases for boundary values.”
• “Prefer behavior-focused test names over implementation names.”

Corrija modos de falha comuns depois da primeira saída

Problemas comuns incluem imports errados, mocks em excesso, assertions frágeis baseadas na implementação, tratamento assíncrono ausente e testes que aumentam a cobertura de linhas sem aumentar a confiança. Depois do primeiro resultado, cole a falha do teste ou o erro de compilação e peça uma correção direcionada. Por exemplo: “These Jest tests fail because the service constructor requires a repository dependency. Revise using a typed mock and keep the same behavioral coverage.”

Use dados de cobertura para priorizar o trabalho

Se o objetivo é melhorar a cobertura, peça à skill para classificar as lacunas por risco, em vez de gerar testes para cada linha não coberta. Priorize condicionais não testados, branches de erro, métodos públicos e regras de negócio antes de getters triviais ou branches defensivos. O workflow de cobertura do repositório dá suporte à priorização P0/P1/P2, que é mais útil do que perseguir apenas uma porcentagem bruta.

Itere em direção a uma prática de TDD sustentável

O melhor uso da tdd-guide é iterativo. Primeiro peça testes que falhem a partir dos requisitos; depois, peça o formato mínimo da implementação; por fim, solicite sugestões de refatoração que mantenham os testes estáveis. Mantenha o assistente focado em comportamento observável: entradas, saídas, efeitos colaterais, exceções e fronteiras de integração. Isso gera testes que continuam úteis mesmo depois que a implementação muda.