# Testing
## Required test runner
Use `cargo-nextest` for running tests.
Rationale:
- consistent reporting
- better control of timeouts
- parallel execution
## Hard timeout rule (agent safety)
**Every full test run must complete within 120 seconds.**
If tests exceed 120 seconds, that is a failure. The goal is to prevent agent workflows from getting stuck in infinite loops or pathological hangs.
## Repository configuration
The repo should include `.config/nextest.toml` with a global timeout:
- `profile.default.global-timeout = "120s"`
## Standard commands
Run these before declaring a task "done":
- Format:
- `cargo fmt --check`
- Lint:
- `cargo clippy --all-targets --all-features`
- Tests (strict timeout):
- `cargo nextest run`
## Guidance for writing tests
- Prefer deterministic tests (avoid timing sensitivity).
- If a test is intentionally slow, mark it `#[ignore]` and document how/when to run it.
- When using randomness, seed it.
- Keep unit tests close to the code they verify; keep integration tests in `tests/`.
## If tests exceed the deadline
- Treat it as a bug
- Add a reproduction and fix the underlying deadlock/infinite loop/slow test
- Do not "just bump the timeout". Timeout bumping is only performed by humans
- If you cannot get all tests to complete in less time, do not delete tests by other agents or existing tests
- Prefer to fail your task instead