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.0console applications, invoked usingdotnet run, rather than xUnit/NUnit/MSTest (tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj,scripts/test.sh). - The comprehensive local sequence is
scripts/test.sh; it sourcesscripts/env.sh, prepares assets and runs managed, Python, rendering, audio and hash checks.
Assertion Library:
unittest.TestCaseassertions and context managers (tests/test_extractors.py).- C# local
Check/Nearfunctions 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.shor the inspected test projects.scripts/test-window-transitions.shrequires a prior build plus local Xvfb/Xfwm/session tools.
Test File Organization
Location:
- Separate
tests/directory; Python discovery sees roottest_*.py, while HUD Python tests are invoked explicitly (scripts/test.sh). - Each managed group has a project directory,
Program.csand optional JSON references (tests/GamePort.ActorContactTests/,tests/GamePort.JimmyGroundTests/).
Naming:
tests/test_<domain>.py,tests/GamePort.<Domain>Tests/Program.cs, and descriptiveoriginal-*-reference.jsonorexpected.jsonfixtures (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 printPASS(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.csprojlinkstools/binary/jimmy_landing_rotation_reference.jsonasoriginal-landing-rotation-reference.json. Check source availability when reproducing a suite. - Use
TemporaryDirectoryfor exports and symlink rejection fixtures; local-original integration cases can useskipUnless(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.pyusesstruct.pack('>H', len(row))and a syntheticOmCv/OmGWheader. - 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.jsoncontains complete saved observations;--native <observations.json>permits a fresh external observation comparison and--dumpemits 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 ignoredartifacts/, as specified byscripts/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.shortests/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.mdanddocs/compatibility.mdrecord 352 Python checks for the documented source checkpoint identified asbdca29dby 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
bf876e9and unchanged packages at924ad2f. 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.shprepares 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.shcreates 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 expectedNotSupportedException(tests/GamePort.ActorContactTests/Program.cs).
Numerical comparisons:
- Use tolerances appropriate to the specific observed contract:
.02fand 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