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 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