--- last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 last_mapped_at: 2026-11-12 --- # Testing Patterns **Analysis Date:** 2026-11-12 ## Test Framework **Runner:** - Python standard-library `unittest`; no pinned Python test framework package is detected (`tests/test_extractors.py`, `scripts/test.sh`). - Standalone C# `net10.0` console applications, invoked using `dotnet run`, rather than xUnit/NUnit/MSTest (`tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`, `scripts/test.sh`). - The comprehensive local sequence is `scripts/test.sh`; it sources `scripts/env.sh`, prepares assets and runs managed, Python, rendering, audio and hash checks. **Assertion Library:** - `unittest.TestCase` assertions and context managers (`tests/test_extractors.py`). - C# local `Check`/`Near` functions or recursive JSON comparisons that throw exceptions (`tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`). **Run Commands:** Run from the GamePort repository root; these are recorded commands, not checks executed by this mapping. ```bash source scripts/env.sh python3 -m unittest discover -s tests -p 'test_*.py' -v scripts/test.sh dotnet run --project tests/GamePort.ActorContactTests dotnet run --project tests/GamePort.JimmyGroundTests dotnet run --project tests/GamePort.DataTests -- ../Original python3 tests/GamePort.HudTests/test_ui.py SDL_AUDIODRIVER=dummy dotnet run --project tests/GamePort.AudioPauseTests NEUTRON_WINDOW_TEST=1 scripts/test.sh scripts/test-window-transitions.sh ``` - No dedicated watch or coverage command is detected in `scripts/test.sh` or the inspected test projects. `scripts/test-window-transitions.sh` requires a prior build plus local Xvfb/Xfwm/session tools. ## Test File Organization **Location:** - Separate `tests/` directory; Python discovery sees root `test_*.py`, while HUD Python tests are invoked explicitly (`scripts/test.sh`). - Each managed group has a project directory, `Program.cs` and optional JSON references (`tests/GamePort.ActorContactTests/`, `tests/GamePort.JimmyGroundTests/`). **Naming:** - `tests/test_.py`, `tests/GamePort.Tests/Program.cs`, and descriptive `original-*-reference.json` or `expected.json` fixtures (`tests/test_actor_contact.py`, `tests/GamePort.DirectorTests/original-camera-rotation-reference.json`). **Structure:** ```text tests/ test_extractors.py test_actor_contact.py GamePort.ActorContactTests/ GamePort.ActorContactTests.csproj Program.cs expected.json GamePort.JimmyGroundTests/ Program.cs original-ground-reference.json ``` ## Test Structure **Suite Organization:** Use deterministic inputs and assertions with descriptive failures. Actual Python pattern from `tests/test_extractors.py`: ```python class BoundedReaders(unittest.TestCase): def test_read_bounds_and_negative_size(self): for size in (-1, 2): with self.assertRaises(FormatError): Reader(b'x').take(size) ``` Actual C# comparison helper from `tests/GamePort.JimmyGroundTests/Program.cs`: ```csharp static void Check(bool condition,string name) { if(!condition)throw new Exception(name); } static void Near(float value,float expected,string name) => Check(float.IsFinite(value)&&Math.Abs(value-expected)<.02f, $"{name}: {value} != {expected}"); ``` **Patterns:** - Top-level managed programs load JSON using `AppContext.BaseDirectory`, enumerate cases, compare every relevant field, check case counts and print `PASS` (`tests/GamePort.JimmyGroundTests/Program.cs`). - Test projects copy saved fixtures into output and compile production files directly with explicit globs (`tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`). - Some fixture filenames are output links rather than colocated tracked files: `tests/GamePort.JimmyGroundTests/GamePort.JimmyGroundTests.csproj` links `tools/binary/jimmy_landing_rotation_reference.json` as `original-landing-rotation-reference.json`. Check source availability when reproducing a suite. - Use `TemporaryDirectory` for exports and symlink rejection fixtures; local-original integration cases can use `skipUnless(ORIGINAL.exists())` (`tests/test_extractors.py`, `tests/test_actor_contact.py`). Do not assume every original-dependent suite has a skip guard. ## Mocking **Framework:** No general mocking library is detected in the inspected projects. Use explicit fixtures, interfaces and callbacks (`tests/GamePort.ActorContactTests/Program.cs`). **Patterns:** The actor-contact fixture implements `IOriginalNormalBody`, logs each accessor and deliberately changes state on a later read (`tests/GamePort.ActorContactTests/Program.cs`): ```csharp public Vector4 ReadVelocity() { events.Add("Gv"); velocityGets++; if(FreshY && velocityGets == 2) Velocity.Y = 99; return Velocity; } ``` **What to Mock:** - Synthetic actor state, bounded callback endpoints, geometry and controlled getter mutations isolate original component behavior (`tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/actor-normal-contacts.md`). - Dummy SDL audio drivers isolate lifecycle/consumption checks; they do not establish audible output (`scripts/test.sh`, `docs/compatibility.md`). **What NOT to Mock:** - Preserve real parser byte boundaries, production algorithms, archive identities and saved original observations; compare through the production implementation (`tests/test_extractors.py`, `tests/GamePort.ActorContactTests/Program.cs`). - Do not replace live GPU validation with a managed-only assertion; real headless Vulkan paths write readbacks (`scripts/test.sh`, `src/GamePort/Program.cs`). ## Fixtures and Factories **Test Data:** - Build minimal byte fixtures with explicit endian packing, e.g. the RGB555 canvas case in `tests/test_extractors.py` uses `struct.pack('>H', len(row))` and a synthetic `OmCv`/`OmGW` header. - Use `Fixture.Reset(kind)` to seed reproducible body state and clear event logs before each named observation (`tests/GamePort.ActorContactTests/Program.cs`). - Preserve source-executed references rather than deriving all expectations from the port. `tests/GamePort.ActorContactTests/expected.json` contains complete saved observations; `--native ` permits a fresh external observation comparison and `--dump` emits port states (`tests/GamePort.ActorContactTests/Program.cs`). **Location:** - Saved component references live beside managed projects (`tests/GamePort.DynamicReclipTests/expected.json`, `tests/GamePort.GrapplerTests/original-query-reference.json`). - Original integration fixtures are external local `../Original`; never modify them (`AGENTS.md`, `tests/test_extractors.py`). Generated extraction/replay outputs belong under ignored `artifacts/`, as specified by `scripts/test.sh`; this map does not inspect those outputs. - Binary tools validate complete original bodies, relocation operands, table bindings and generated-probe output separation (`tests/test_actor_contact.py`, `tools/binary/actor_contact.py`). ## Coverage **Requirements:** - No enforced percentage threshold or coverage collector is detected in `scripts/test.sh` or `tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`. - Use behavioral coverage: malformed lengths/counts/trailing bytes, coordinate/winding/UV identities, positive recovered behavior, explicit unsupported contracts, case completeness and callback read order (`tests/test_extractors.py`, `tests/GamePort.ActorContactTests/Program.cs`). - `docs/progress.md` and `docs/compatibility.md` record 352 Python checks for the documented source checkpoint identified as `bdca29d` by the mapping task. This is an existing receipt, not a fresh run or independently recounted total. - The same records distinguish integrated SDL/GPU evidence at `bf876e9` and unchanged packages at `924ad2f`. Do not attach the newest component counts to an older package or imply the latest component work reran graphics. **View Coverage:** Not detected. Consult `docs/compatibility.md` and subsystem reports for evidence scope rather than treating test count as gameplay completeness. ## Test Types **Unit Tests:** - Bounded readers, PackBits/PNG operations, numerical movement/orientation, task transitions, UI and standalone collision components (`tests/test_extractors.py`, `tests/GamePort.JimmyGroundTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`). - Explicit unsupported-path checks require exceptions instead of silent admission; zero-horizontal reflection is rejected in `tests/GamePort.ActorContactTests/Program.cs`. **Integration Tests:** - Decode actual local archives and compare counts, models, materials, textures and exported references (`tests/test_extractors.py`, `tests/GamePort.DataTests/Program.cs`). - `scripts/test.sh` prepares scenes/audio, verifies assets, runs save/load checks, SDL dummy audio lifecycle checks, Vulkan renders and original manifest verification. - Differential component probes execute copied original instructions with synthetic state under Wine32, then compare port snapshots; complete-body/operand guards and provenance are described in `docs/checkpoint/actor-normal-contacts.md`. This is stronger than a port self-comparison but remains a bounded component experiment. **E2E Tests:** - Port smoke flows cover story/practice/RETURN routes, cutscenes, gadgets, input, windows and real GPU readbacks (`scripts/test.sh`, `src/GamePort/Application/WindowTransitionSmoke.cs`). - Optional window checks are gated by `NEUTRON_WINDOW_TEST=1`; `scripts/test-window-transitions.sh` creates a private Xvfb session with Xfwm to support asynchronous fullscreen requests. - Whole-original gameplay equivalence and native Windows runtime are separate open evidence gates (`docs/compatibility.md`). Windows cross-publishing is compiler/package evidence; Wine execution is preliminary compatibility evidence. ## Common Patterns **Async Testing:** - No general async test runner pattern is detected in the inspected console/Python suites. SDL/window progression is exercised through frame-driven smoke state and real window-manager acknowledgements (`src/GamePort/Application/WindowTransitionSmoke.cs`, `scripts/test-window-transitions.sh`). **Error Testing:** - Python uses `assertRaises` / `assertRaisesRegex`, including rejection of original-directory and symlink output (`tests/test_extractors.py`, `tests/test_actor_contact.py`). - Managed tests call unsupported paths inside `try`, throw if accepted, and catch only the expected `NotSupportedException` (`tests/GamePort.ActorContactTests/Program.cs`). **Numerical comparisons:** - Use tolerances appropriate to the specific observed contract: `.02f` and finite checks for ground motion; decimal-place comparisons for exported ASE positions/UVs (`tests/GamePort.JimmyGroundTests/Program.cs`, `tests/test_extractors.py`). - Actor-contact snapshots compare JSON field shapes, array counts, event order and `GetSingle()` values exactly; do not weaken exact float32 checks by borrowing another suite's tolerance (`tests/GamePort.ActorContactTests/Program.cs`). - Preserve source float-store boundaries rather than declaring all double intermediates a universal x87 equivalent (`docs/checkpoint/dynamic-reclip.md`). **Verification reporting:** - State separately: compiler success, managed/Python assertions, copied-original component execution, port rendering/native SDL input, package provenance, whole-original comparison, and native Windows gameplay (`AGENTS.md`, `docs/progress.md`, `docs/compatibility.md`). - No builds or tests are executed for this mapping; commands and evidence above describe the checked-in source and documented receipts. --- *Testing analysis: 2026-11-12*