Run flows

Open a workspace, write a flow, run it on a device, and read the result.

This page covers the daily loop: open a workspace, write a flow, run it on a device and read the result.

Workspaces

A workspace is a folder that contains your Maestro flows (.yaml files) and anything else you want next to them. Use the File menu, or the Welcome to Astra Scout window when no workspace is open:

Command	What it does
New Workspace… (Cmd+N)	Chooses or creates a folder for your tests and gives it the workspace layout below.
Open Workspace… (Cmd+O)	Opens a folder that already has flows.
Close Workspace	Closes the current workspace.
Open Recent	Reopens a workspace you used before.

If a workspace folder no longer exists, the app tells you to reopen the project folder.

A new workspace starts with this layout. Open Workspace… leaves a folder as it is.

<workspace>/
├── *.yaml            your flows
├── subflows/         flows that other flows call with runFlow
├── tracking-specs/   tracking specs, with a README (see Tracking)
└── artifacts/runs/   one folder per run: its videos and screenshots, not committed

The Files navigator

The Files navigator shows your files and folders. The Add (+) button and the filter field at its bottom create items and narrow the list. Right-click an item for these actions:

• New File… (Shift+Cmd+N), with templates Mobile Test, Javascript File and Text File. A mobile test asks for a name, an App ID (pick from Recently Used or, when a device is connected, On Connected Device) and optional Tags. When the project has an app picked in the toolbar app picker, the App ID starts as ${APP_ID}: a flow with appId: ${APP_ID} runs on the picked app (the server sets APP_ID for each run; an APP_ID you pass yourself wins). A flow with a literal appId is unchanged.
• New Folder…
• Run Test
• Duplicate, Rename and Delete (items go to the Trash)
• Show in Finder

You can drag files and folders to move them, and select several items at once.

The editor

The editor shows one file at a time. Use Go Back and Go Forward in the toolbar (Ctrl+Cmd+← and Ctrl+Cmd+→) to move between files you opened. The editor suggests Maestro commands as you type and underlines commands the connected device cannot run.

• Files auto-save after a short delay. You can turn this off with File → Autosave or in Settings → General. Cmd+S saves immediately and Cmd+W closes the file.
• While a flow runs, each command line shows its state: pending, running, completed or failed.
• Click a line number in the gutter for Run “command” or Run from Here. These run on the connected device without leaving the editor.

Need a command quickly?

Turn on Device → Inspect Elements, right-click an element on the device screen and use Insert into Editor. See Inspector.

Run a flow

1. Connect a device. See Devices.
2. Open the flow file.
3. Click Run Test in the toolbar (Cmd+R). Use Stop (Cmd+.) to cancel.

Before a run starts, Astra Scout checks the driver (and, on iPhone, whether the screen is locked). Purchase-like steps run like any other step. See Purchase testing.

Run all flows in a workspace

Choose Run → Run All Tests (Shift+Cmd+R) to run every flow in the workspace, and Stop All Tests to stop. Videos from a workspace run share one folder, with _2, _3 added to duplicate names.

Choose an environment

The Environment menu at the right of the runner bar applies named variables and tags to the run. See Environments and variables.

Read the results

The Test Runs navigator lists runs for this session. Pick one to see the status of each flow and command in the runner: one row per flow (result and time under its name, duration at the right), then one row per step. A failed step shows why right under it. Right-click a row, or select it and use the buttons in the detail pane, for these actions:

Action	Purpose
Open File	Jump to the flow file
Copy Logs	Copy the full log of a failed step
Show Recording	Play the video of the run over the device mirror
Fix with AI and Auto-Fix…	Hand a failed flow to the AI. See AI assistant.
Report Bug to Jira…	See Jira

Clear History… at the bottom of the navigator removes the local run history for the workspace.

Verdicts

Besides pass or fail per step, each run has a verdict label that Astra Scout computes from structured facts. The AI never writes it.

Label	Meaning	CLI exit code
Passed	Every step passed.	0
Failed	A real app or flow failure: wrong selector, failed assertion, app crash.	1
Incomplete	Stopped before a conclusion: you pressed Stop, a limit was reached, the AI timed out.	2
Unsure	An AI check was not conclusive, so a person must review it.	2
Blocked	Device or environment problem: lost connection, driver not responding, app not installed, signing error, no AI.	3

Click a label to see the reason, the deciding step and the report. The report is stored with the run as Markdown and JSON.

Reason codes

A Blocked run always has a reason code. An Incomplete run has one when the cause is known. A run with a reason code is never treated as an app bug, so no bug report is suggested.

Code	Meaning
ENVIRONMENT_UNAVAILABLE	Device or driver not ready (lost connection, WDA or DeviceLab not responding)
APP_NOT_INSTALLED	The app is not installed
APP_FILE_REQUIRED	clearState on a real iPhone needs an .ipa or .app build. See Devices.
AUTOMATION_UNSUPPORTED	The command is not supported on this platform
AI_PROVIDER_UNAVAILABLE	AI not installed, not signed in, errored or timed out
AI_BUDGET_EXHAUSTED	Out of AI calls (exploration)
STEP_BUDGET_EXHAUSTED	Step, round or time limit reached
POLICY_DENIED	The tester declined
NEEDS_HUMAN	The tester must act on the device (system purchase or password dialog)
SYSTEM_OVERLAY	An iOS system dialog or sheet covers the app. Steps that match text or ids on that dialog act on it directly.
DEVICE_LOCKED	The iPhone screen is locked and has a passcode
UNKNOWN	Blocked, but no fact states the cause

Videos

Flow videos are saved in the open workspace:

<workspace>/artifacts/runs/<run start date_time>/<flow file name>.mp4

A takeScreenshot with a relative path, such as - takeScreenshot: home, saves home.png in <run start date_time>/<flow file name>/, beside the video, rather than next to the flow file, so each run keeps its own screenshots. An absolute path is kept as written. Commands run outside a flow file in a workspace save their screenshots in a run folder of their own.

Astra Scout creates artifacts/runs/.gitignore containing * so videos are not committed. It does not edit your own .gitignore. Videos from commands run outside a flow file and from exploration live in the app's data folder under tests/<session>/videos/.

Run history plays videos from those paths. If you delete a file, the video disappears from history.

Commands that cannot run

Commands the connected platform does not support are marked in the editor and rejected by the AI and MCP tools. See Supported platforms.

Next steps

• Writing flows and the commands reference
• Troubleshooting