172 lines
11 KiB
Markdown
172 lines
11 KiB
Markdown
---
|
|
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_<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:**
|
|
```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 <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*
|