08 — Test coverage (behavioral)¶

No line/branch % claimed — no coverage tool is wired. This page is the definitive behavioral FEATURE × TEST matrix from the live tree: what is tested, where, and how. Gate wiring (lefthook, ctest registrations) lives on quality-gates.md and is only referenced, not repeated.

Dual harness (+ script gates)¶

HOW legend — golden = real Benchy fixture with hard asserts; synthetic = embedded gcode/XML/temp files; crafted = byte-patched ZIP; bridge = P/Invoke into the real libNPSEngine.so; headless = Avalonia.Headless real controls; logic = pure managed math; ABI smoke = entry-point call without semantic assert; structural = grep/nm/script scan.

Golden fixture¶

4-colors+Benchy+AMS+test-v2.3mf (repo root) = 1 plate / 16562 vertices / 33097 triangles / 4 palette colors (0xFFC12E1F, 0xFFFEC600, 0xFF00AE42, 0xFF0A2989). Constants pinned at engine_tests.cpp:97-98; resolver ResolveBenchyPath() (:106), RAII BenchyFixture (:143). The fixture-present pre-push hook (lefthook.yml:139-140) refuses to push without it — there is no synthetic fallback for loader tests.

Consumers (hard golden asserts, not smoke):

Test-hook-gated exports (why they exist)¶

NPS_ENABLE_TEST_HOOKS (src/Engine/CMakeLists.txt:31, auto-ON when BUILD_TESTING=ON at :50-60, defined at :212-213) compiles extra C ABI entry points that let both harnesses drive internals without exposing them in production: TestParseModelXmlForHarness, TestZipReaderExtractModelAndMetadata, TestZipReaderDirectError, TestGetPlateThumbnailSize, GetMeshBounds (abi/nps_c_api.h:247-274), TestGcodeParseForHarness, TestThermalGridForHarness, TestStructuralScoreForHarness, TestAnalysisManagerThermal (:398-411). GetMeshBounds is test-gated because no app/C# consumer exists — production computes bounds from the vertex stream. The production gate (nps-n1m-12-production-gate.sh) asserts zero Test* symbols via nm -D; see quality-gates.md for why that gate never runs inside lefthook (hooks always build Debug+tests).

Feature × test matrix¶

C++/C# cells give line anchors (engine_tests.cpp / the named C# file).

Load / 3MF / ZIP¶

G-code generation & parsing¶

Analysis & material¶

Findings / overlays / viewport¶

C# facades & UI¶

Errors, ABI, scripts, perf¶

Zero-coverage rows (brutally honest)¶

