Testing Guide
Relevant source files
The following files were used as context for generating this wiki page:
The testing infrastructure for cargo-cooldown is designed to validate the tool's ability to delay the adoption of freshly published registry crates through end-to-end CLI tests, integration tests using deterministic local registries, and performance benchmarks. The test suite ensures that Cargo-valid lockfiles are produced while adhering to configured cooldown periods and enforcement policies.
Testing is categorized into three main layers: top-level CLI verification, complex integration scenarios using a mock sparse registry server, and manual smoke/benchmark scripts that interact with live registries like crates.io.
Test Infrastructure Architecture
The project utilizes a multi-layered testing approach to ensure reliability across different environments and use cases.
The diagram shows the relationship between different test suites and the components they validate. Sources: tests/cli.rs, tests/integration.rs, examples/run-crates-io-benchmark.sh
Key Components
| Component | Description | File Reference |
|---|---|---|
TestHarness | Orchestrates temporary directories, mock registries, and command execution for integration tests. | tests/integration.rs:592 |
RegistryServer | A deterministic local sparse registry server that serves mock crate metadata and tarballs. | tests/integration.rs:1140 |
ServerState | Tracks request counts and mock responses for the internal registry server. | tests/integration.rs:1205 |
Cargo Wrapper | A platform-specific script used to intercept and log internal cargo calls during cooldown. | tests/integration.rs:1493 |
CLI and Initialization Testing
CLI tests focus on top-level behavior, argument normalization, and the interactive initialization wizard.
Binary Verification
Tests in tests/cli.rs ensure that the tool responds correctly to standard flags like --help and --version without requiring a valid Cargo project context. Sources: tests/cli.rs:9-55
Interactive Setup Wizard
The init command is validated through tests/init.rs, which simulates user input to verify:
- Creation of
cooldown.tomlin crate roots. - Workspace-wide defaults and per-member overrides.
- Rejection of non-root directories.
- Prevention of overwriting existing configuration files.
Sources: tests/init.rs:11-85
Integration Testing Framework
The integration suite in tests/integration.rs provides a controlled environment for testing complex resolution logic, such as coordinated bundle resolution and backtracking.
Deterministic Registry Mocking
The RegistryServer simulates a Cargo sparse registry. It can be configured in several modes to test different metadata availability scenarios:
PubtimeOnly: Local index contains publish times.MissingPubtimeWithApi: Local index is missing times, but an HTTP API fallback is available.MissingPubtimeNoApi: No timing metadata is available, forcing fail-closed behavior.
Sources: tests/integration.rs:1149-1160, tests/integration.rs:1754-1768
Resolution Logic Validation
Integration tests cover specific resolver features:
- Coordinated Bundles: Testing groups of crates tied by exact requirements that must move together. Sources: tests/integration.rs:411-442
- Batch Solver: Verifying that multiple independent crates are cooled in a single verified lockfile rewrite rather than per-crate updates. Sources: tests/integration.rs:444-474
- Backtracking: Ensuring the solver can find locally compatible assignments when transitive dependencies conflict. Sources: tests/integration.rs:499-536
Isolated Workspace Testing
Integration tests verify that cargo-cooldown uses a temporary workspace for speculative resolution to avoid corrupting the user's primary Cargo.lock during failure. Sources: tests/integration.rs:322-371
The sequence shows how the integration tests interact with the mock registry server to validate resolution. Sources: tests/integration.rs:643-662, tests/integration.rs:1140
Performance and Manual Benchmarks
Manual benchmark scripts in the examples/ directory allow for performance probing against real-world datasets from crates.io.
Wall-Clock Benchmarks
The run-crates-io-benchmark.sh script measures:
- Total execution time across multiple samples.
- Frequency of HTTP fallback inspections.
- Registry API hit rates.
Sources: examples/run-crates-io-benchmark.sh:267-336
Smoke Testing
The run-crates-io-smoke.sh script provides presets for common manual checks:
allow-rules: Verifies mixed overrides for specific crates.cargo-compatible: Tests the permissive enforcement mode.skip-crates-io: Ensures registry-level exclusion works.
Sources: examples/run-crates-io-smoke.sh:91-135
Internal Logic Testing
Unit tests within src/executor.rs and src/resolution_state.rs target the mathematical and logical cores of the tool.
Resolver Unit Tests
Internal tests validate:
- Blocker Parsing: Extracts unique package names from Cargo conflict diagnostics. Sources: src/executor.rs:1162-1200
- Version Comparison: Ensures correct ordering for downgrading and cooling actions. Sources: src/executor.rs:1367-1425
- Constraint Tracking: Validates that reachable registry package versions are correctly identified from metadata. Sources: src/resolution_state.rs:460-520
Configuration Precedence
Tests in src/config.rs verify the hierarchy of settings:
- Environment variables (highest).
- Member-specific
cooldown.toml. - Workspace-root
cooldown.toml. - Global
$CARGO_HOME/cooldown.toml(lowest).
Sources: src/config.rs:309-354
The comprehensive test suite ensures that cargo-cooldown maintains its primary guarantee: producing a valid, "cooled" dependency graph that respects the security boundaries defined by the user while remaining compatible with standard Cargo workflows.