Agent notes — tests/

CRITICAL: Complete the mandatory AGENTS.md preflight in ../AGENTS.md before editing here.

Layout

Pytest and Catch2/CTest suites generally live under this tree:

tests/
  cpp/       ← Catch2 executables (one target per module leaf)
  python/    ← pytest suites (one pyproject.toml per leaf)

Organize by product area, mirroring src/ and examples/:

Shared C++ fixtures (not executables) live under tests/cpp/viz/support/ (viz::test_support, viz::layers_testing).

Naming invariants (CI depends on these)

• Catch2 executable names stay stable: schema_tests, viz_core_tests, viz_layers_tests, … CI globs viz_*_tests for GPU packaging.
• CTest name prefixes stay stable: schema_*, retargeting_*, viz_python_*, etc.
• Catch2 tags → CTest labels via ADD_TAGS_AS_LABELS (unit, gpu, xr).

Python conventions

• Each leaf directory has its own pyproject.toml so uv run resolves deps locally (mujoco pins, asyncio, cupy extras, grounding/wuji extras).
• After updating CloudXR import or mock-patch paths for the isaaccapture package, run ruff format on the touched tests; longer paths can change multiline layout.
• Format changed Python tests before staging; if pre-commit rewrites a file, restage the result and rerun the full hook set.
• Use raw strings for regular-expression patterns passed to pytest.raises(..., match=...); Ruff rejects escaped metacharacters in ordinary strings.
• CTest runs one pytest invocation per test_*.py with WORKING_DIRECTORY set to that leaf.
• Use repo_paths.py for paths into src/python/ or examples/ from conftest.py — do not hard-code parents[N] against repo depth.
• If CMake under examples/ reads a file under tests/, guard it on the in-tree configure: standalone wheel builds use the example as CMAKE_SOURCE_DIR, not the repo root.
• A stand-in child process must stay alive on its own (python -m <builtin> exits at once), and Popen() can return while the child's /proc/<pid>/cmdline still reads empty or the parent's argv: wait for the child's own argv before any check, including one that expects no match, which either stale value passes without testing anything (python/core/cloudxr/test_background.py does both).

Adding tests

1. Pick the matching tests/{cpp,python}/<area>/<module>/ leaf (create it if new).
2. Add sources + leaf CMakeLists.txt (copy an existing sibling).
3. Wire the leaf from the parent CMakeLists.txt under the same BUILD_* gates as before (e.g. viz tests require BUILD_VIZ).
4. Do not colocate new pytest/Catch2 trees under src/ or examples/.

• FlatBuffers generated VT_* constants are vtable offsets, not schema field IDs. Compare them with (field_id + 2) * 2, as the existing schema tests do.

Out of scope here

• Vehicle teleop worker tests belong in examples/vehicle_teleop/tests/, alongside the example they exercise.
• src/core/codegen/test_*.py — unittest, co-located with the generator.
• tests/python/xr_runtime/ — standalone scripts for CloudXR GPU CI, not pytest: no pyproject.toml or CTest wiring. scripts/run_tests_with_cloudxr.sh lists the ones CI runs.
• ROS2 Docker integration helpers under examples/teleop_ros2/.../integration_tests/.
• scripts/sbom/tests/ — the SBOM collector's tests, run from its own uv project.