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

1. RED: Write a failing test that defines desired behavior
2. GREEN: Write minimal code to make the test pass
3. REFACTOR: Clean up code while keeping tests green
4. Repeat for each new behavior

Rule Categories by Priority

Quick Reference

1. Red-Green-Refactor Cycle (CRITICAL)

• cycle-write-test-first – Write the Test Before the Implementation
• cycle-minimal-code-to-pass – Write Only Enough Code to Pass the Test
• cycle-refactor-after-green – Refactor Immediately After Green
• cycle-verify-test-fails-first – Verify the Test Fails Before Writing Code
• cycle-small-increments – Take Small Incremental Steps
• cycle-maintain-test-list – Maintain a Test List

2. Test Design Principles (CRITICAL)

• design-test-behavior-not-implementation – Test Behavior Not Implementation
• design-one-assertion-per-test – One Logical Assertion Per Test
• design-descriptive-test-names – Use Descriptive Test Names
• design-aaa-pattern – Follow the Arrange-Act-Assert Pattern
• design-test-edge-cases – Test Edge Cases and Boundaries
• design-avoid-logic-in-tests – Avoid Logic in Tests

3. Test Isolation & Dependencies (HIGH)

• isolate-mock-external-dependencies – Mock External Dependencies
• isolate-no-shared-state – Avoid Shared Mutable State Between Tests
• isolate-deterministic-tests – Write Deterministic Tests
• isolate-prefer-stubs-over-mocks – Prefer Stubs Over Mocks for Queries
• isolate-use-dependency-injection – Use Dependency Injection for Testability

4. Test Data Management (HIGH)

• data-use-factories – Use Factories for Test Data Creation
• data-minimal-setup – Keep Test Setup Minimal
• data-avoid-mystery-guests – Avoid Mystery Guests
• data-unique-identifiers – Use Unique Identifiers Per Test
• data-builder-pattern – Use Builder Pattern for Complex Objects

5. Assertions & Verification (MEDIUM)

• assert-specific-assertions – Use Specific Assertions
• assert-error-messages – Assert on Error Messages and Types
• assert-no-assertions-antipattern – Every Test Must Have Assertions
• assert-custom-matchers – Create Custom Matchers for Domain Assertions
• assert-snapshot-testing – Use Snapshot Testing Judiciously

6. Test Organization & Structure (MEDIUM)

• org-group-by-behavior – Group Tests by Behavior Not Method
• org-file-structure – Follow Consistent Test File Structure
• org-setup-teardown – Use Setup and Teardown Hooks Appropriately
• org-test-utilities – Extract Reusable Test Utilities
• org-parameterized-tests – Use Parameterized Tests for Variations

7. Test Performance & Reliability (MEDIUM)

• perf-fast-unit-tests – Keep Unit Tests Under 100ms
• perf-avoid-network-calls – Eliminate Network Calls in Unit Tests
• perf-fix-flaky-tests – Fix Flaky Tests Immediately
• perf-parallelize-tests – Parallelize Independent Tests
• perf-avoid-sleep – Avoid Arbitrary Sleep Calls

8. Test Pyramid & Strategy (LOW)

• strat-test-pyramid – Follow the Test Pyramid
• strat-mutation-testing – Use Mutation Testing to Validate Test Quality
• strat-coverage-targets – Set Meaningful Coverage Targets
• strat-integration-boundaries – Test Integration at Service Boundaries
• strat-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 vitest skill
• For API mocking with MSW, see msw skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md