Files
2026-11-12 11:06:58 -05:00

11 KiB

last_mapped_commit, last_mapped_at
last_mapped_commit last_mapped_at
bdca29d3aa 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.

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_<domain>.py, tests/GamePort.<Domain>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:

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:

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:

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):

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 <observations.json> 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