# Testing Guidelines
Testing rules for the Delaunay triangulation library.
Agents must follow these expectations when adding or modifying Rust code.
---
## Contents
- [Testing Philosophy](#testing-philosophy)
- [Test Types](#test-types)
- [Unit Tests](#unit-tests)
- [Integration Tests](#integration-tests)
- [Property Tests](#property-tests)
- [Floating-Point Comparisons](#floating-point-comparisons)
- [Degenerate Geometry](#degenerate-geometry)
- [Dimension Coverage (2D–5D)](#dimension-coverage-2d5d)
- [Deterministic Randomness](#deterministic-randomness)
- [Error Handling in Tests](#error-handling-in-tests)
- [Triangulation Validation](#triangulation-validation)
- [Core Geometry Invariants](#core-geometry-invariants)
- [Triangulation Validity Checklist](#triangulation-validity-checklist)
- [Test Commands](#test-commands)
- [Documentation Tests](#documentation-tests)
- [Performance-Sensitive Tests](#performance-sensitive-tests)
- [CI Expectations](#ci-expectations)
- [Test Module Organization](#test-module-organization)
- [Preferred Test Style](#preferred-test-style)
---
## Testing Philosophy
This project is a **scientific computational geometry library**.
Tests should verify:
- mathematical correctness
- geometric invariants
- topological consistency
- algorithm stability
When possible, prefer **property-based testing** over single-case tests.
Tests should focus on validating invariants rather than merely executing code.
---
## Test Types
The project uses several categories of tests.
### Unit Tests
Location:
```text
src/**
```
Defined inline using:
```rust
#[cfg(test)]
mod tests {
```
Unit tests validate:
- small internal algorithms
- helper utilities
- invariants within modules
They should be small, deterministic, and fast.
---
### Integration Tests
Location:
```text
tests/
```
Integration tests compile as **separate crates** and test the public API.
Each integration test crate should include a crate-level documentation comment:
```rust
//! Integration tests for triangulation invariants.
```
This satisfies `clippy::missing_docs` in CI.
Integration tests should validate:
- full triangulation construction
- public API behavior
- cross-module interactions
Fixed-bug regression integration tests belong in `tests/regressions.rs`. Add
new regression cases there instead of creating issue-specific files such as
`tests/regression_issue_123.rs`, unless the case needs separate crate-level
configuration, feature flags, or profile isolation.
---
### Property Tests
Property tests are strongly preferred for geometric structures.
The project uses the **proptest** crate.
Example pattern:
```rust
proptest! {
#[test]
fn triangulation_is_valid(points in point_cloud_strategy()) {
let tri = build_triangulation(points);
assert!(tri.validate().is_ok());
}
}
```
Property tests should validate invariants rather than specific outputs.
Typical invariants include:
- Euler characteristic
- simplex adjacency consistency
- vertex-star topology
- manifold link conditions
- orientation predicate correctness
---
## Floating-Point Comparisons
Never compare floating-point values using `assert_eq!`.
Use the **approx** crate for tolerant comparisons.
Preferred macros:
```rust
use approx::{assert_relative_eq, assert_abs_diff_eq};
assert_relative_eq!(a, b, epsilon = 1e-12);
```
Floating-point arithmetic is not exact and direct equality comparisons will
produce fragile tests.
For geometric predicates you might also allow **ULP comparisons** from the same crate:
```rust
assert_ulps_eq!(a, b, max_ulps = 4);
```
---
## Degenerate Geometry
Tests should include degenerate or near-degenerate configurations.
Important cases include:
- duplicate vertices
- collinear points
- coplanar point sets
- nearly coincident points
- extremely large coordinate values
- extremely small coordinate values
Robust geometry code must handle these cases gracefully.
---
## Dimension Coverage (2D–5D)
This library supports d-dimensional triangulations. Tests for
dimension-generic code **must cover 2D through 5D** whenever possible.
### Use macros for per-dimension test generation
Define a macro that accepts a dimension literal and generates the full set
of test functions for that dimension. Invoke it once per dimension:
```rust
macro_rules! gen_tests {
($dim:literal) => {
pastey::paste! {
#[test]
fn [<test_foo_ $dim d>]() {
let points = build_points::<$dim>();
// assertions …
}
}
};
}
gen_tests!(2);
gen_tests!(3);
gen_tests!(4);
gen_tests!(5);
```
### Keep core logic in generic helper functions
The macro body should be thin — primarily calling generic helpers and
asserting results. Dimension-specific point construction, translation, and
other setup belongs in `const`-generic helper functions:
```rust
fn build_degenerate_points<const D: usize>() -> Vec<Point<D>> { … }
fn translate_point<const D: usize>(p: &Point<D>) -> Point<D> { … }
```
This keeps the macro readable and the helpers independently testable.
### Reference examples
- Unit tests: `src/geometry/sos.rs` — `gen_sos_dim_tests!`
- Property tests: `tests/proptest_sos.rs` — `gen_sos_tests!`
### When single-dimension tests are acceptable
Some tests are inherently dimension-specific (e.g. 1D edge cases,
matrix-level tests for a fixed size, error-handling tests). These do not
need macro-ification.
---
## Deterministic Randomness
Tests must be deterministic.
If randomness is required, use a seeded RNG.
Example:
```rust
use rand::{SeedableRng, rngs::StdRng};
let rng = StdRng::seed_from_u64(1234);
```
Do **not** use:
```rust
thread_rng()
```
Deterministic seeds allow failures to be reproduced.
---
## Error Handling in Tests
Unit tests may use unwrap/expect-style failure when an impossible setup failure
should fail the test immediately. Public examples, doctests, benchmarks, and
public API integration tests should prefer typed `Result`, `Option`, or
infallible flows so users do not copy panic-only control flow.
Examples:
```rust
let tri = build_triangulation(points)?;
```
or
```rust
#[derive(Debug, thiserror::Error)]
enum ExampleQueryError<K: std::fmt::Debug> {
#[error("missing simplex {key:?}")]
MissingSimplex { key: K },
}
let Some(simplex) = tri.simplex(key) else {
return Err(ExampleQueryError::MissingSimplex { key });
};
```
Explicit error handling is still unnecessary inside focused unit tests unless
the test is specifically verifying error behavior.
Clippy's `unwrap_used` lint may be relaxed or allowed in test code when
appropriate.
---
## Triangulation Validation
Whenever possible, prefer validating triangulations using invariant checks.
Example:
```rust
assert!(tri.validate().is_ok());
```
Validation helpers are preferred over writing manual assertions about
internal state.
Tests should verify structural correctness of the triangulation.
---
## Core Geometry Invariants
The formal triangulation invariants are defined in:
```text
docs/invariants.md
```
Tests should verify behavior consistent with that specification.
For details on validation helpers such as `validate()`, `is_valid()`,
`is_valid_topology()`, and `is_valid_delaunay()`, see:
```text
docs/validation.md
```
Tests should prefer calling these validation helpers instead of
re‑implementing invariant logic.
Tests should verify core invariants such as:
- every simplex references valid vertices
- adjacency relationships are symmetric
- vertex stars are topologically consistent
- no duplicate simplices exist
- Euler characteristic is correct
- orientation predicates produce consistent signs
## Triangulation Validity Checklist
When writing tests that construct or modify a triangulation, agents should
prefer validating the following checklist rather than writing ad‑hoc
assertions:
- `tri.validate()` returns `Ok(())`
- every simplex references existing vertices
- adjacency relationships are symmetric
- vertex stars form closed topological neighborhoods
- no duplicate simplices exist
- orientation predicates are consistent across neighbors
Whenever possible, prefer a single invariant validation call (e.g.
`tri.validate()`) rather than duplicating these checks manually.
Invariant-based testing is the most reliable way to validate geometric
algorithms.
---
## Test Commands
Tests should pass using the repository command set.
The test suite has two routine correctness buckets:
- Default tests: expected to stay under roughly 10 seconds per test and run
through `just test`.
- Slow tests: correctness or regression tests that exceed that per-test budget.
Gate these with `#[cfg(feature = "slow-tests")]` and run them through
`just test-slow`.
Default test recipes are split by target class:
- `just test-unit` runs Rust lib unit tests in debug and release profiles.
- `just test-doc` runs Rust doctests in release profile.
- `just test-integration` runs Rust integration tests.
- `just test-cli` runs feature-gated CLI integration tests.
- `just test-python` runs Python tests.
For test-only changes, run only the matching focused recipe. If multiple test
target classes changed, compose those focused recipes once each. Use
`just test` when you intentionally want the full default test suite;
`just test-rust` composes the four Rust target classes once each.
During iteration, prefer the targeted changed-test commands in
[`commands.md`](commands.md); reserve full focused recipes such as
`just test-doc`, `just test-unit`, and `just test-integration` for final bucket
validation or broad changes.
Notebook validation is separate from `just test`. Cell identity, source
hygiene, deliberate execution, and artifact rules live in
[`notebooks.md`](notebooks.md); exact recipes remain in
[`commands.md`](commands.md).
Do not mark deterministic slow correctness tests with `#[ignore]`; that makes
them invisible to `just test-slow`. Benchmark-style tests should live in
`benches/`, not as `#[cfg(feature = "bench")]` unit tests. Feature-gated
`bench` helpers are acceptable only as fixture builders for Criterion harnesses,
especially when measuring repair paths that need deliberately invalid topology.
Those helpers should still have focused unit tests for their fixture contract.
Known limitations should be asserted explicitly or tracked outside the routine
test suite rather than hidden behind `#[ignore]`.
Run all default test buckets:
```bash
just test
```
Run every default Rust test class:
```bash
just test-rust
```
Run Rust lib unit tests:
```bash
just test-unit
```
Run Rust doctests:
```bash
just test-doc
```
Run integration tests:
```bash
just test-integration
```
Run Python tests:
```bash
just test-python
```
Run feature-gated CLI integration tests:
```bash
just test-cli
```
Run the slow correctness bucket:
```bash
just test-slow
```
---
## Documentation Tests
Public documentation examples must compile.
Validate with:
```bash
just test-doc
```
or:
```bash
cargo test --doc --release
```
---
## Performance-Sensitive Tests
Tests should remain fast.
Avoid:
- extremely large random inputs
- quadratic or worse scaling test loops
- heavy allocations
Large-scale performance validation belongs in **benchmarks**, not tests.
---
## CI Expectations
All tests must pass under CI.
For final handoff validation after Rust test changes, run:
```bash
just ci
```
For documentation-only, configuration-only, or Python-only edits, follow the
validation command selection matrix in [`commands.md`](commands.md) instead of
defaulting to full CI.
CI enforces:
- formatting
- linting
- documentation builds
- unit tests
- integration tests
---
## Test Module Organization
Within a `#[cfg(test)] mod tests { … }` block, items should appear in
this order:
1. `use` imports
2. Test-only types (e.g. mock kernels, stub structs)
3. Helper functions
4. Macros (`macro_rules!`)
5. `#[test]` functions (and `proptest!` blocks)
All `use` imports for a test module must go at the **top** of the module,
not inside individual test functions. This keeps dependencies visible in
one place and avoids duplicated or scattered imports.
Local test-only helpers, shims, forced-failure hooks, and fixture state belong
inside the owning file's `#[cfg(test)] mod tests { ... }` block. Do not put
local test-only modules or imports in the production module preamble. Production
code that must branch for a unit test should reference helpers under
`tests::...` only from code guarded by `#[cfg(test)]`. Shared cross-module test
support that must live beside private storage internals must be named
`test_support`, placed near the owning tests rather than in the preamble, and
given the narrowest visibility that still lets the tests compile.
Thread-local fault-injection flags are a last-resort unit-test seam for rare
rollback, repair, and validation branches that cannot be reached
deterministically through public APIs or narrower test fixtures. Keep them
inside the owning `mod tests`, use an RAII guard that restores the previous
value, and document why thread-local state is needed for parallel-test
isolation. Prefer explicit inputs, typed fixtures, or harness APIs whenever they
can cover the branch, and remove the thread-local hook once a cleaner trigger
exists.
Keeping helpers and types **above** macros and tests makes them easy to
find and avoids forward-reference confusion. New helpers should be added
to this section rather than inlined next to the tests that use them.
---
## Preferred Test Style
Tests should be:
- deterministic
- focused
- invariant-driven
- easy to reproduce
Avoid large monolithic tests or tests that do not verify correctness.