# 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.
Every source module should unit-test all reasonably testable behavior that it
owns. Keep those tests in the owning source file, in a `#[cfg(test)] mod tests`
block at the end of the file after all production items. Place a test at the
lowest layer that owns the behavior: do not construct a `Triangulation` or
`DelaunayTriangulation` merely to test a TDS invariant, and do not leave
construction-, query-, validation-, or algorithm-specific tests in a model
module solely because they exercise the model type. A narrowly shared
`#[cfg(test)] mod test_support` may immediately precede the owning test module
when private storage access is necessary. Cross-module workflows and public API
contracts belong in integration tests instead.
Do not keep duplicate tests of the same contract in another source module or
integration test. Prefer the focused unit test in the module that owns the
behavior and retire the duplicate. Tests at multiple layers are justified only
when each supplies distinct boundary evidence, such as a private invariant unit
test plus a public API integration test; their names and assertions should make
that distinction explicit.
---
### 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
#### Fail-closed admission and production errors
Property tests must fail closed after independently admitting generated input.
Use `prop_assume!`, `TestCaseError::reject`, or an early successful return only
for domain facts computed directly from raw generated values, such as too few
coordinate-distinct points or a deliberately excluded non-finite coordinate.
Never reject or silently skip a case because a builder, insertion, predicate,
serialization, deserialization, or validation operation returned an error.
After admission, map every unexpected production error to
`TestCaseError::fail` with the operation, dimension or input position, and the
typed error's debug representation.
```rust
// Good: admission is an input-only fact; construction must then succeed.
prop_assume!(unique_coordinate_count(&points) > D);
let triangulation = build(&points).map_err(|error| {
TestCaseError::fail(format!("{D}D construction failed: {error:?}"))
})?;
```
```rust
// Bad: a production failure is converted into a rejected or passing case.
let Ok(triangulation) = build(&points) else {
return Err(TestCaseError::reject("construction failed"));
};
if let Ok(value) = predicate(&triangulation) {
prop_assert!(value);
}
```
Properties that drive `TestRunner` directly must also establish deterministic
acceptance evidence. After a successful run, assert that the accepted count
equals the configured target case count; do not make the minimum acceptance
rate depend on an optional environment variable. Rejected raw inputs may
increase the generated count, but production failures must never contribute to
that rejection telemetry.
---
## 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
../construction_and_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 binary unit and CLI integration tests.
- `just test-python` runs Python tests.
The debug unit-test profile keeps the same 10-second per-test budget as the
default and CI profiles. Timeout exceptions must be nextest overrides matching
the smallest stable set of test names; do not raise the whole debug profile.
The periodic T^2 builder smoke test and its matching-explicit-topology variant
have a 60-second override because debug exact-geometry cost varies materially
by platform. They remain in the normal suite because they cover distinct public
builder contracts and are fast in release builds. The optimized 5D intersection
agreement check receives a platform-neutral 60-second override because it can
reach the 10-second boundary on hosted runners. The randomized 5D full-report
agreement check receives the same focused override across platforms. The
translated 5D and complete 6D exact SoS expansion checks, including the D=6
adaptive-kernel checks that repeat the complete expansion, receive a focused
60-second override because their irreducible cold-path work can cross the
default boundary on hosted runners.
The release integration profile similarly grants 60 seconds on Windows only
to the promoted 4D property families that sit at the 10-second boundary there.
The 5D local-neighbor repair guardrail receives the same focused Windows-only
headroom because its hosted-runner runtime can cross that boundary.
The cospherical 3D `OnSuspicion` sequence property receives the same focused
headroom across platforms because hosted runners can cross the default
integration-test watchdog. The isolated downstream checkpoint fixture receives
a 120-second override because it intentionally performs a clean standalone
dependency build in a separate target directory to prevent Cargo feature
unification from masking the behavior under test. The overrides combine the
narrowest applicable platform, integration-binary, and test-name filters so
unrelated tests retain the normal budget. The deterministic 5D SoS in-sphere
property also receives a cross-platform 60-second override because each
generated case performs two complete exact expansions and can cross the
hosted-runner boundary.
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]`.
`just test-slow` is the maintained execution path for every test hidden by the
`slow-tests` feature, including feature-gated doctests. When changing a gate,
compare nextest discovery with and without `--features slow-tests`; a test is
not owned by the slow lane unless it appears in the feature-enabled catalog.
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 binary unit and CLI integration tests:
```bash
just test-cli
```
Run the slow correctness bucket:
```bash
just test-slow
```
---
## Documentation Tests
Public documentation examples must compile.
Public Rustdoc code fences must also use focused workflow preludes instead of
`use delaunay::prelude::*`; `scripts/tests/test_rustdoc_imports.py` scans only
repository-owned Rust sources under `src/` and fails on both kitchen-sink
imports and unterminated documentation fences.
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.
Tests for fallible topology moves, mutations, and repairs must prove the full
two-outcome contract. Establish that the pre-operation owner is valid through
the promised validation layers. For success, validate the committed state
through those layers. For failure, exercise meaningful post-mutation failure
stages where feasible, compare the complete observable owner state with the
pre-operation state, and revalidate the restored state. The comparison must
cover canonical topology plus affected indexes, caches, hints, identity,
generation, and provenance; recovered counts or a partial topology snapshot are
not sufficient evidence of failure atomicity.
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.