Testing Best Practices
adewale/testing-best-practices
Enforce testing best practices com TDD, property-based tests e detecção de anti-padrões
Ver no GitHubSkill para Claude Code que reforça boas práticas de testes: TDD, testes baseados em propriedades, objetos reais vs mocks, avaliação de qualidade de testes e detecção de anti-padrões. Opera em quatro modos: escrita (Red-Green-Refactor), avaliação estruturada (P0-P3), upgrade de testes fracos e detecção de anti-padrões.
Instalação
npx convez-ai adewale/testing-best-practices1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Escrever testes com TDD seguindo red-green-refactor
- Revisar qualidade de testes existentes com auditoria estruturada
- Detectar anti-padrões: testes pulados, mocks desnecessários, assertions fracas
- Gerar testes baseados em propriedades (Hypothesis, proptest, fast-check)
- Melhorar densidade de assertions e cobertura de casos limítrofes
Veredito

Ferramenta sólida e bem-fundamentada em boas práticas consolidadas (Kent Beck, GOOS). Útil para elevar qualidade de testes em projetos com Claude Code, com suporte a múltiplas linguagens e detecção concreta de anti-padrões. Requer disciplina do desenvolvedor para usar efetivamente nos quatro modos.
README
A tradução para o português deste README ainda está na fila.
testing-best-practices
An agent skill that enforces testing best practices when writing, reviewing, or improving tests. Built from analysis of real-world testing patterns across 15 GitHub accounts and grounded in the work of practitioners like Kent Beck (TDD), Nat Pryce (GOOS), Graydon Hoare (Rust), Salvatore Sanfilippo (Redis), and Andrej Karpathy.

