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](references/_sections.md) - Category structure and impact levels
• [Rule template](assets/templates/_template.md) - Template for adding new rules
• [cycle-write-test-first](references/cycle-write-test-first.md) - Write the Test Before the Implementation
• [design-aaa-pattern](references/design-aaa-pattern.md) - 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