claudes_game/continue.md

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

Sim Engine Capabilities

Implemented

• Body propagation (elliptical + parabolic via Barker's equation)
• Orbital↔Cartesian transforms (full z-x-z Euler rotation)
• Velocity drift detection and element reconstruction
• Global coordinate computation (hierarchical parent→child)
• Spacecraft struct, loading, propagation
• Impulsive burns (prograde, retrograde, normal, antinormal, radial_in, radial_out, custom)
• TOML 1.0 config parsing

NOT Implemented (notify the user before beginning to refactor)

• SOI transitions
• Maneuver trigger system (TRIGGER_TIME, TRIGGER_TRUE_ANOMALY)
• Hohmann transfer calculations
• Rendezvous planning
• OrbitTracker
• Energy functions (KE, PE, total)
• Hyperbolic propagation

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 SECTIONs 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. Precalc scripts

• For each test file, create scripts/precalc_<test_name>.py that computes expected values.
• Check the capability matrix first — only use sim_engine.py for implemented features.
• Always output local-frame values (distances from parent, not global from origin).
  • C++ tests typically use local coordinates (e.g., vec3_distance(craft->local_position, (Vec3){0,0,0})).
  • Global distances are dominated by parent body positions (e.g., Earth-Sun distance swamps LEO orbit).
• Output C++-style comments with precalculated constants for embedding in the test.
• Run with: python3 scripts/precalc_<test_name>.py
• If sim_engine.py lacks a feature, use analytical formulas instead (but notify the user what feature was missing)

5. Process per file

• Pre-check: Verify the test file has a TOML config in old_tests/. If it doesn't, skip — it's likely hardcoded.
• Pre-check: Check if the test is already in tests/ (already refactored). Skip if so.
• Pre-check: Check the capability matrix — if the test needs SOI, maneuvers, rendezvous, etc., flag this before starting.
• Process one test file at a time.
• Create scripts/precalc_<test_name>.py and run it to get expected values.
• Copy from old_tests/ to tests/, rewrite using the pattern from test_true_anomaly_roundtrip.cpp.
• Rewrite TOML configs to TOML 1.0 inline table syntax (single-line {}).
• Build and verify: make test-build then ./build/orbit_test '[tag]' -s.
• Run full suite: make test.
• Verify no other tests broke — the new test shouldn't affect unrelated tests.
• Note any sim_engine.py features that were missing for this test (add to capability matrix if needed).
• notify the user about any broken tests (e.g., OrbitTracker bugs)
• Always ask for review before moving to the next file.
• Only commit when asked.