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