Test-Driven Development

Overview

One skill for all TDD workflows. Enforces test-first development using existing repository patterns. Three input modes handle different entry points — specs, task files, or ad-hoc descriptions — but the core cycle is always RED → GREEN → REFACTOR.

Input Modes

Detect the input type and follow the corresponding mode:

Mode A: From Spec (

.spec.md

)

Use when the input references a

.spec.md

file with Given/When/Then acceptance criteria.

1. Locate and parse the spec file — extract all Given/When/Then triples
2. Generate one test stub per criterion with

   todo!()

   bodies:

   /// Spec: <spec-file> — Criterion #<N>
   /// Given <given text>
   /// When <when text>
   /// Then <then text>
   #[test]
   fn <spec_name>_criterion_<N>_<slug>() {
       todo!("Implement: <then text>");
   }
   

3. Verify stubs compile but fail:

   cargo test --no-run -p <crate>

4. Proceed to the TDD Cycle to make stubs pass

Programmatic support:

ralph_core::preflight::{extract_acceptance_criteria, extract_criteria_from_file, extract_all_criteria}

can parse criteria from spec files.

Mode B: From Task (

.code-task.md

)

Use when the input references a

.code-task.md

file or a specific implementation task.

1. Read the task and identify acceptance criteria or requirements
2. Discover patterns (see Pattern Discovery)
3. Design test scenarios covering normal operation, edge cases, and error conditions
4. Write failing tests for all requirements before any implementation
5. Proceed to the TDD Cycle

Mode C: From Description

Use for ad-hoc tasks without a spec or task file.

1. Clarify requirements from the description
2. Discover patterns (see Pattern Discovery)
3. Write failing tests targeting the described behavior
4. Proceed to the TDD Cycle

Pattern Discovery

Before writing tests, discover existing conventions:

rg --files -g "crates/*/tests/*.rs"
rg -n "#\[cfg\(test\)\]" crates/

Read 2-3 relevant test files near the target code. Mirror:

• Test module layout, naming, and assertion style
• Fixture helpers and test utilities
• Use of

  tempfile

  , scenarios, or harnesses

TDD Cycle

1) RED — Failing Tests

• Write tests for the exact behavior required
• Run tests to confirm failure for the right reason
• If tests pass without implementation, the test is wrong

2) GREEN — Minimal Implementation

• Write the minimum code to make tests pass
• No extra features or refactoring during this step

3) REFACTOR — Clean Up

• Improve implementation and tests while keeping tests green
• Align with surrounding codebase conventions
• Re-run tests after every change

Proptest Guidance

Use

proptest

only when ALL of:

• Function is pure (no I/O, no time, no globals)
• Deterministic output for given input
• Non-trivial input space or edge cases

proptest! {
    #[test]
    fn round_trip(input in "[a-z0-9]{0,32}") {
        let encoded = encode(input.as_str());
        let decoded = decode(&encoded).expect("should decode");
        prop_assert_eq!(decoded, input);
    }
}

Don't introduce proptest as a new dependency without strong justification.

Backpressure Integration

Include coverage evidence in completion events:

ralph emit "build.done" "tests: pass, lint: pass, typecheck: pass, audit: pass, coverage: pass (82%)"

Run

cargo tarpaulin --out Html --output-dir coverage --skip-clean

when feasible. If coverage cannot be run, state why and include targeted test evidence instead.

Test Location Rules

• Spec maps to a single module → inline

  #[cfg(test)]

  tests
• Spec spans multiple modules → integration test in

  crates/<crate>/tests/

• CLI behavior →

  crates/ralph-cli/tests/

• Follow existing patterns in the target crate

Anti-Patterns

• Writing implementation before tests
• Generating tests that pass without implementation
• Copying tests from other crates without adapting to local patterns
• Adding proptest when a simple example test suffices
• Emitting completion events without coverage evidence