Story: Add compass test run: build and run unit tests via compass

Table of Contents

This page documents a story in Sprint 20. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

Running tests today means knowing the cmake target zoo (rat, test_<component>.tests) and, for direct binary runs, hand-loading the .env test environment. Compass already owns test-result inspection (compass test results) and test logging (compass test logging); this story completes the pillar with compass test run.

Use cases:

  1. Run all tests — compass test run → delegates to the rat target.
  2. Run a composite component's tests — compass test run refdata → discovers and runs every test target under the component (ores.refdata.api.tests, ores.refdata.core.tests, …).
  3. Run a specific component's tests — compass test run refdata.core → the test_ores.refdata.core.tests cmake target.
  4. Filter by Catch2 name or tag — compass test run refdata.core --filter "[repository]" (or a test name) → compass invokes the test binary directly, loading .env into the process environment first.
  5. Build first — --build builds the relevant targets before running; compass just calls cmake (no parallel build logic of its own).

The preset comes from ORES_PRESET in .env (as compass test results already does), overridable with --preset.

2. Status

Field Value
State DONE
Parent sprint Sprint 20
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-06-12

3. Acceptance

  • compass test run runs the full suite via the rat target.
  • compass test run <component> runs all of a composite component's test targets; compass test run <component>.<part> runs one.
  • --filter <name-or-tag> passes a Catch2 filter to the test binary, with .env loaded into its environment.
  • --build builds the targets first by calling cmake; without it, existing binaries are used as-is.
  • --preset overrides the ORES_PRESET default from .env.
  • compass test results picks up the run's XML output unchanged.
  • The run-the-tests recipe is updated to lead with the compass command (and its stale -DORES_TEST_LOG_LEVEL / parse_test_results.py references are fixed).

4. Tasks

Task State Start End Description
Implement compass test run DONE 2026-06-12 2026-06-12 The test pillar's run subcommand: all tests, composite/component targets, Catch2 filters, –build and –preset.

5. Decisions

6. Out of scope

  • CI integration — CI keeps calling cmake targets directly.
  • Test sharding/parallelism beyond what ctest already provides.

7. Promoted from capture

Originally the sprint-19 story of the same UUID, abandoned at sprint close and carried to the backlog inbox; re-promoted 2026-06-06 with goal, acceptance and out-of-scope lifted back into the live sections verbatim.

Emacs 29.3 (Org mode 9.6.15)