rtk-tdd

# Rust TDD Workflow ## Three Laws of TDD 1. Do NOT write production code without a failing test 2. Write only enough test to fail (including compilation failure) 3. Write only enough production code to pass the failing test Cycle: **RED** (test fails) -> **GREEN** (minimum to pass) -> **REFACTOR** (cleanup, cargo test) ## Red-Green-Refactor Steps ``` 1. Write test in #[cfg(test)] mod tests of the SAME file 2. cargo test MODULE::tests::test_name -- must FAIL (red) 3. Implement the minimum in the function 4. cargo test MODULE::tests::test_name -- must PASS (green) 5. Refactor if needed, re-run cargo test (still green) 6. cargo fmt && cargo clippy --all-targets && cargo test (final gate) ``` Never skip step 2. If the test passes immediately, it tests nothing. ## Idiomatic Rust Test Patterns | Pattern | Usage | When | |---------|-------|------| | Arrange-Act-Assert | Base structure for every test | Always | | `assert_eq!` / `assert!` | Direct comparison / booleans | Deterministic values | | `assert!(result.is_err())` | Error path testing | Invalid inputs | | `Result<()>` return type | Tests with `?` operator | Fallible functions | | `#[should_panic]` | Expected panic | Invariants, preconditions | | `tempfile::NamedTempFile` | File/I/O tests | Filesystem-dependent code | ## Patterns by Code Type | Code Type | Test Pattern | Example | |-----------|-------------|---------| | Pure function (str -> str) | Input literal -> assert output | `assert_eq!(truncate("hello", 3), "...")` | | Parsing/filtering | Raw string -> filter -> contains/not-contains | `assert!(filter(raw).contains("expected"))` | | Validation/security | Boundary inputs -> assert bool | `assert!(!is_valid("../etc/passwd"))` | | Error handling | Bad input -> `is_err()` | `assert!(parse("garbage").is_err())` | | Struct/enum roundtrip | Construct -> serialize -> deserialize -> eq | `assert_eq!(from_str(to_str(x)), x)` | ## Naming Convention ``` test_{function}_{scenario} test_{function}_{input_type} ``` Examples: `test_truncate_edge_case`, `test_parse_invalid_input`, `test_filter_empty_string` ## When NOT to Use Pure TDD - Functions calling `Command::new()` -> test the parser, not the execution - `std::process::exit()` -> refactor to `Result` first, then test the Result - Direct I/O (SQLite, network) -> use tempfile/mock or test the pure logic separately - Main/CLI wiring -> covered by integration/smoke tests ## Pre-Commit Gate ```bash cargo fmt --all --check cargo clippy --all-targets cargo test ``` All 3 must pass. No exceptions. No `#[allow(...)]` without documented justification.