n4m3z/TestDrivenDevelopment

TestDrivenDevelopment

Foundational engineering principle for all Forge ecosystem code. Write the test first, then make it pass, then refine.

The Red-Green-Refactor Cycle

1. Red — Write a failing test that describes the desired behavior
2. Green — Write the minimum code to make the test pass
3. Refactor — Clean up without changing behavior (tests still pass)

This cycle produces code that is testable by design, not testable by accident.

Test Categories

Unit Tests

Test individual functions and modules in isolation. These are the backbone:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn extract_frontmatter_value_finds_simple_key() {
        let content = "---\ntitle: My Note\nclaude.name: TestAgent\n---\nBody";
        assert_eq!(
            extract_frontmatter_value(content, "claude.name"),
            Some("TestAgent".to_string())
        );
    }

    #[test]
    fn extract_frontmatter_value_handles_quoted_values() {
        let content = "---\ndescription: \"A quoted value\"\n---\n";
        assert_eq!(
            extract_frontmatter_value(content, "description"),
            Some("A quoted value".to_string())
        );
    }

    #[test]
    fn extract_frontmatter_value_returns_none_for_missing() {
        let content = "---\ntitle: Note\n---\n";
        assert_eq!(extract_frontmatter_value(content, "missing"), None);
    }
}

Convention: Put unit tests in a tests.rs file alongside mod.rs, referenced by #[cfg(test)] mod tests; at the top of the module.

Integration Tests

Test binary behavior end-to-end. Use std::process::Command:

#[test]
fn safe_read_strips_red_sections() {
    let output = Command::new(env!("CARGO_BIN_EXE_safe-read"))
        .arg("tests/fixtures/mixed-tlp.md")
        .output()
        .expect("failed to run safe-read");

    let stdout = String::from_utf8_lossy(&output.stdout);
    assert!(stdout.contains("## Public Section"));
    assert!(!stdout.contains("#tlp/red"));
    assert!(!stdout.contains("secret content"));
}

Edge Case Tests

Every function should have tests for boundary conditions:

#[test]
fn handles_empty_input() {
    assert_eq!(extract_frontmatter_value("", "key"), None);
}

#[test]
fn handles_no_frontmatter() {
    assert_eq!(extract_frontmatter_value("Just text", "key"), None);
}

#[test]
fn handles_empty_frontmatter() {
    assert_eq!(extract_frontmatter_value("---\n---\nBody", "key"), None);
}

#[test]
fn handles_frontmatter_without_closing() {
    assert_eq!(extract_frontmatter_value("---\nkey: val\n", "key"), None);
}

Property-Based Tests (when appropriate)

For functions with well-defined invariants, use proptest or quickcheck:

#[cfg(test)]
mod proptests {
    use proptest::prelude::*;

    proptest! {
        #[test]
        fn roundtrip_slugify(name in "[A-Z][a-zA-Z]{1,30}") {
            let slug = slugify(&name);
            // slug is always lowercase kebab-case
            assert!(slug.chars().all(|c| c.is_ascii_lowercase() || c == '-'));
            // slug is never empty
            assert!(!slug.is_empty());
        }
    }
}

Test Organization in Forge

Rust Modules

src/
├── frontmatter/
│   ├── mod.rs         # pub fn extract_value(...) + #[cfg(test)] mod tests;
│   └── tests.rs       # all unit tests
├── deploy/
│   ├── mod.rs         # pub fn deploy_agent(...) + #[cfg(test)] mod tests;
│   └── tests.rs       # all unit tests

Shell Test Suites (legacy, being converted)

lib/tests/
├── helpers.sh                    # Shared assertions (assert_eq, assert_contains, report)
├── test-module-structure.sh      # Module layout validation
├── test-agent-frontmatter.sh     # Agent file integrity
├── test-defaults-consistency.sh  # Config consistency
├── test-skill-integrity.sh       # Skill file validation
└── test-deploy-parity.sh         # Deploy output matching source

Each shell test uses assert_eq, assert_contains, assert_file_exists from helpers and calls report to summarize PASS/FAIL.

Test Fixtures

Use dedicated fixture directories for test data:

#[test]
fn parses_agent_frontmatter() {
    let content = include_str!("../../tests/fixtures/agent.md");
    let fm = parse_frontmatter(content).expect("valid frontmatter");
    assert_eq!(fm.name, "Developer");
    assert_eq!(fm.model, "sonnet");
}

For generated fixtures, create them in test setup:

fn fixture_agent(name: &str) -> String {
    format!(
        "---\ntitle: {name}\nclaude.name: {name}\nclaude.model: sonnet\n\
         claude.description: \"Test agent\"\nclaude.tools: Read, Grep\n---\n\nBody.\n"
    )
}

Coverage Strategy

| Component | Required Coverage | Method | |-----------|-------------------|--------| | Frontmatter parsing | 100% branch | Unit tests with valid/invalid/edge inputs | | Config loading | All fallback paths | Unit tests with missing/corrupt files | | Agent deployment | All providers | Integration tests per provider format | | Skill installation | Happy + error paths | Integration tests | | TLP redaction | 100% (security-critical) | Unit + property tests |

What NOT to Test

• External library behavior (serde deserialization, clap parsing)
• Trivial getters/setters with no logic
• Platform-specific code in CI (use #[cfg] to skip)

Test-First Workflow for New Features

1. Write the public API signature with doc comment
2. Write 3-5 tests covering: happy path, error case, edge case
3. Run tests (all fail — Red)
4. Implement the function (tests pass — Green)
5. Refactor for clarity (tests still pass — Refactor)
6. Add any additional edge case tests discovered during implementation

Running Tests

# All Rust tests in a workspace
cargo test --workspace

# Single test in a specific crate
cargo test --manifest-path <crate>/Cargo.toml -- test_name

# With output
cargo test -- --nocapture

Red Flags

| Thought | Reality | | -------------------------------------------- | ---------------------------------------------------------------- | | "Too simple to test" | Simple code breaks. Test takes 30 seconds. | | "I'll write tests after" | Tests passing immediately prove nothing. | | "Tests after achieve the same goals" | Tests-after verify what you built. Tests-first verify what's needed. | | "I already manually tested it" | Ad-hoc is not systematic. No record, can't re-run. | | "Deleting X hours of work is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. | | "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. | | "Need to explore first" | Fine. Throw away exploration, start with TDD. | | "Test is hard to write — design is unclear" | Listen to the test. Hard to test means hard to use. | | "TDD will slow me down" | TDD is faster than debugging. Pragmatic means test-first. | | "This is different because..." | It's not. Delete code. Start over with TDD. |

Anti-Patterns

| Anti-Pattern | Why | Fix | |-------------|-----|-----| | Testing after implementation | Shapes code around existing structure, not behavior | Write test first | | Testing implementation details | Breaks on refactor | Test public API behavior | | Large integration tests only | Slow, hard to debug | Unit tests first, integration for wiring | | Ignoring test failures | Normalizes broken code | Fix immediately or mark #[ignore] with reason | | Copy-paste test cases | Maintenance burden | Use parameterized tests or fixtures | | Mocking everything | Tests pass but nothing works | Mock at boundaries only |