Test-Driven Development

Version 0.1.0
Community
January 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive guide to Test-Driven Development practices, designed for AI agents and LLMs. Contains 42 rules across 8 categories, prioritized by impact from critical (red-green-refactor cycle, test design principles) to strategic (test pyramid, coverage targets). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide test writing, refactoring, and code generation.

Table of Contents

1. Red-Green-Refactor Cycle — CRITICAL
   • 1.1 Maintain a Test List — CRITICAL (prevents scope creep and forgotten cases)
   • 1.2 Refactor Immediately After Green — CRITICAL (prevents technical debt accumulation)
   • 1.3 Take Small Incremental Steps — CRITICAL (2-5× faster debugging from smaller change sets)
   • 1.4 Verify the Test Fails Before Writing Code — CRITICAL (prevents false positives from untested code)
   • 1.5 Write Only Enough Code to Pass the Test — CRITICAL (prevents over-engineering and YAGNI violations)
   • 1.6 Write the Test Before the Implementation — CRITICAL (prevents 40-90% of defects)
2. Test Design Principles — CRITICAL
   • 2.1 Avoid Logic in Tests — CRITICAL (eliminates bugs in test code itself)
   • 2.2 Follow the Arrange-Act-Assert Pattern — CRITICAL (makes tests 2-3× more readable)
   • 2.3 One Logical Assertion Per Test — CRITICAL (reduces failure diagnosis time to O(1))
   • 2.4 Test Behavior Not Implementation — CRITICAL (reduces test brittleness by 50-80%)
   • 2.5 Test Edge Cases and Boundaries — CRITICAL (catches 60-80% of production bugs)
   • 2.6 Use Descriptive Test Names — CRITICAL (2-3× faster failure diagnosis)
3. Test Isolation & Dependencies — HIGH
   • 3.1 Avoid Shared Mutable State Between Tests — HIGH (eliminates 74% of test order dependency bugs)
   • 3.2 Mock External Dependencies — HIGH (makes tests 10-100× faster)
   • 3.3 Prefer Stubs Over Mocks for Queries — HIGH (reduces test brittleness)
   • 3.4 Use Dependency Injection for Testability — HIGH (enables isolation without hacks)
   • 3.5 Write Deterministic Tests — HIGH (eliminates flaky test failures)
4. Test Data Management — HIGH
   • 4.1 Avoid Mystery Guests — HIGH (2-3× faster test comprehension)
   • 4.2 Keep Test Setup Minimal — HIGH (2-5× faster test execution and comprehension)
   • 4.3 Use Builder Pattern for Complex Objects — HIGH (reduces complex setup code by 40-60%)
   • 4.4 Use Factories for Test Data Creation — HIGH (reduces test setup code by 60-80%)
   • 4.5 Use Unique Identifiers Per Test — HIGH (prevents test pollution)
5. Assertions & Verification — MEDIUM
   • 5.1 Assert on Error Messages and Types — MEDIUM (prevents false positives from wrong errors)
   • 5.2 Create Custom Matchers for Domain Assertions — MEDIUM (reduces assertion code by 60-80%)
   • 5.3 Every Test Must Have Assertions — MEDIUM (prevents false passing tests)
   • 5.4 Use Snapshot Testing Judiciously — MEDIUM (prevents snapshot blindness)
   • 5.5 Use Specific Assertions — MEDIUM (2-5× faster debugging from better failure messages)
6. Test Organization & Structure — MEDIUM
   • 6.1 Extract Reusable Test Utilities — MEDIUM (reduces duplication by 40-60%)
   • 6.2 Follow Consistent Test File Structure — MEDIUM (reduces time finding tests)
   • 6.3 Group Tests by Behavior Not Method — MEDIUM (2-3× faster test navigation and discovery)
   • 6.4 Use Parameterized Tests for Variations — MEDIUM (reduces test code by 50-70%)
   • 6.5 Use Setup and Teardown Hooks Appropriately — MEDIUM (reduces setup duplication by 30-50%)
7. Test Performance & Reliability — MEDIUM
   • 7.1 Avoid Arbitrary Sleep Calls — MEDIUM (eliminates 54% of async-related flakiness)
   • 7.2 Eliminate Network Calls in Unit Tests — MEDIUM (makes tests 10-100× faster)
   • 7.3 Fix Flaky Tests Immediately — MEDIUM (preserves trust in test suite)
   • 7.4 Keep Unit Tests Under 100ms — MEDIUM (enables rapid feedback loops)
   • 7.5 Parallelize Independent Tests — MEDIUM (reduces suite time by 50-80%)
8. Test Pyramid & Strategy — LOW
   • 8.1 Follow the Test Pyramid — LOW (reduces test infrastructure cost by 10-100×)
   • 8.2 Limit E2E Tests to Critical User Paths — LOW (reduces maintenance burden)
   • 8.3 Set Meaningful Coverage Targets — LOW (2-3× better ROI on testing effort)
   • 8.4 Test Integration at Service Boundaries — LOW (prevents integration failures in production)
   • 8.5 Use Mutation Testing to Validate Test Quality — LOW (detects 30-50% more weak assertions)

References

1. https://martinfowler.com/bliki/TestDrivenDevelopment.html
2. http://blog.cleancoder.com/uncle-bob/2014/12/17/TheCyclesOfTDD.html
3. https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices
4. https://testing.googleblog.com/2020/08/code-coverage-best-practices.html
5. https://semaphore.io/blog/aaa-pattern-test-automation
6. https://docs.pytest.org/en/stable/how-to/fixtures.html
7. https://martinfowler.com/articles/practical-test-pyramid.html

Source Files

This document was compiled from individual reference files. For detailed editing or extension: