Test Via API

Test the workbench via API

The production luncosim exposes a reflect-registered Event API on --api PORT (default 4101). Always pass this flag when launching the luncosim, including visual checks; use another explicit free port if 4101 is occupied. UI verification — diagrams rendering, drill-ins, simulations, file ops — should be driven from this API rather than asking the user to click.

Mode policy

Use a headful windowed luncosim session by default whenever the work concerns a scene, Editor, viewport, UI, motion, layout, or any result the user needs to watch. Start the production binary with --api PORT and a graphical display; do not add --no-ui, --offscreen, or another windowless flag. Keep that window alive while iterating so the user can see each coherent change.

Use --no-ui/luncosim-server only for explicitly numeric or API-only checks where there is no visual acceptance claim. Use --offscreen only when the user specifically requests an offscreen recording or a graphics test that is meant to run without a visible window. If a requested visual check cannot run headfully, stop and report the display/session blocker instead of silently falling back to headless mode.

Live shader iteration

Shader source edits are a live-test path. Keep the production luncosim running, edit the WGSL under assets/shaders/, then dispatch ReloadShader through the same API. A bare engine path such as shaders/starfield.wgsl resolves the active default-source or lunco:// asset identity; an explicit lunco://… or twin://… path is exact. An empty path reloads every currently loaded WGSL asset, not an arbitrary hard-coded file list. The response reports the queued paths and fails if no active asset matches. Confirm the command result, then inspect the unchanged window; shader compiler errors remain in the render log. Do not relaunch the app just to pick up a shader edit.

Tutorial and Rhai iteration

For Twin lifecycle regressions, open an editor document in Twin A, replace it with Twin B, and inspect ListOpenDocuments plus USD preview state. No old document ID or preview may survive; repeat OpenTwin on B to verify fresh admission. A rejected Twin path must preserve the current documents. Twin replacement closes loose/library editor documents as well as Twin-owned files; RestartScene preserves editable documents and tests a different lifecycle. Pending editor and workspace-restore work must not recreate old tabs after replacement. Modelica CloseDocument is owned by the headless core, so exercise scratch-document closure in both headless and windowed hosts.

The maintained document-close scene gate is scenes/tests/twin_session_retirement/twin_session_retirement.usda with verdict channel TWIN_DOCUMENT_CLOSE. Run it through $LUNCOSIM_BIN test. The gate covers dirty SysML drafts as well as Modelica scratch documents; assert actual domain retirement rather than only removal from workspace metadata. The windowed switch/reopen/rejected-candidate gate is python scripts/api/test_twin_session_retirement.py; set LUNCOSIM_BIN and an explicit free LUNCOSIM_API_PORT. Its assertions are authored in assets/scenarios/tests/twin_session_retirement.rhai, and its process wrapper verifies API Exit and port release.

Tutorial behavior is authored in assets/tutorials/**/*.rhai and should be tested through its production scene gate in assets/scenes/tests/ with the observer in assets/scenarios/tests/. After editing either Rhai file, rerun ./scripts/run_scene_tests.sh --no-build --exact <scene-name> for a single scene, or ./scripts/run_scene_tests.sh --no-build <scene-substring> for a group; the runner uses four independent headless processes by default, and -j/--jobs N changes that bound (-j 1 is the serial diagnostic mode). This does not change each gate process's deterministic --threads 1 --jitter 0, and graphics assertions remain a separate serial offscreen pass. Do not rebuild the Rust core for a script-only change. The observer must verify public cmd:* events plus the resulting live state and emit a real verdict. Parsing or --validate is only preflight evidence.

The generic model-authoring facades have the same production gate. The focused fixture is model_authoring:

./scripts/run_scene_tests.sh --no-build --exact model_authoring -j 4

Its Rhai observer exercises model_context, readiness_report, scene_recipe, port_graph, wiring_plan, and publish_component, including fail-loud missing endpoint, control, asset, identity, and provenance cases. Use this narrow gate after changing the tool or its authored fixture; a parse pass alone does not prove the namespaced calls work in production.

The live port-owner collision contract is covered the same way:

./scripts/run_scene_tests.sh --no-build --exact port_owner_collision -j 4

Its USD fixture owns the duplicate and clean control cases; the Rhai observer calls RunLint and verifies the structured LintReport winner, shadowed owner, property paths, and precedence. Prefer this authored pair for observable lint behavior instead of embedding USDA or fake backend components in Rust tests.

Public USD query-provider behavior belongs in authored .usda fixtures and Rhai scene gates, exercised through the production query bridge. Keep Rust tests for provider internals only when the behavior cannot be observed through that public surface; do not construct DocumentRegistry worlds with inline USDA to duplicate inspection, target-resolution, or synchronization behavior. The usd_query_api gate covers those public contracts, while the assembly proposal lifecycle gate covers edit-session inspection.