1. ViewportToolbar — CLOSED (nps-oro.2): 22 Facts in ViewportToolbarTests enumerate the 10 code-built controls + tooltips (ViewportToolbarTests.cs:99–:189), drive every button click through Button.ClickEvent and verify *Clicked fires exactly once (:193–:339), drive both toggles through flipped-IsChecked + Click to verify the bool payload (:340–:436 + :521–:559), and wire the toolbar to a real ViewportController to verify preset clicks change vc.Camera across all six orientations (:437–:520) and zoom-fit clicks change vc.Camera.Zoom / PanX / PanY (:560–:626).
2. Playback runtime — CLOSED (nps-oro.1): 6 Facts in AppHeadlessSmokeTests:1410-:1758 drive PlayPauseClicked / StepClicked / AutoPause / ScrubberPointerPressed/Released / SpeedChanged / ScrubberChanged through the public panel surface into the real MainWindow handlers (SimulatorApp/MainWindow.axaml.cs:510-658). Observable contract: panel.IsPlaying, status substring, _simMoveIndex mirror, _playTimer.Interval.
3. App event handlers — CLOSED (nps-oro.3) for all reachable branches: OnLoadAnalyzeClick driven through LoadAndAnalyzeFromPath seam with both fixture-missing and invalid-file paths (AppHeadlessSmokeTests:367,:420,:791,:843); OnApplySliceClick driven via XAML button before/after load (:531,:572); OnOverlayModeChanged driven via reflected OverlayPanel.ModeChanged (:657,:998); OnLayerSliderChanged driven via Slider.Value (:615,:958); OnFindingSelected driven via FindingsPanel.FindingSelected for both pinned and unpinned (-1) move indices (:727,:1052,:1115). Both apps covered. Engine-side-only (4 Skip facts, AppHeadlessSmokeTests:1447-:1467): RunGenerate gen-failed (SlicerApp/MainWindow.axaml.cs:441-443; SimulatorApp/MainWindow.axaml.cs:557-559) and analyze-failed (SlicerApp/MainWindow.axaml.cs:503-506; SimulatorApp/MainWindow.axaml.cs:579-582) branches are unreachable from production today — Engine::GenerateGcode returns NPS_RESULT_SUCCESS unconditionally (src/Engine/engine.cpp:1433) and Engine::AnalyzeGcode is void (src/Engine/engine.cpp:1479-1488); covered engine-side by EngineSessionTests.GenerateDemoToolpath_AfterBenchyLoad_ReturnsMoves (:166) and EngineSessionTests.Findings_AreEmptyBeforeAnalyze_AndPopulatedAfter (:185). The Skip facts cite these engine-side tests and flip to real asserts the moment a future engine revision makes either op return a failure code.
4. Pointer-drag orbit/pan + Zoom-to-Fit button — CLOSED (nps-oro.4 / nps-oro.2): synthetic press/drag/release through Avalonia.Headless asserts camera fields for both apps — unarmed move is a no-op, left-drag orbit clamps RotationXRadians at ±1.5 while applying the Z delta, right-drag pan scales by 0.5 / max(0.1, Zoom) (AppHeadlessSmokeTests:157 Slicer, :165 Simulator via the shared RunViewportPointerGestureSmoke:227). Zoom-to-Fit clicks reach ViewportController.Camera with aspect-preserving math (ViewportToolbarTests.cs:561,:598).
5. UI error paths — CLOSED (nps-oro.3): 5 facts across both apps drive the load-failed / fixture-missing / Apply-before-load branches through the real OnLoadAnalyzeClick + OnApplySliceClick handlers (AppHeadlessSmokeTests:367,:420,:531,:791,:843). Each error branch asserts the user-visible Shell.StatusText substring and that the engine session stays valid (IsValid==true, _modelLoaded==false, no move buffer populated).
6. MeshCanvasPainter + GcodeToolpathPainter happy path — CLOSED (nps-oro.4): GcodeToolpathPainterTests:75 draws parsed moves and asserts travel/extrusion Lines, colors, finding Ellipse markers, and the max-layer filter; MeshCanvasPainterTests:71 renders the golden Benchy mesh and asserts Polygon output stays within MaxTrianglesPerPlate=2000, :106 pins the empty-palette opaque-white fallback.
7. Warp grid risk values — CLOSED (nps-oro.5): engine_tests.cpp:1912 content-asserts the risk array cell-by-cell on a pinned synthetic input (values, not just size==gridW*gridH).
8. Analyzer value correctness — CLOSED (nps-oro.5 / nps-ai2.2): golden values pinned per analyzer — thermal engine_tests.cpp:1554 (score == totHeat == 0.04, findingCount == 1), structural :1594, motion :1640 (2-move tiny + cube junction clamp at 14.4). Motion profile inference is un-stubbed: inferProfileFromGcode applies real M204 P/T/S declarations (engine_tests.cpp:4096).
9. Retraction analyzer + MaterialCatalog C# parity, corrupt-bgcode, multi-plate fixtures, debug-mixed.ps1 — CLOSED (nps-oro.6): retraction C# parity (EngineBridgeTests:1639), MaterialCatalog POD roundtrip C# (:1770), corrupt-CRC bgcode warn-and-continue on the real fixture (:1904). Two gaps documented instead of tested: multi-plate stays untested by design (engine hardcodes plate_1, no fixture exists — tracked by feature bead nps-ai2.3) and debug-mixed.ps1 is wont-fix (Windows-only twin; bash twin covered at engine_tests.cpp:4213 + 4 ctest).

