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

cycle-

design-

isolate-

data-

assert-

org-

perf-

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