Editor material edits belong in an authored USD fixture plus an editor Rhai scenario, not a Rust test with a multiline USDA string. The usd_material_edit_projection fixture exercises typed material edits, whole-source replacement, and the preview's projected-generation lifecycle through the production editor runner. Keep Rust coverage for the focused USD-to-render-intent mapping mechanism, where the mapping itself is the subject.

For source-preview isolation, run scripts/api/test_usd_source_isolation.py with an exact --scene, --source, composed --selection-path, free --port and --log. Its RunScenarioAsset invocation supplies all required parameters to assets/scenarios/tests/usd_source_isolation.rhai and requires eight authored checks, including invalid-source rejection, unchanged Twin/topology and advancing physics. --screenshot records the exact viewport/selection context; the shared ProductionSession.capture_screenshot requires fresh publication before API Exit. Pair the resulting image with those handles when checking Prim-tree reveal and highlight.

For spatial safety coverage, keep malformed authored transforms in the USD projection layer: that layer must reject them before ECS materialization. Test runtime-state admission at the lunco-usd-avian bridge owner, where a finite but f32-unrepresentable pose must raise a named RuntimeFaults record and PhysicsHolds::SAFETY_FAILURE before Avian runs. Test public Raycast and GroundHeight with a finite but unrepresentable query origin through an authored production scene; the expected result is {hit:false}, not a terminal simulation fault. This distinction keeps query-input validation from masking an engine-state failure and avoids duplicating guards in sensors, terrain, and vehicle callers.

For terminal runtime-fault recovery, verify the two owners separately and then the lifecycle seam. RuntimeFaults must pause Time<Physics> with a zero delta while leaving Time<Virtual> available for diagnostics and teardown. The bad scene is not repaired or resumed. SceneTeardown clears only the outgoing scene's terminal fault and PhysicsHolds::SAFETY_FAILURE; the physics owner also resets scene-owned holds, deliberate-step debt, and the physics clock before replacement admission. The focused regression names are terminal_runtime_fault_pauses_physics_until_cleared in lunco-physics and fault_then_scene_reload_can_admit_a_replacement_runtime in lunco-usd-sim.

The multi-process scene-test runner cannot prove same-process replacement: its expected terminal-fault process exits when the authored verdict is observed. Use a lifecycle test or a live API session that explicitly submits teardown, loads the replacement, and checks the new scene's admission/status. Do not add an automatic repair, retry, process restart, or fault-clearing fallback to make the invalid scene continue.

Scene, render, and editor acceptance runs are isolated by default and use a fresh production process. Their launchers keep settings in memory and disable runtime-overlay reads and writes regardless of Twin policy. The production scene runner fails before scenario start if a file-backed authored USD document is already dirty; runtime setup must not turn a clean fixture into unsaved authored work.

For a one-shot assertion that needs the currently loaded USD stage, use ./scripts/api/run_rhai_test.sh <port> <test.rhai> [probe-prim]. It prepends the test libraries and delegates to the native luncosim rhai --stdout client, which calls RunRhai on the existing production session. Editing and rerunning the test does not restart the app. Use ./scripts/api/run_scenario.sh when the assertion should remain attached as a persistent observer.

When a test depends on a Twin-scoped Rhai tool, register or reload that library in the same session first, confirm it with ListToolLibraries/GetToolLibrary, and make a minimal namespaced call before running the real observer. Discovery does not prove that the current Rhai engine has rebuilt its static module set. For a user-requested same-session workflow, use RunRhai or an attached RunScenario; do not substitute the multi-process scene-test runner.

For an interactive lesson, keep one production session and use RunScenarioAsset through /api/commands, then inspect the HUD and event stream. RunScenario is the live hot-reload path for a script attached to an existing host. Restart only when changing Rust or when a clean scene lifecycle is itself under test.

To exercise a discrete semantic action, address the target's api_id and send one SimulateIntentEdge command; do not model a pulse as two API requests:

{
  "type": "ExecuteCommand",
  "command": "SimulateIntentEdge",
  "params": {
    "target": 1234,
    "intent": "release",
    "edge": "pulse",
    "producer_id": 4123
  }
}

The response includes the canonical intent, edge, producer_id, correlation_id, and command id. Reuse the same nonzero producer_id for commands from one API producer. API submissions also include admission with the committed scene generation, effective simulation tick, and per-tick sequence. Confirm delivery through the intent.edge telemetry event (source, value.target_gid, and value.correlation_id identify the same target/action); its admission fields carry the same stamp. Use the returned correlation_id for the exact edge's trace, even when the scene emits later edges:

{
  "type": "ExecuteCommand",
  "command": "CausalTrace",
  "params": {"target": 1234, "correlation_id": 5678}
}

