Self-test: the release smoke check

--self-test <scenario> plays a scenario inside the engine and exits with its verdict. It is how a release build is smoke-tested on every platform (docs/PLAN-PLATFORMS.md §8): a release engine serves no query API (G2), and on Android, iOS and the web there is nothing to connect to anyway, so the check runs in-process and needs no server.

argus run <project | scene.json> --self-test <scenario> [--headless]
<exported game> --self-test <scenario> [--headless]

• Exit code: 0 when every step and every check passed, 1 when anything failed, 2 when the scenario could not be found or read.
• Report: self-test.json, written to $ARGUS_SELF_TEST_OUT if set, else beside $ARGUS_LOG_FILE (an exported game's logs/ folder in its unpack directory), else the platform's log folder (%LOCALAPPDATA%\Argus\logs, ~/Library/Logs/Argus, $XDG_STATE_HOME/argus/logs or ~/.local/state/argus/logs). Captures are saved beside it as self-test-<name>.png. Besides the steps and checks it carries frames (ticks run), digest (the simulation's state at the end, WorldState::digest: every entity, its transform, script state, HUD and goals, so two engines given the same scenario can be compared) and screens at the end of the run: stack (screen names, bottom first), registered and the active input context, as /ui/screens names them. A release engine has no query API, so this is how a caller sees which menu is up.
• Saves: a run plays from no save, as a first launch does, in a folder of its own made in the system's temporary folder, so ctx.save neither reads nor writes the player's save. --save-dir or $ARGUS_SAVE_DIR names another folder, for a test that inspects what the game saved.
• Stdout: one line, argus-self-test {"ok":…,"scenario":…,"frames":…,"report":"<path>"}.
• Surface: never a window. Without --headless the engine renders offscreen, so the capture checks run; with --headless there is no GPU and every capture is skipped (reported as skipped, never faked). An exported game's launcher forwards --self-test and runs the engine offscreen unless --headless is given.
• Serving: none. --self-test conflicts with --serve, --watch and the session flags.
• Time: fixed 60 Hz ticks. Seconds and milliseconds in a scenario become ticks, so a scenario is deterministic in the critic build and never depends on how fast the machine is.

Finding the scenario

In this order:

1. a file path, absolute or relative to the working directory. An exported game's launcher runs the engine in its unpack directory, so it makes a relative path to a file it can see absolute against the folder the game was started from before handing it over;
2. <project root>/selftest/<name>.json. play, play.json and selftest/play.json (either slash) all name selftest/play.json. A project export, from engine export or the editor, packs the project's selftest/*.json at app/selftest/, so a shipped game runs its own scenarios by name;
3. smoke, the built-in scenario: 180 ticks, no script errors, and a frame that is not blank.

The format

One format for scripted play: the bench's step language (bench/README.md, "Scripts"; bench/lib/exportrun.mjs) with the same spellings, run against the world directly instead of over HTTP, plus an expect block.

{
  "selfTest": 1,
  "description": "What this scenario proves.",
  "maxFrames": 1800,
  "steps": [
    { "wait": "screen", "name": "main-menu", "top": true },
    { "press": "Start" },
    { "wait": "screen-gone", "name": "main-menu" },
    { "axis": "move", "value": [0, 1], "frames": 60 },
    { "capture": "playing" }
  ],
  "expect": { "goals": 1, "screen": "hud", "top": false, "scriptErrors": 0, "capture": "auto" }
}

selfTest is required, so a stray JSON file is never run as a scenario. Unknown keys are refused. maxFrames (default 3600) is the tick budget for the whole run; running out fails it.

Steps

Steps run one after another, and an action or axis step holds its one action for its frames before the next step starts: one step cannot hold two actions, so a steer step after a throttle step steers with the throttle released (a vehicle coasts through it).

Every waiting step takes timeout in seconds (default 15). A failed step stops the run: every later step assumed the ones before. The bench steps that only make sense from outside the process — launch, restart, checkUi, track, read, and the expect kinds var, moved, saved and exit — are refused by name rather than skipped.

XR steps (--xr-sim)

With the desktop XR simulator (argus run <project> --xr-sim[=profile] --self-test <scenario>, docs/status/xr-sim.md) a scenario places and works the head and both hands, in fixed ticks, so a VR game is checked with no headset. Every pose is in the XR origin's tracking space, or, with relativeTo, in that entity's own frame, worked out again every tick: a hand put on a moving vehicle's control stays on it.

An XR step in a run without the simulator fails, naming --xr-sim. The same scenario runs unchanged under every headset profile (--xr-sim=focus3, pico4, quest3, index, or a headset file): the poses are in the scene's frame, not the headset's.

Checks (expect)

"Not blank" means at least 0.5% of pixels differ from the frame's first pixel by more than 8 in some channel: a clear-colour frame, a black frame or a failed draw fails it.

Where it runs

• crates/app/tests/self_test.rs — the checked-in fixtures/selftest/starter-course-start.json on the starter course, and each way a scenario has to fail.
• packages/export/test/native.test.ts — --self-test smoke on a release export.
• scripts/release/matrix.sh — every platform the machine can build: the same scene export headless on Linux and Windows, and a project export offscreen on Linux, recorded in dist/release/<version>/MATRIX.json.

Known gap (not the self-test's): a scene-only export carries no font, and a scene that declares text refuses to load without one, so such an export can only run --headless. A project export packs a font under app/ui/fonts/ and renders. The matrix's capture check therefore runs on a project.