Inspect And Scenarios

Luotsi gives you two different automation surfaces on purpose.

Inspect: for exploration

inspect is a long-lived JSONL session for agent-driven exploration.

luotsi inspect --device <serial>

Use it when you are still learning the screen flow, want structured snapshots and deltas, or need an agent to reason about the UI incrementally.

Typical emitted events include:

session_started
screen_snapshot
screen_delta
command_result
session_ended

Scenarios: for repeatability

Scenario files are plain JSON playbooks with optional setup, required steps, and optional teardown phases.

luotsi scenario-list --path scenarios
luotsi scenario-init --file scenarios/smoke.json --name "smoke"
luotsi scenario-validate --path scenarios
luotsi scenario-explain --file scenarios/smoke.json
luotsi run --path scenarios --output-dir ./artifacts/smoke-run --dry-run --include-tag smoke
luotsi run --file scenarios/smoke.json --device <serial>

Use them when you want a checked-in flow with validation, timing, artifacts, and CI-friendly reports.

Discovery: for unknown app surfaces

discover is the bounded autonomous layer between open-ended inspection and repeatable scenarios.

luotsi discover --device <serial> --package <app.id> --budget 5m

It writes a discovery map, JSONL event trace, and review-required scenario candidate into the artifact root. Discovery follows changed screens up to --max-depth, records the backtracks needed to return through the explored branch, and supports --allow-text, --deny-text, --deny-resource-id, and --deny-class guardrails for excluding unsafe or irrelevant tap targets before ranking. Treat the generated scenario as a starting point: validate and edit it before using it as CI coverage.

What scenario files support

Root variables and lightweight template substitution
App, device, and layout metadata for calibrated runs
Direct interaction steps, structured selector steps (waitElement/tapElement), waits, assertions, app lifecycle, and artifact capture, including screenshot-first fallback steps for weaker hierarchy output
Failure bundles and replay metadata when something breaks
continueOnError: true on runtime-failure steps when the flow should continue after a bounded failure

Runner modes that matter

scenario-list and run --path share discovery filters such as --include-tag, --exclude-tag, --name, and --action.
run --path --dry-run returns the selected plan after filtering and sharding without validating or touching a device host.
--validate-only validates the selected files and still writes reports, but does not create a device host or execute device work.
--dry-run and --validate-only are intentionally mutually exclusive.
Use --artifacts <directory> or --output-dir <directory> when you want a stable run-artifact root instead of Luotsi’s default user-local run home.
--events-jsonl, --report-json, and --report-junit are the main machine-readable outputs for CI and artifact review.
--claim-device, --owner, and --ttl-sec let a run hold a lab lease while it executes.

A practical split

Use inspect first when the flow is still changing and needs step-by-step agent control. Use discover when the app surface is broad or unknown and you want a state map plus candidate scenarios. Once you know the sequence and the assertions you care about, move that behavior into a scenario JSON file and run it under luotsi run.

Where replay fits

Scenario runs and long-lived sessions write artifact roots on purpose. Once a flow has been codified, use luotsi artifacts list to rediscover recent runs, then start replay-specific triage with replay packet so the run has a durable run-summary.json and run-summary.md before moving into replay open, replay summarize, or replay timeline. Use artifacts open only when you specifically need the generic browser.