# Testing procedure

**13 October AI teardown applicability:** the old autonomous enemy AI is
removed on `codex/enemy-ai-rebuild`. Retained full suites must still discover their
complete current assemblies; deleting obsolete AI fixtures does not make historical
counts current. Run retained combat/entity/spawn/session checks against this revision
and report their exact selection. Legacy pack/arrival/roster-behavior campaigns below
are historical procedures until corresponding behavior exists again; they grant no
new campaign attempts. The [removal record](superpowers/plans/2026-10-13-enemy-ai-removal.md)
owns this checkpoint's evidence and omissions.

Use this procedure with [AGENTS.md](../AGENTS.md), the [complete catalogue](TEST_CATALOGUE.md) and [current project state](PROJECT_PLAN.md). A plan describes intent; source describes implementation; a saved report proves only its recorded revision/build, selection and conditions.

## Choose checks before running

The [delegated test execution policy](AGENT_WORKFLOW.md#delegated-test-execution) permits
a Sol 6.1 / Medium operator to execute a lead-selected substantial batch. The lead retains
strategy and evidence acceptance; transfer exclusive Editor ownership, freeze source and
retain every selection, identity, cleanup and retry safeguard below. Human-review timing
is chosen for playable implementation slices and does not lower these gates. Read-only
reviews do not authorize test execution or a test operator merely by selecting reviewers.

Use [the workflow](AGENT_WORKFLOW.md) to classify review effort and exploratory versus
integrated work. Those decisions do not lower the gates below. An isolated prototype
may use focused checks for its bounded question; promotion into the normal game requires
the affected integrated gates and required reviews. Human feel/balance/readability,
hardware and separate-network acceptance remain distinct. A prototype label never
relaxes authority, state ownership, release exclusion or campaign qualification/budgets.
For a prose-only change, inspect references/policy without running Unity. Read the
relevant catalogue entries for other boundaries rather than every fixture by default.

Write a brief verification packet in the task record: changed behavior/boundary, files/assets, focused checks, remaining integrated gates, reusable evidence and its identity, estimated duration (or unknown), escalation triggers and stop condition. This is not an additional approval step.

| Changed boundary | During work | Integrated acceptance |
|---|---|---|
| Prose/instructions | Inspect links, parameters, consistency | No Unity tests/builds by default; documentation checks only if export/executable docs changed |
| Pure rules | Relevant fixture | Full EditMode; affected native contracts if rules drive runtime behavior |
| Pack contact/navigation/actions | Relevant rules and actual actor/native fixtures | Relevant full suites once; affected two/four-player combat and lifecycle checks |
| Receipts/observer/export/capture | Scope/isolation/serialization/capture fixtures | Affected native cases and representative actual export/render; escalate if production timing, visibility or lifecycle changes |
| Owner movement/authority/session | Clock/credit/input/lifecycle regressions | Full relevant suites; matching two/four-owner and warp/lifecycle checks; affected normal-stage progression |
| PowerShell launcher/reporting | Controlled arguments, classification, cleanup, parser checks | Representative affected real cohorts; progression matrix only when its path changed |
| Runtime/development compilation/debug assets | Relevant source checks | Necessary normal/debug/release builds and release exclusion |
| Natural arrivals | Retained artifact qualification first | Resume only eligible unfinished cells when needed and authorized; preserve cumulative budget |

Select by the actual boundary, not a task label. A navigation change can affect movement, authority and damage. Record omissions with reasons; a focused pass does not close omitted gates. Freeze integrated source, run broad checks once, then repeat only checks invalidated by fixes/new evidence. Stop once agreed checks pass. Do not change deadlines, assertions or geometry to obtain a pass.

Examples: a documentation typo needs link/prose inspection; a pack-navigation fix needs relevant pure/native fixtures then integrated pack and affected two/four-player lifecycle proof; a remote movement-credit fix requires broader authority, owner, warp and affected stage regression. Neither the typo nor a timing-only sidecar automatically requires three player builds.

## Editor prerequisites and execution

Verify connected project, pinned version from `ProjectSettings/ProjectVersion.txt`, stopped/playing state, import/compile readiness and Console errors. Current pins: Unity 6000.6.4f1 and Test Framework 1.8.0 (read manifest/version files again before execution). Use supported Unity CLI/MCP operations; C# below belongs inside an Editor command, not PowerShell. Never launch a second Editor against an already-open project to run tests.

Only one test/discovery/build operation at a time in the shared Editor. Coordinate exclusive ownership with other agents and the manual Test Runner. Do not cancel unrelated jobs or clear a lease merely because a caller timed out. Preserve the active scene/unsaved authoring and restore owned settings after verification.

Assemblies are exactly `ProjectI.Foundation.EditModeTests` and `ProjectI.Foundation.PlayModeTests`. Full entry points retain full-assembly meaning:

```csharp
ProjectI.Editor.FoundationTestRunner.RunEditMode("task-integrated-editmode");
// Run only AFTER the previous request has finalized:
ProjectI.Editor.FoundationTestRunner.RunPlayMode("task-integrated-playmode");
```

Existing focused entry points accept discovered exact fixture or method names:

```csharp
ProjectI.Editor.FoundationTestRunner.RunEditModeFiltered(
    "movement-focused", "ProjectI.Tests.ReceivedMovementBudgetTests");
ProjectI.Editor.FoundationTestRunner.RunPlayModeFiltered(
    "navigation-focused", "ProjectI.Tests.EnemyPackNavigationPlayModeTests");
```

Use exact multi-fixture selection for predictable native scope:

```csharp
ProjectI.Editor.FoundationTestRunner.RunFixtures("pack-focused",
    UnityEditor.TestTools.TestRunner.Api.TestMode.PlayMode,
    new[] { "ProjectI.Tests.EnemyPackNavigationPlayModeTests",
            "ProjectI.Tests.EnemyCoverGraceTests" });
```

Never guess NUnit filter expressions or assume a typo means a full run. Fixture requests must identify actual discovered fixture types; namespaces/method prefixes are rejected. A skipped, missing, duplicate, zero-case or wrong-mode result is not GREEN. Deliberate RED remains labelled failed evidence; documented historical skips remain skips.

`Integration.Arena` identifies the expensive all-scenario arena fixture; it remains included in full PlayMode. Feature categories aid discovery, while exact `RunFixtures` selections avoid category/filter ambiguity. No assembly split or shared cross-fixture session is introduced.

## Reports and identity

New runner requests use unique `TestResults` directories with request identity, XML/text and final JSON. Read the manifest's validation/status, requested/discovered/executed leaves, mode/assembly and failures before trusting counts. A finished operation can still produce invalid evidence. Legacy `TestResults/<label>.xml/.txt` paths are compatibility copies only: they never replace an earlier label. Follow the unique directory for reused labels. Incomplete output without a final manifest is not a pass.

The pinned public API provides an execution GUID but callbacks lack that GUID and there is no public active-job query. Request ownership relies on serialized local state plus observed starts/leaf identity; observed competing or ambiguous callbacks must fail closed. An unobserved manual operation started before the monitor was registered is a limitation, so confirm the Test Runner is idle before starting. Domain reload is expected for PlayMode and is not itself interruption.

Timeouts leave ownership uncertain. Inspect `FoundationTestRunner.ActiveRequestId` and `ActiveRequestStatus`, the Test Runner and request artifacts first. `CancelOwnedRun(requestId)` addresses only the recorded owned execution GUID; it requests cancellation, not successful completion. `RecoverInterruptedRun(requestId)` refuses recovery without exact owned terminal proof, no conflict and no outstanding external activity. A false cancellation result is never termination proof. Pinned PlayMode cancellation can omit `RunFinished`; its lease deliberately remains held. In that case stop the owned operation, confirm clean/stopped state and restart the Editor through supported tooling. Normal shutdown retains an interrupted/non-GREEN manifest; a process exit establishes that its in-Editor operation cannot survive. If shutdown hangs, stop only the verified closing Editor with required tool permission after preserving authoring/report state. Never edit SessionState or delete reports to release ownership. Interrupted requests cannot become successful retries. See [execution evidence](TEST_REFINEMENT_EXECUTION.md).

Runner compiled identity freezes the discovered project runtime/test/Editor dependency file inventory at request start and rehashes those exact files at finish. Source identity normalizes only the two enter-play-option lines that the pinned framework temporarily mutates; requested options are recorded separately, and the lead verifies restoration. All other source/assets/settings remain hashed. Tests against the normal no-reload setting and a genuine domain reload are distinct evidence.

`Tools/TestEvidence.ps1` adds `evidence.json` beside existing launcher `result.json`. It records runner/helper hashes, executable, managed assembly, complete built data fingerprint, current player source/assets/settings fingerprint (excluding Editor/Tests), player application build ID, network/cohort/profile, per-phase UTC bounds, Stopwatch elapsed and cleanup errors. Current-source hashes and built-data hashes are separate identities: they alone do not prove the build was produced from current source. Keep the matching build report/source provenance. Identity is rechecked after cleanup; a change invalidates attribution. Missing build/identity is retained as unavailable and cannot pass.

Timing phases can nest (operation inside scenario/setup); do not sum overlapping phases. `total` includes launcher setup, observation, result publication and cleanup, excluding the sidecar's own final serialization/write. UTC is attribution; elapsed uses a monotonic Stopwatch. Unmeasured import/network/render costs remain unknown, never zero. No hard speed threshold or promised percentage follows from one machine.

## PowerShell launchers

Run from the repository root, with matching development builds and free-tier services available. These commands launch real players; select them deliberately:

```powershell
& .\Tools\Test-TestEvidence.ps1                 # Controlled contracts; no players
& .\Tools\Test-DebugArena.ps1 -Players 2 -ResetCycles 2
& .\Tools\Test-DebugArena.ps1 -Players 4 -ResetCycles 2
# Deliberate soak (the direct-caller default remains 10):
& .\Tools\Test-DebugArena.ps1 -Players 4 -ResetCycles 10
& .\Tools\Test-OwnerArrivalInput.ps1 -Players 2
```

Routine two-cycle selection retains the retained damage-and-weakpoint scenario, intentional failure proof, remote-player disconnect, host loss, rehost/rejoin and owned-process cleanup. `-SkipFailureProof`/zero cycles must be reported as exclusions; they do not satisfy affected full acceptance. `-DeliberateFailure` must exit nonzero. Normal scenario failure, fixture invalidity, launcher/process failure and cleanup failure remain separate from the positive intentional failure-path proof.

Schedule common normal menu/full-stage regressions once after the required arena cohorts and confirmed owned-player cleanup:

```powershell
& .\Tools\Test-MainMenu.ps1
& .\Tools\Test-EncounterPolish.ps1 -VerdantInitial -DelayMs 75 -JitterMs 15 -LossPercent 1
```

The arena launcher's existing `-RunNormalRegression` convenience option runs those checks after arena cleanup. It does not make per-cohort repetition necessary. Normal progression requirements affected by production changes remain required; compatible prior evidence may be cited explicitly for unchanged boundaries. Owner-input HUD traces retain `naturalCampaign=false`: movement proof does not qualify natural arrivals.

Only launched process objects are stopped; exit must be confirmed. A cleanup error blocks common regressions and acceptance, preserves the primary failure and is written separately. Known process exit/build identity mismatch should fail promptly; retain operation ceilings and stability windows. Cloud outages are infrastructure failures; do not loosen assertions or enable paid billing.

## Campaign resume and evidence reuse

No new random attempts or extra budget are authorized merely by this testing refinement. The accepted campaign remains nineteen attempts/forty-four captures with four incomplete cells; consult [arrival validation](PACK_ARRIVAL_VALIDATION.md) for identity and exact original/exception budgets. Optional early-stop is deferred because useful surplus qualified observation has not been demonstrated.

Inspect existing data first. `Test-OrdinaryArrivalCampaign.ps1 -CampaignDirectory <existing-directory> -Cells four-split -ValidateOnly` validates retained evidence without launching another attempt. Remove `-ValidateOnly` only when new work is needed and authorized. `-CampaignDirectory`, `-Cells` and `-PreviousCampaignDirectories` retain history; do not change hashes to force compatibility. The existing rules enforce managed/source/route/bootstrap/network identity, qualified-cell skipping and cumulative attempts/time. The separately authorized fourth-attempt exception is not a fresh budget and must not be generalized.

Missing Large selection, owner death, unfinished tail, pending/missing captures or route/layout proof remain incomplete. Final exported qualification and actual image inspection are distinct. No automatic reroll substitutes for human control/readability, representative hardware or separate-network acceptance.

Reuse historical evidence only for unchanged requirements and compatible source/assets/builds/settings. State its path/date/identity, what remains valid and what changed. Never label reused evidence fresh or combine mismatched sources into one checkpoint.

## Failure response and completion

| Outcome | Response |
|---|---|
| Product/assertion failure | Preserve evidence; reproduce focused failure and fix the responsible layer |
| Invalid fixture/setup | Repair demonstrated setup defect; rerun affected case; no fake contact/movement |
| Compile/discovery/identity failure | Fix readiness/selection/attribution; zero cases cannot pass |
| Infrastructure outage | Retain failed attempt; bounded retry only after external condition changes |
| Interrupted/ambiguous ownership | Confirm operation state; explicit safe recovery; retain invalid/interrupted report |
| Incomplete natural coverage | Record missing requirement; no fabricated coverage or extra rerolls |
| Cleanup failure | Preserve primary failure and process errors; verify owned processes ended before continuing |

Report changed behavior, focused and integrated checks actually run, reused historical evidence, omissions with reasons and remaining manual/network/hardware acceptance. The [execution record](TEST_REFINEMENT_EXECUTION.md) carries this refinement's fresh results. Documentation-only edits need no gameplay run. Wiki source links use the existing collector; refresh/check documentation exports when those references change.