Golden blessing recipe (NPS_BLESS_GOLDEN)¶

The single visual-golden baseline (tests/golden/g6_orbit_render.sha256, tests/golden/g6_orbit_render.ppm) is fail-closed:

• A missing baseline = hard FAIL (C++ TEST_CASE("Visual/golden render parity …") at engine_tests.cpp:2650; C# VisualGolden_RenderOrbit_BytesMatchCppBaseline at EngineBridgeTests.cs:2214). No auto-write.
• A mismatch = hard FAIL + .drift PPM next to the baseline (C++ side only — for eog/xdg-open/byte-diff inspection).

Regenerating the baseline is an explicit, gated, human-reviewed operation. To (re)bless the baseline after a deliberate ABI/render change:

# C++ Catch2:
NPS_BLESS_GOLDEN=1 ctest --test-dir build --output-on-failure \
    -R "Visual/golden render parity"

# C# xUnit (mirrors the C++ test byte-for-byte):
NPS_BLESS_GOLDEN=1 dotnet test tests/NPSEngine.Tests \
    --filter "FullyQualifiedName~VisualGolden_RenderOrbit_BytesMatchCppBaseline"

Both harnesses gate on NPS_BLESS_GOLDEN=="1" exactly. The bless run WARNs in C++ (INFO log) and silently passes in C#; both write the new .sha256 (C++ also rewrites the .ppm). Subsequent runs without the env var then enforce the new baseline.

Mandatory review checklist before committing:

1. git diff tests/golden/g6_orbit_render.sha256 — new SHA must match what the C++ side just wrote (C# bless is byte-identical because the Bresenham oracle is mirrored).
2. Visually inspect the new .ppm against the previous one (eog tests/golden/g6_orbit_render.ppm or any image viewer). Drift should match the deliberate change (camera, color ramp, ABI).
3. If a mismatch run wrote .drift, byte-diff it against the committed .ppm to confirm the diff is exactly the intended change.

The baseline is committed (tests/golden/g6_orbit_render.sha256) and MUST NOT be deleted as a workaround for a missing baseline. If it's missing, run the bless recipe above; do not git restore the previous SHA without reviewing.

How to run each harness¶

# C++ Catch2 (Debug build auto-enables NPS_ENABLE_TEST_HOOKS):
cmake -S src/Engine -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel
ctest --test-dir build --output-on-failure

# C# xUnit (build the engine first; lib must be on the loader path):
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 $HOME/.dotnet/dotnet test tests/NPSEngine.Tests
#   (lefthook.yml:110 — place libNPSEngine.so next to the test binary or set LD_LIBRARY_PATH)

# Script fitness gates:
./scripts/layer-fitness.sh                 # live in pre-push
./scripts/no-placeholder-scan.sh           # live in pre-push
./scripts/structural-fitness.sh            # manual (gate disabled by design)
./scripts/closure-integrity.sh <beadId>    # manual close protocol

Re-count baselines:

grep -c 'TEST_CASE(' src/Engine/tests/engine_tests.cpp        # 76 (+17 TEST_CASE_METHOD)
grep -rnE '^\s*\[Fact' tests/NPSEngine.Tests/*.cs | wc -l     # 154 (+4 [Theory], 163 cases after Theory row expansion)

Optional future: gcov/llvm-cov + coverlet for true % — not wired today.

Full test inventory (every name)¶

Mechanically extracted from the live tree (same grep the re-count one-liners use). The matrix above groups them by feature; this list is the complete checklist the refresh gate diffs against.

See also¶

• quality-gates.md — lefthook/ctest wiring for every gate named here
• overview.md — golden fixture in the architecture context
• c-abi.md — the ABI surface the bridge tests pin