# Test Refactoring Optimization Strategy

## Tooling
- `scripts/sim_engine.py` — Generic orbital mechanics simulator (Python, TOML 1.0 configs)
  - Replicates C++ physics: Kepler propagation, orbital↔Cartesian transforms, drift detection
  - Multi-body hierarchical propagation with global/local coordinate tracking
  - Use for precalculating expected values (transition times, final states, energy conservation)
- TOML configs in `tests/` must use TOML 1.0 inline table syntax (single-line `{}`)
  - Old configs in `old_tests/` use multiline inline tables (toml-c17 style) — keep for reference
  - Python's `tomllib` requires single-line inline tables

## 1. Structure
- One `SCENARIO("description")` per logical test group, with `[tag1][tag2]` annotations
- Shared fixture: all constants, structs, and variables declared between `SCENARIO` opening and first `SECTION`
- Precompute expected values analytically at fixture level (use `scripts/*.py` for complex simulations)

## 2. Duplication elimination
- Use lambdas that capture the fixture for repeated setup→call→assert patterns
- Reuse shared structs in-place (mutate fields rather than recreating)
- Single-line `SECTION`s when body is one statement: `SECTION("name") { helper(arg); }`

## 3. Assertions
- `using Catch::Matchers::WithinAbs;` after includes
- `REQUIRE_THAT(value, WithinAbs(expected, tolerance))` — never `Approx()`
- Tolerances based on actual observed errors, tightened aggressively (1e-12 for angles, 1e-6 for meters, etc.)
- Replace qualitative checks (`a > b`) with quantitative (`WithinAbs(expected, tol)`)
- `INFO("label: " << value)` for debugging context

## 4. Process per file
- Process **one test file at a time**.
- For each file, **discuss with the user** how to precompute `REQUIRE` values — analytical formulas, Python scripts, or simulation runs.
- Copy from `old_tests/` to `tests/`, rewrite, rebuild, verify.
- **Always ask for review** before moving to the next file.
- **Only commit when asked.**

## 5. Testing Harness TODOs
- [ ] `OrbitalMetrics::angular_position` — uses `atan2(y, x)` which is XY-plane only; meaningless for inclined orbits