tdd
Community Test-Driven Development Best Practices
Comprehensive guide to Test-Driven Development practices, designed for AI agents and LLMs. Contains 42 rules across 8 categories, prioritized by impact to guide test writing, refactoring, and code generation.
When to Apply
Reference these guidelines when:
- Writing new tests using TDD workflow
- Implementing the red-green-refactor cycle
- Designing test structure and organization
- Creating test data and fixtures
- Reviewing or refactoring existing test suites
TDD Workflow
- RED: Write a failing test that defines desired behavior
- GREEN: Write minimal code to make the test pass
- REFACTOR: Clean up code while keeping tests green
- Repeat for each new behavior
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Red-Green-Refactor Cycle | CRITICAL | cycle- |
| 2 | Test Design Principles | CRITICAL | design- |
| 3 | Test Isolation & Dependencies | HIGH | isolate- |
| 4 | Test Data Management | HIGH | data- |
| 5 | Assertions & Verification | MEDIUM | assert- |
| 6 | Test Organization & Structure | MEDIUM | org- |
| 7 | Test Performance & Reliability | MEDIUM | perf- |
| 8 | Test Pyramid & Strategy | LOW | strat- |
Quick Reference
1. Red-Green-Refactor Cycle (CRITICAL)
cycle-write-test-first- Write the Test Before the Implementationcycle-minimal-code-to-pass- Write Only Enough Code to Pass the Testcycle-refactor-after-green- Refactor Immediately After Greencycle-verify-test-fails-first- Verify the Test Fails Before Writing Codecycle-small-increments- Take Small Incremental Stepscycle-maintain-test-list- Maintain a Test List
2. Test Design Principles (CRITICAL)
design-test-behavior-not-implementation- Test Behavior Not Implementationdesign-one-assertion-per-test- One Logical Assertion Per Testdesign-descriptive-test-names- Use Descriptive Test Namesdesign-aaa-pattern- Follow the Arrange-Act-Assert Patterndesign-test-edge-cases- Test Edge Cases and Boundariesdesign-avoid-logic-in-tests- Avoid Logic in Tests
3. Test Isolation & Dependencies (HIGH)
isolate-mock-external-dependencies- Mock External Dependenciesisolate-no-shared-state- Avoid Shared Mutable State Between Testsisolate-deterministic-tests- Write Deterministic Testsisolate-prefer-stubs-over-mocks- Prefer Stubs Over Mocks for Queriesisolate-use-dependency-injection- Use Dependency Injection for Testability
4. Test Data Management (HIGH)
data-use-factories- Use Factories for Test Data Creationdata-minimal-setup- Keep Test Setup Minimaldata-avoid-mystery-guests- Avoid Mystery Guestsdata-unique-identifiers- Use Unique Identifiers Per Testdata-builder-pattern- Use Builder Pattern for Complex Objects
5. Assertions & Verification (MEDIUM)
assert-specific-assertions- Use Specific Assertionsassert-error-messages- Assert on Error Messages and Typesassert-no-assertions-antipattern- Every Test Must Have Assertionsassert-custom-matchers- Create Custom Matchers for Domain Assertionsassert-snapshot-testing- Use Snapshot Testing Judiciously
6. Test Organization & Structure (MEDIUM)
org-group-by-behavior- Group Tests by Behavior Not Methodorg-file-structure- Follow Consistent Test File Structureorg-setup-teardown- Use Setup and Teardown Hooks Appropriatelyorg-test-utilities- Extract Reusable Test Utilitiesorg-parameterized-tests- Use Parameterized Tests for Variations
7. Test Performance & Reliability (MEDIUM)
perf-fast-unit-tests- Keep Unit Tests Under 100msperf-avoid-network-calls- Eliminate Network Calls in Unit Testsperf-fix-flaky-tests- Fix Flaky Tests Immediatelyperf-parallelize-tests- Parallelize Independent Testsperf-avoid-sleep- Avoid Arbitrary Sleep Calls
8. Test Pyramid & Strategy (LOW)
strat-test-pyramid- Follow the Test Pyramidstrat-mutation-testing- Use Mutation Testing to Validate Test Qualitystrat-coverage-targets- Set Meaningful Coverage Targetsstrat-integration-boundaries- Test Integration at Service Boundariesstrat-e2e-critical-paths- Limit E2E Tests to Critical User Paths
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
- cycle-write-test-first - Write the Test Before the Implementation
- design-aaa-pattern - Follow the Arrange-Act-Assert Pattern
Related Skills
- For Vitest framework specifics, see
vitestskill - For API mocking with MSW, see
mswskill
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
More from pproenca/dot-skills
zod
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
2.0Kclean-architecture
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
1.4Kemilkowal-animations
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
917vitest
Vitest testing framework patterns for test setup, async testing, mocking with vi.*, snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
906typescript
This skill should be used when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
820nuqs
nuqs (type-safe URL query state) best practices for Next.js applications. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, or Next.js routing with state.
734