Skip to main content
Scenarios live in docs/roveflow/scenarios.md. Each one is a YAML block under a ## <id> heading. You author the flow, a handful of waypoints, and plain-English pass/fail conditions. The agent figures out the taps.

​
The minimum: cold-setup

Every project has exactly one cold-setup scenario. It runs first, always, and establishes a known home state the rest of the suite can assume. The orchestrator refuses to run if it’s missing or misconfigured. 
id: cold-setup
criticality: critical
order: 0
goal: Reach the Nav App home screen from cold install.
entry: cold-install
waypoints:
  - reach_screen: "Nav App Home"
steps_hint: |
  The app opens directly to the home screen. No login. Verify the app
  bar reads "Nav App Home" and the "Open Detail" button is visible.
pass: "Open Detail" button visible AND welcome text visible
fail: screen blank, app crashes within 10s, or app bar title missing
Rules the orchestrator enforces:
  • id: cold-setup, criticality: critical, order: 0, entry: cold-install.
  • Every other scenario has entry: home (the warm-chain assumption).
  • Scenario ids are unique.
  • criticality is critical or extended — no other values.

​
Additional scenarios

After cold-setup, add one block per user flow. Each starts from the home screen and ends back at home (the agent runs reset-to-home automatically). 
id: open-detail
criticality: extended
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

​
Criticality tiers

  • critical — runs in --mode=critical (the default) and --mode=all. Reserve for flows a release cannot ship without.
  • extended — runs only in --mode=all. Broader coverage for scheduled nightly runs.

​
Skip results (no exceptions)

An agent may return result: skipped instead of pass or fail when the environment blocks the flow. Skipped scenarios surface in the report but do not fail the run.
Skip reasonWhat it means
skipped: no_dataEnvironmental gap. No slots today, no prior data. Declared by the agent based on the scenario’s fail conditions.
skipped: setup_failedcold-setup never reached home. Cascades to every remaining scenario.
skipped: setup_lostMid-run reset_to_home failed. Cascades to remaining scenarios.
Write fail: as the explicit failure signal, and let ambiguous environmental states resolve to skipped: no_data. “No slots available” is a skip, not a failure.

​
Waypoint format

Waypoints are mid-flight assertions the agent checks as it progresses: 
waypoints:
  - reach_screen: "Nav App Home"      # exact AppBar title match
  - reach_screen: home                # named state
  - tap_text: "Open Detail"           # action assertion
  - navigate_back                     # MCP action assertion
Keep waypoints to 3–6 per scenario. More than that suggests the flow should be split.

​
steps_hint — when to use it

Short hints help the agent when text alone is ambiguous: 
steps_hint: |
  From the home screen, tap the floating action button (the "+" icon in the
  bottom-right). Verify the counter text updates from "0" to "1".
Don’t write full scripts. The point of Roveflow is that the agent finds the path; hints nudge it when screens have multiple similar-looking targets.

​
preferred_keys — optional stability

List ValueKey strings the agent should try first when the scenario is fragile. Optional — the default install uses visible text and the semantics tree. See Using ValueKeys for when to reach for them.

​
Full field reference

FieldRequiredPurpose
idyesStable identifier; matches the ## heading
criticalityyescritical or extended
ordernoForce order (cold-setup uses 0)
goalyesOne-sentence outcome the user achieves
entryyescold-install, home, or a named state
waypointsyesMid-flight assertions
steps_hintnoFree-text hint
preferred_keysnoValueKeys to prefer over text
passyesPlain-English pass condition
failyesPlain-English explicit fail signals
Schema reference: Scenario schema.

​
Next

Running smoke tests

Execute the scenarios with /roveflow.

Scenario schema

Every field, with validation rules and skip result semantics.