The response composes the authored binding, selected PortRegistry owner, USD connection/native-joint admission, current retained measurements, and the producer's admission stamp. An empty/pending stage is a real incomplete path. A target-scoped command still passes the normal ownership/authority gate; an acknowledgement alone does not prove that a consuming Twin policy acted on the edge.

For a held control, send one SimulateIntent command with held: true or false and a stable nonzero producer_id, reusing that ID for later commands from the same API producer. An external command targeting fixed-simulation state returns a correlation id and next-tick admission stamp; verify the matching intent.hold event has the same producer, target, held value, and stamp. The held state changes at that fixed tick. Local-embodiment commands remain on the interaction cadence.

Live runtime HTML/CSS iteration

The native luncosim UI watches the retained runtime surfaces under assets/ui/. Edit a surface's .html or .css in place and inspect the same window; HUI rebuilds the affected template and Flair reapplies the stylesheet without a binary rebuild or relaunch. Editing runtime_surfaces.json rebuilds the registered surface roots and action bindings. Rust exposure producers and action observers still require a rebuilt production binary.

Use ReadExposures to verify the data side independently of the pixels:

curl -s -X POST http://127.0.0.1:4101/api/commands \
  -H 'content-type: application/json' \
  -d '{"type":"ExecuteCommand","command":"ReadExposures","params":{"surface":"driven-vessel"}}' | jq .

The response's revision changes only when an exposed value or visibility flag changes. If it is stable, an unchanged runtime surface should not rebuild its view-model. Use CaptureScreenshot for the visual check. ReloadShader and RunScenario reload WGSL and Rhai respectively; neither reloads HTML/CSS.

Runtime UI is a small native HUI/Flair language, not a browser DOM. Do not expect JavaScript, forms, text inputs, full CSS, or host-font fallback. Read the runtime UI skill for the supported surface contract, placement/dock ownership, font rules, and performance gates.

Session lifecycle

Each agent doing runtime work owns a luncosim session on a distinct explicit free API port. Concurrent agent sessions are allowed on different ports. Launch from the same repository checkout and working directory as that agent's terminal, using that checkout's production binary. Before replacing your own session, send Exit and verify its process and port are gone; never control another agent's session or reuse an occupied port. Keep your current process for live shader/Rhai edits; restart only when a rebuilt binary or an explicit clean session is required.

Lifecycle (start → drive → stop)

# 1. Resolve the production binary in this checkout, choose a free API port
#    owned by this agent, and start it from this checkout's working directory.
#    Keep it alive in the runner's background session.
"$LUNCOSIM_BIN" --api 4101

# 2. Wait for the readiness contract, not just an open socket:
until curl -s http://127.0.0.1:4101/api/ready 2>/dev/null \
  | jq -e '.data.ready == true and .data.world_hold == false and .data.pending_count == 0' >/dev/null; do
  sleep 1
done

# 3. Send commands (see catalog below).

# 4. Stop with Exit, NEVER pkill / kill (user has to confirm those):
curl -s -X POST http://127.0.0.1:4101/api/commands \
  -H "Content-Type: application/json" \
  -d '{"type":"ExecuteCommand","command":"Exit","params":{}}'

After Exit, verify that the process and :4101 listener are gone before starting another session. A queued command or a reachable socket is not proof that a scene is ready; /api/ready is the gate for scene load, Modelica compile and participant initialization. For scene replacements that change ActivePhysicsFrame, also query each new dynamic body with QueryPhysicsState and require physics_pose_seeded == true before declaring admission complete; this catches a physics clock blocked before the replacement scene's first pose is written.

Curl shape

Every typed command uses the tagged envelope {"type":"ExecuteCommand","command":"<Name>","params":{...}}. Include params even for parameterless commands. Built-in discovery and entity listing use their own explicit type values.

curl -s -X POST http://127.0.0.1:4101/api/commands \
  -H "Content-Type: application/json" \
  -d '{"type":"ExecuteCommand","command":"OpenClass","params":{"qualified":"Modelica.Blocks.Continuous.PID"}}'

Successful fire-and-forget response: {"data":{"accepted":true}}. A result-returning typed command puts its command-specific payload in the same data envelope. Malformed envelopes are rejected at the transport boundary, and invalid typed parameters return HTTP 422. A deferred command may resolve its acknowledgement on the same request, but that is not necessarily completion of the domain work. RunExperiment returns its exact experiment_id once registered; the numerical solve remains asynchronous and is read through RunStatus and GetExperimentResult using that id. Rhai's in-process cmd may expose a pending command id; command_result(id) resolves that deferred command acknowledgement only. There is no generic HTTP command-id polling endpoint, and callers must not guess the run from its label or newest position.