What it does
When an agent uses this skill, it produces higher-quality tests than it would on its own. Specifically:
- Property-based tests appear (Hypothesis, fast-check, proptest) where they wouldn't otherwise
- Assertion density increases from ~1 to 3+ meaningful assertions per test
- Assessments become structured with severity-prioritized findings (P0/P1/P2/P3) instead of ad-hoc lists
- Anti-patterns get detected: skipped tests, logging-instead-of-asserting, mock-everything "integration" tests, weak "not empty" assertions
- Language-appropriate patterns are used: table-driven tests in Go,
#[test]modules in Rust, Vitest + fast-check in TypeScript
Install
npx skills add adewale/testing-best-practices
Skills appear on skills.sh automatically after users install the repo with the skills CLI. Install counts and leaderboard rankings come from anonymous CLI telemetry; opt out with DISABLE_TELEMETRY=1. The repo page customization in skills.sh.json is picked up after the repository is seen by telemetry and the cache refreshes.
Agent compatibility
The installable skill directory is testing-best-practices. It uses the Agent Skills SKILL.md format and is configured for Codex, OpenCode, Pi, Gemini CLI, and Claude Code.
| Agent/client | Install or use |
|---|---|
| Codex | cp -R testing-best-practices ~/.codex/skills/testing-best-practices |
| OpenCode | cp -R testing-best-practices ~/.config/opencode/skills/testing-best-practices or use .opencode/skills/testing-best-practices in a project |
| Pi | pi install https://github.com/adewale/testing-best-practices or pi --skill testing-best-practices |
| Gemini CLI | gemini skills install https://github.com/adewale/testing-best-practices --path testing-best-practices or copy to .gemini/skills/testing-best-practices |
| Claude Code | npx skills add adewale/testing-best-practices or copy to .claude/skills/testing-best-practices |
How it works
The skill operates in four modes:
| Mode | When | What it does |
|---|---|---|
| Write | Writing new tests | Red-Green-Refactor TDD, property-based tests, boundary values, sad path coverage, validation loop |
| Assess | Reviewing existing tests | 6-step quality audit: sabotage detection, assertion density, mock drift, tier integrity, coverage config, mutation testing readiness |
| Upgrade | Improving weak tests | Prioritized fixes for flaky, weak, or sabotaged tests |
| Detect | Finding hidden problems | Unconditional skips, print-not-assert, ordering dependencies, tests that fake coverage |
Language-specific guidance loads on demand based on the project's language. Advanced pattern references load only when their trigger condition matches (e.g., references/characterization-testing.md loads only when refactoring legacy code). This keeps token usage efficient.
What's covered
Core principles (always loaded, ~5,000 tokens)
- Red-Green-Refactor TDD
- Test quality over quantity (Kent Beck's Test Desiderata, assertion density)
- Real objects over mocks (with a preference hierarchy)
- Property-based testing (9 invariant patterns including mathematical properties)
- E2E testing
- Documentation-code sync testing
- Characterization testing for legacy code
- Differential and pirate testing
- Test data builders and fixtures
- Correctness by construction — types over runtime checks; invariant-proof tests (PBT) plus model-gap tests (try to construct each forbidden state)
- Sad path and boundary testing
- Validation loop (self-check before reporting done, including "could a type have replaced this test?")
Reference files (loaded on demand)
Language-specific (one loaded per project):
| File | Content |
|---|---|
references/python.md | pytest, Hypothesis, VCR cassettes, async testing, CLI testing |
references/typescript.md | Vitest, fast-check, Playwright, mock contract tests, API clients |
references/go.md | Table-driven tests, t.TempDir(), httptest, build tags, testdata/, t.Helper() |
references/rust.md | #[test], proptest, exhaustigen, cargo-mutants, CLI binary tests |
Always available:
| File | Content |
|---|---|
references/antipatterns.md | 13 anti-patterns with detection signals, severity levels, and fixes |
references/test-types.md | Decision guide with Step Zero (types-vs-tests), trust-boundary lens, and 3-tier hierarchy |
Topic-specific (loaded only when the trigger matches):
| File | Trigger |
|---|---|
references/characterization-testing.md | Refactoring legacy code |
references/differential-testing.md | Reimplementing algorithms, multi-language SDKs |
references/golden-file-testing.md | Transformation pipelines, snapshot tests, promote workflow |
references/deterministic-time.md | Code depends on time, timers, scheduling, or flaky time tests |
references/vcr-cassettes.md | Code calling external APIs |
references/doc-sync-testing.md | CLI commands or plugin hooks in docs |
references/mutation-testing.md | Verifying test suite catches real bugs |
references/exhaustive-testing.md | Small state spaces (booleans, enums) |
references/mathematical-properties.md | Domain objects with arithmetic |
references/test-data-builders.md | Need factories, fixtures, or assertion helpers |
references/correctness-by-construction.md | Same invariant checked at 3+ layers, "should never happen" tests, status enums duplicated across layers, loose strings through the system, or typed language with smart constructors |
Eval results
Evaluated with 10 test cases across Python, TypeScript, Go, and Rust:
| Eval | Language | Mode | Description |
|---|---|---|---|
| 1 | Python | Write | URL parser test suite |
| 2 | Python | Assess | Weak test quality review |
| 3 | TypeScript | Write | Security-focused sanitizer tests |
| 4 | Go | Write | Cache with TTL and concurrency |
| 5 | Python | Write | Characterization tests for legacy code |
| 6 | Python | Write | VCR cassette setup for API testing |
| 7 | TypeScript | Assess | Weak test quality review |
| 8 | Go | Assess | Weak test quality review |
| 9 | Rust | Write | INI config parser tests |
| 10 | Go | Write | Characterization tests for cache |
Full eval data is in testing-best-practices-workspace/.
Research corpus
Built from analysis of testing patterns across 16 GitHub accounts and one organization:
- kentbeck -- Test Desiderata (12 properties of good tests), TCR, MoneyPython; books: TDD: By Example (red/green/refactor, test list, green-bar strategies, testing patterns), XP Explained (test-what-might-break, 100% rule, ten-minute build), Tidy First? (behavior vs. structure changes)
- npryce (GOOS co-author) -- factcheck, snodge, make-it-easy, worktorule; GOOS book: walking skeleton, double feedback loop, listen-to-your-tests, mock roles not objects, allow queries / expect commands
- graydon (Rust creator) -- exhaustigen-rs, proptest-arbitrary-interop
- karpathy -- differential testing against PyTorch/tiktoken
- kepano -- fixture-based golden file testing (defuddle)
- maryrosecook -- gitlet test suite, file tree builders
- simonw (datasette, sqlite-utils, llm) -- documentation-as-tests, VCR cassettes
- bradfitz (Go team) -- protocol-faithful fake servers
- joewalnes -- minimalist testing frameworks
- ivanmoore -- TDD katas, mock object exercises
- adewale -- property-based testing, mock fidelity, test quality audits
- chrischabot -- 5-tier test architecture, API scenario tests
- tirsen -- retry patterns
- antirez (Redis creator) -- differential fuzzing vs. a reference oracle, digest roundtrips,
DEBUGas a testability surface, recall testing for approximate algorithms, agent-as-QA - janestreet -- expect tests, library-level simulation,
Time_source, Bonsai testing - danluu -- random/coverage-guided generation thesis, "world's dumbest fuzzer" (Fuzz.jl: seed/try-catch-log/denylist harness mechanics), differential testing (csv), fault injection (fs-errors), solver-backed generation (kodkod-clj, secvisor-formal-verification)
- WardCunningham (wiki/Fit/CRC inventor) -- Fit customer-readable example tables, CHECKS validation patterns, domain DSLs in test suites (wiki-client), characterization harnesses (sudokuku), test-investment-tracks-lifetime, "preserve and protect [the test suite] as if it were code" (EPISODES)
Individual research documents are in research/ (one per practitioner/account). The research process itself is captured in research/METHODOLOGY.md — a minimum checklist (GitHub history including actual test files and commit authorship, books, long-form writing, talks/interviews, pre-GitHub tools, post-mortems and criticism), explicitly framed as a floor rather than a ceiling.
Project structure
testing-best-practices/ # The skill (ships to agents)
SKILL.md # Core instructions (~175 lines)
references/ # Loaded on demand
python.md # Language: Python
typescript.md # Language: TypeScript
go.md # Language: Go
rust.md # Language: Rust
antipatterns.md # Always: detection signals + fixes
test-types.md # Always: decision guide
characterization-testing.md # Topic: legacy code
differential-testing.md # Topic: reference implementations
golden-file-testing.md # Topic: transformation pipelines, snapshot tests
deterministic-time.md # Topic: clock injection, time virtualization
vcr-cassettes.md # Topic: external APIs
doc-sync-testing.md # Topic: documentation drift
mutation-testing.md # Topic: test quality verification
exhaustive-testing.md # Topic: small state spaces
mathematical-properties.md # Topic: algebraic laws
test-data-builders.md # Topic: factories and fixtures
research/ # Source material (does not ship)
METHODOLOGY.md # How we research a practitioner (a floor, not a ceiling)
LESSONS_FROM_KENTBECK.md
LESSONS_FROM_NPRYCE.md
LESSONS_FROM_GRAYDON.md
LESSONS_FROM_KARPATHY.md
LESSONS_FROM_KEPANO.md
LESSONS_FROM_MARYROSECOOK.md
LESSONS_FROM_SIMONW_REPOS.md
LESSONS_FROM_BRADFITZ.md
LESSONS_FROM_JOEWALNES.md
LESSONS_FROM_IVANMOORE.md
LESSONS_FROM_ADEWALE_REPOS.md
LESSONS_FROM_CHRISCHABOT_REPOS.md
LESSONS_FROM_TIRSEN.md
LESSONS_FROM_ANTIREZ.md
LESSONS_FROM_JANE_STREET.md
LESSONS_FROM_DANLUU.md
LESSONS_FROM_WARDCUNNINGHAM.md
ANTIPATTERNS.md
DECISION_TREE.md
NOVEL_TESTING_TYPES.md
DESIGN_FOR_TESTABILITY_LITERATURE.md
evals/ # Test cases for the skill itself
shared-benchmark.json # Shared harness manifest with 36 cases
evals.json # Legacy eval set across 4 languages
files/ # Fixture code for eval prompts
testing-best-practices-workspace/ # Eval results by iteration
License
MIT