C Test Suite Developer Guide

Table of Contents

• 1. Test Layout
• 2. Canonical Targets
• 3. Where A Test Belongs
• 4. Fixture Helpers
• 5. Conventions
• 6. Temporary Files
• 7. Adding A New C Unit Suite

This page documents how the PETSc-backed C testing layer is structured and how to extend it safely.

1. Test Layout

Key directories:

• tests/c/: C test sources and shared fixture helpers
• tests/smoke/: executable smoke runner and reserved tiny fixture directories
• tests/fixtures/: Python/control-plane YAML fixtures

Current C files:

• test_support.h
• test_support.c
• test_install_check.c
• test_geometry.c
• test_solver_kernels.c
• test_particle_kernels.c
• test_io.c
• test_postprocessing.c

2. Canonical Targets

Canonical user-facing targets:

• make doctor
• make unit
• make unit-geometry
• make unit-solver
• make unit-particles
• make unit-io
• make unit-post
• make smoke
• make check

Compatibility aliases (install-check, ctest*) should be preserved for continuity, but documentation and new contributor guidance should always prefer the canonical names.

3. Where A Test Belongs

Use this rule set:

• doctor:
  • only for installation/toolchain/PETSc viability checks
• unit-*:
  • for isolated functions, kernels, and small component seams
• smoke:
  • for real executable launch or tiny end-to-end entrypoint checks
• test-python:
  • for scripts/picurv, schema, and repository metadata behavior

If a test can run against a small local fixture without invoking the full executables, it almost always belongs in unit-*.

4. Fixture Helpers

tests/c/test_support.* provides the shared PETSc-backed fixture layer.

Current responsibilities:

• create minimal SimCtx and UserCtx fixtures
• create deterministic DMDA objects
• create deterministic DMSwarm objects
• seed identity metric fields
• create unique temporary directories under /tmp
• provide assertion helpers for reals, ints, vectors, and file existence

Future C tests should reuse these helpers instead of rebuilding fixtures inline unless a suite truly needs a specialized setup.

5. Conventions

Naming:

• keep file names aligned with the target name (test_io.c -> make unit-io)
• use function names that state the behavior under test

Assertions:

• fail fast
• print the failing context plus expected and actual values

Tolerances:

• 1e-12 for algebraic invariants
• 1e-10 to 1e-9 for interpolation and I/O round-trips
• exact equality for integer/state checks

6. Temporary Files

Rules:

• write temporary artifacts under /tmp
• never write repo-tracked test outputs
• keep paths easy to inspect (/tmp/picurv-test-*) so a failed test can be debugged manually

7. Adding A New C Unit Suite

Recommended workflow:

1. add or reuse a tests/c/test_<area>.c file
2. build on test_support.*
3. add a dedicated executable in the Makefile
4. expose a canonical unit-<area> target
5. add a compatibility alias only if it matches an existing naming family
6. document the new target in the README and testing guide if it is user-facing

1. Reference Scales

• Testing and Validation Guide
• Installation Guide