Synvael/synvael
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs(workspace): add testing policy to AGENTS.md

Browse source
This commit is contained in:
Serkyo 2026-07-07 01:17:35 +02:00
parent d3c75a4454
commit 645ba6d301
1 changed files with 12 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
AGENTS.md
View file

@ -95,6 +95,18 @@ The game is **multithreaded by design**: single-threaded would not meet the perf
- **Errors in binaries** (`client`, `server`): [`anyhow`](https://docs.rs/anyhow/) at the top level, with `.context("...")` for human-readable layering. Library errors compose into `anyhow::Error` cleanly via `?`.
- **Never `.unwrap()` or `.expect()` outside `main` / setup / tests**, except where the invariant is genuinely impossible to violate. In the hot path, propagate with `?` and let the caller decide.
## Testing policy
Tests are prioritised by risk, not by a coverage percentage. Effort is directed where "compiles and appears correct" does not guarantee correctness. The following categories require accompanying unit tests, written in the same change that introduces or modifies the logic:
- **Pure, algorithmic logic** — values in, values out, no I/O, no GPU, no windowing: coordinate and index math, packing/unpacking, meshing math, and similar self-contained computation. These are cheap to test and their edges are easy to get subtly wrong.
- **Correctness traps** — behaviour where a plausible implementation is silently wrong on an edge case: sign handling, off-by-one, integer overflow or truncation, bit-packing boundaries. As a canonical example, world-to-chunk conversion floors via `div_euclid` rather than truncating via `/`; a test on negative inputs pins that contract and prevents a regression to `/`.
- **Load-bearing invariants, especially determinism** — per the determinism stance below, worldgen is seed-deterministic and bit-for-bit reproducible. That contract cannot be verified by inspection and is guarded by tests (for example, generating a chunk twice from one seed and asserting equality). Determinism is guarded aggressively.
Subsystems that are I/O- or hardware-bound — the `renderer`/Vulkan GPU paths, `client` windowing and input, and top-level binary wiring — are validated through integration and manual/visual verification rather than unit tests, since their behaviour depends on a live device, window, or process rather than on pure logic. The appropriate mechanism differs; the expectation of verification does not.
Unit tests live beside the code (`#[cfg(test)] mod tests`) and run with `cargo test -p <crate>`.
## Documentation style
- **Objective Tone:** All comments (both doc comments `///` and inline `//`) must be written in a formal, objective, and neutral tone.