Skip to main content
Scenarios live in docs/roveflow/scenarios.md as YAML blocks under ## <id> headings. This page is the authoritative field reference. For usage context, see Authoring scenarios.

​
Field reference

FieldRequiredTypePurpose
idyesstringStable identifier. Matches the ## heading above the block. Must be unique across the inventory.
criticalityyesenumcritical or extended. No other values accepted.
ordernointForce scenario order. Used only by cold-setup with value 0.
goalyesstringOne-sentence outcome the user achieves.
entryyesenumcold-install, home, or a named state declared elsewhere.
waypointsyeslistMid-flight assertions the agent checks as it progresses.
steps_hintnostringFree-text hint for the agent. Keep short — one paragraph.
preferred_keysnolist<string>ValueKey strings to prefer over text taps. Optional.
passyesstringPlain-English pass condition.
failyesstringPlain-English explicit fail signals.

​
Validation rules

The orchestrator refuses to run a suite that violates any of these rules:
  • Exactly one scenario must have id: cold-setup, criticality: critical, order: 0, and entry: cold-install.
  • Every scenario other than cold-setup must have entry: home.
  • All scenario ids must be unique.
  • criticality must be exactly critical or extended.

​
Waypoint formats

Waypoints accept a handful of shapes. Mix as needed: 
waypoints:
  - reach_screen: "Nav App Home"   # exact AppBar title
  - reach_screen: home             # named state (string, unquoted)
  - tap_text: "Open Detail"        # action assertion
  - navigate_back                  # MCP action assertion
Keep waypoints to 3–6 per scenario. A scenario needing more is usually two scenarios.

​
Skip results

A agent may return result: skipped instead of pass or fail. Skip reasons are declared at the return-value level, not in the YAML — you don’t author them, but the schema below describes what you’ll see in reports.
Skip reasonCauseCascade
no_dataEnvironmental gap — no slots, no prior data.None; scenario-local.
setup_failedcold-setup did not reach home.Every remaining scenario.
setup_lostMid-run reset_to_home failed after the orchestrator’s fallback attempt.Every remaining scenario.
Skipped scenarios surface in the report but do not fail the run.

​
Full example

id: open-detail
criticality: extended
order: 1
goal: Navigate from home to the detail screen via the "Open Detail" button.
entry: home
waypoints:
  - tap_text: "Open Detail"
  - reach_screen: "Detail"
steps_hint: |
  From "Nav App Home", tap the "Open Detail" button. Verify the new
  screen's app bar reads "Detail" and the body text reads "You are on
  Detail".
preferred_keys:
  - open_detail_button
pass: detail app-bar title "Detail" visible AND detail body text visible
fail: navigation does not occur, or Detail screen does not render

​
Agent return value

Every agent returns this structure. The orchestrator aggregates these into the final report. 
{
  "id": "<scenario id>",
  "result": "pass" | "fail" | "skipped",
  "skip_reason": "no_data" | "setup_failed" | "setup_lost" | null,
  "waypoints_hit": ["<waypoint 1>", "<waypoint 2>"],
  "screenshots": ["<path 1>", "<path 2>"],
  "notes": "<free text — anything fragile, surprising, or worth flagging>",
  "ended_at_home": true | false
}
Every run writes screenshots, notes, and the structured result under docs/roveflow/runs/<run-id>/scenarios/<id>/.

​
Next

Authoring scenarios

Practical patterns for writing scenarios.

MCP tools

The interaction tools a agent calls.