tdd git:20261026.fc845e3A

Immutable. This exact content never changes and is served at /api/v1/blob/262579374f51bf65.

---
name: tdd
description: Use when writing tests before implementation, applying red-green-refactor or reviewing test-first development. Not for Vitest APIs or request mocking; use vitest or msw.
---

# 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

| 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](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`