# Testing

RSConstruct uses integration tests exclusively. All tests live in the `tests/` directory and exercise the compiled `rsconstruct` binary as a black box — no unit tests are embedded in `src/`.

## Running tests

```bash
cargo test              # Run all tests
cargo test rsconstructignore    # Run tests matching a name
cargo test -- --nocapture  # Show stdout/stderr from tests
```

## Test directory layout

```
tests/
├── common/
│   └── mod.rs                  # Shared helpers (not a test binary)
├── build.rs                    # Build command tests
├── cache.rs                    # Cache operation tests
├── complete.rs                 # Shell completion tests
├── config.rs                   # Config show/show-default tests
├── dry_run.rs                  # Dry-run flag tests
├── graph.rs                    # Dependency graph tests
├── init.rs                     # Project initialization tests
├── processor_cmd.rs            # Processor list/auto/files tests
├── rsconstructignore.rs                # .rsconstructignore / .gitignore exclusion tests
├── status.rs                   # Status command tests
├── tools.rs                    # Tools list/check tests
├── watch.rs                    # File watcher tests
├── processors.rs               # Module root for processor tests
└── processors/
    ├── cc_single_file.rs       # C/C++ compilation tests
    ├── zspell.rs           # Zspell processor tests
    └── template.rs             # Template processor tests
```

Each top-level `.rs` file in `tests/` is compiled as a separate test binary by Cargo. The `processors.rs` file acts as a module root that declares the `processors/` subdirectory modules:

```rust
mod common;
mod processors {
    pub mod cc_single_file;
    pub mod zspell;
    pub mod template;
}
```

This is the standard Rust pattern for grouping related integration tests into subdirectories without creating a separate binary per file.

## Shared helpers

`tests/common/mod.rs` provides utilities used across all test files:

| Helper | Purpose |
|---|---|
| `setup_test_project()` | Create an isolated project in a temp directory with `rsconstruct.toml` and basic directories |
| `setup_cc_project(path)` | Create a C project structure with the `cc_single_file` processor enabled |
| `run_rsconstruct(dir, args)` | Execute the `rsconstruct` binary in the given directory and return its output |
| `run_rsconstruct_with_env(dir, args, env)` | Same as `run_rsconstruct` but with extra environment variables (e.g., `NO_COLOR=1`) |

All helpers use `env!("CARGO_BIN_EXE_rsconstruct")` to locate the compiled binary, ensuring tests run against the freshly built version.

Every test creates a fresh `TempDir` for isolation. The directory is automatically cleaned up when the test ends.

## Test categories

### Command tests

Tests in `build.rs`, `clean`, `dry_run.rs`, `init.rs`, `status.rs`, and `watch.rs` exercise CLI commands end-to-end:

```rust
#[test]
fn force_rebuild() {
    let temp_dir = setup_test_project();
    // ... set up files ...
    let output = run_rsconstruct_with_env(temp_dir.path(), &["build", "--force"], &[("NO_COLOR", "1")]);
    assert!(output.status.success());
    let stdout = String::from_utf8_lossy(&output.stdout);
    assert!(stdout.contains("[template] Processing:"));
}
```

These tests verify exit codes, stdout messages, and side effects (files created or removed).

### Processor tests

Tests under `processors/` verify individual processor behavior: file discovery, compilation, linting, incremental skip logic, and error handling. Each processor test module follows the same pattern:

1. Set up a temp project with appropriate source files
2. Run `rsconstruct build`
3. Assert outputs exist and contain expected content
4. Optionally modify a file and rebuild to test incrementality

### Ignore tests

`rsconstructignore.rs` tests `.rsconstructignore` pattern matching: exact file patterns, glob patterns, leading `/` (anchored), trailing `/` (directory), comments, blank lines, and interaction with multiple processors.

## Common assertion patterns

**Exit code:**

```rust
assert!(output.status.success());
```

**Stdout content:**

```rust
let stdout = String::from_utf8_lossy(&output.stdout);
assert!(stdout.contains("Processing:"));
assert!(!stdout.contains("error"));
```

**File existence:**

```rust
assert!(path.join("out/cc_single_file/main.elf").exists());
```

**Incremental builds:**

```rust
// First build
run_rsconstruct(path, &["build"]);

// Second build should skip
let output = run_rsconstruct_with_env(path, &["build"], &[("NO_COLOR", "1")]);
let stdout = String::from_utf8_lossy(&output.stdout);
assert!(stdout.contains("Skipping (unchanged):"));
```

**Mtime-dependent rebuilds:**

```rust
// Modify a file and wait for mtime to differ
std::thread::sleep(std::time::Duration::from_millis(100));
fs::write(path.join("src/header.h"), "// changed\n").unwrap();

let output = run_rsconstruct(path, &["build"]);
let stdout = String::from_utf8_lossy(&output.stdout);
assert!(stdout.contains("Processing:"));
```

## Writing a new test

1. Add a test function in the appropriate file (or create a new `.rs` file under `tests/` for a new feature area)
2. Use `setup_test_project()` or `setup_cc_project()` to create an isolated environment
3. Write source files and configuration into the temp directory
4. Run `rsconstruct` with `run_rsconstruct()` or `run_rsconstruct_with_env()`
5. Assert on exit code, stdout/stderr content, and output file existence

If adding a new processor test module, declare it in `tests/processors.rs`:

```rust
mod processors {
    pub mod cc_single_file;
    pub mod zspell;
    pub mod template;
    pub mod my_new_processor;  // add here
}
```

## Test coverage by area

| Area | File | Tests |
|---|---|---|
| Build command | `build.rs` | Force rebuild, incremental skip, clean, deterministic order, keep-going, timings, parallel -j flag, parallel keep-going, parallel all-products, parallel timings, parallel caching |
| Cache | `cache.rs` | Clear, size, trim, list operations |
| Complete | `complete.rs` | Bash/zsh/fish generation, config-driven completion |
| Config | `config.rs` | Show merged config, show defaults, annotation comments |
| Dry run | `dry_run.rs` | Preview output, force flag, short flag |
| Graph | `graph.rs` | DOT, mermaid, JSON, text formats, empty project |
| Init | `init.rs` | Project creation, duplicate detection, existing directory preservation |
| Processor command | `processor_cmd.rs` | List, all, auto-detect, files, unknown processor error |
| Status | `status.rs` | UP-TO-DATE / STALE / RESTORABLE reporting |
| Tools | `tools.rs` | List tools, list all, check availability |
| Watch | `watch.rs` | Initial build, rebuild on change |
| Ignore | `rsconstructignore.rs` | Exact match, globs, leading slash, trailing slash, comments, cross-processor |
| Template | `processors/template.rs` | Rendering, incremental, dep_inputs |
| CC | `processors/cc_single_file.rs` | Compilation, headers, per-file flags, mixed C/C++, config change detection |
| Zspell | `processors/zspell.rs` | Correct/misspelled words, code block filtering, custom words, incremental |
