Reference
Reference for Astra Scout commands, selectors, and workspace configuration.
Astra Scout runs Maestro flow YAML on iOS Simulators, real iPhones and Android devices, using the maestro-runner engine. This reference covers the commands, selectors and workspace configuration the runner supports. The YAML syntax is identical to Maestro, so existing flows work unchanged, provided they stay within what is listed here.
Explore the reference
| Section | What you will find |
|---|---|
| Commands | Every flow command that Astra Scout supports, with parameters and examples. |
| Selectors | How to target UI elements by text, ID, position, state and size. |
| Workspace configuration | The config.yaml keys that choose and order the flows of a run. |
To learn how to write and organize flows, start from the flows guides.
Commands
Support levels:
- Supported: works on both Android and iOS as documented.
- Partial: works with limits, for example on one platform only or on iOS Simulators only. The page starts with a caveat box that lists them.
"Simulator only" means the command works on iOS Simulators and fails on a real iPhone.
| Command | Description | Android | iOS | Support |
|---|---|---|---|---|
acceptAlert | Accept a system alert dialog on iOS. | No | Yes | Partial |
addMedia | Add images or videos to the device gallery for media picker testing. | Yes | Simulator only | Partial |
assertCondition | Assert that a visibility or script condition holds. | Yes | Yes | Supported |
assertDarkMode | Assert that the device is currently in dark mode. | Yes | Simulator only | Partial |
assertEvents | Assert that the app sent analytics events (Astra Scout only). | Yes | Yes | Supported |
assertLightMode | Assert that the device is currently in light mode. | Yes | Simulator only | Partial |
assertNotVisible | Assert that a UI element is not present or visible on the screen. | Yes | Yes | Supported |
assertNoDefectsWithAI | AI check that the screen has no visual defects. Needs an AI CLI configured in Settings. | Yes | Yes | Supported |
assertScreenshot | Perform visual regression testing of your application against existing screenshots. | Yes | Yes | Supported |
assertTrue | Assert that a JavaScript expression evaluates to true. | Yes | Yes | Supported |
assertWithAI | Assert a natural language statement about the screen with AI. Needs an AI CLI configured in Settings. | Yes | Yes | Supported |
assertVisible | Assert that a UI element is visible on screen with automatic retry. | Yes | Yes | Supported |
back | Press the system back button to navigate to the previous screen. | Yes | No | Partial |
clearKeychain | Clear iOS keychain data for the app under test. | No | Simulator only | Partial |
clearState | Clear app data, cache, and preferences to reset to fresh install state. | Yes | Yes | Supported |
copyTextFrom | Copy text content from a UI element to clipboard or variable. | Yes | Yes | Supported |
defineVariables | Define flow variables from key-value pairs. | Yes | Yes | Supported |
dismissAlert | Dismiss a system alert dialog on iOS. | No | Yes | Partial |
doubleTapOn | Perform a double-tap gesture on a UI element or screen coordinates. | Yes | Yes | Supported |
dragAndDrop | Press an element or point and drag it to another element or point. | Yes (Android 12+) | Yes | Partial |
eraseText | Delete text from input fields by character count or clear entirely. | Yes | Yes | Supported |
evalScript | Evaluate inline JavaScript expressions within the flow context. | Yes | Yes | Supported |
evalWebViewScript | Run JavaScript in the WebView on screen. | Yes | No | Partial |
extendedWaitUntil | Wait for an element with a custom timeout longer than the default. | Yes | Yes | Supported |
extractTextWithAI | Read text from the screen with AI into a variable. Needs an AI CLI configured in Settings. | Yes | Yes | Supported |
hideKeyboard | Dismiss the on-screen keyboard if currently visible. | Yes | Yes | Supported |
inputRandom | Type random data of a chosen type into the focused field. | Yes | Yes | Supported |
inputRandomEmail | Type a random e-mail address. | Yes | Yes | Supported |
inputRandomNumber | Type a random string of digits. | Yes | Yes | Supported |
inputRandomPersonName | Type a random person name. | Yes | Yes | Supported |
inputRandomText | Type a random string of letters and digits. | Yes | Yes | Supported |
inputText | Type text into focused input fields with optional keyboard handling. | Yes | Yes | Supported |
killApp | Force stop an app and optionally clear all its data and cache. | Yes | Yes | Supported |
launchApp | Launch an app with optional permission configuration and clear state. | Yes | Yes | Supported |
longPressOn | Long press on elements for context menus or drag-and-drop operations. | Yes | Yes | Supported |
openBrowser | Open a URL in the device's browser. | Yes | Yes | Supported |
openLink | Open a URL or deep link in the app or system browser. | Yes | Yes | Supported |
openNotifications | Pull down the notification shade on Android. | Yes | No | Partial |
pasteText | Paste text from clipboard into the currently focused input field. | Yes | After copyTextFrom only | Partial |
pressKey | Press hardware keys like home, back, enter, or volume buttons. | Yes | Limited keys | Partial |
removeMedia | Clear the media index on Android, undoing addMedia. | Yes | No | Partial |
repeat | Repeat a block of commands a specified number of times. | Yes | Yes | Supported |
retry | Retry a block of commands on failure with configurable attempts. | Yes | Yes | Supported |
runFlow | Execute a subflow file with optional environment variables. | Yes | Yes | Supported |
runScript | Run an external JavaScript file and capture its output. | Yes | Yes | Supported |
runShell | Run a shell command on the Mac and optionally keep its output. | Yes | Yes | Supported |
runWebViewScript | Run a JavaScript file in the WebView on screen. | Yes | No | Partial |
scroll | A simple vertical scroll to move down the screen to see the content below. | Yes | Yes | Supported |
scrollUntilVisible | Automatically scroll until a target element becomes visible on screen. | Yes | Yes | Supported |
setAirplaneMode | Enable airplane mode to test offline behavior. | Yes | No effect on Simulator | Partial |
setClipboard | Set the device clipboard content to a specified text value. | Yes | No | Partial |
setDarkMode | Enable or disable dark mode to test light/dark UI behavior. | Yes | Simulator only | Partial |
setLocation | Set device GPS location to specific coordinates for location testing. | Yes | Simulator only | Partial |
setOrientation | Change device orientation between portrait and landscape modes. | Yes | Yes | Supported |
setPermissions | Grant or deny app permissions during flow execution. | Yes | Partial on real iPhone | Partial |
startRecording | Start recording the screen for video documentation of test runs. | Yes | No | Partial |
stopApp | Stop a running app without clearing its data or state. | Yes | Yes | Supported |
stopRecording | Stop the current screen recording and save the video file. | Yes | No | Partial |
swipe | Swipe gestures in any direction with customizable speed and distance. | Yes | Yes | Supported |
takeScreenshot | Capture a screenshot and save it to the test output directory. | Yes | Yes | Supported |
tapOn | Tap on UI elements by text, ID, or coordinates with optional repeat and delay. | Yes | Yes | Supported |
tapOnPoint | Tap or press at a screen coordinate. | Yes | Yes | Supported |
toggleAirplaneMode | Toggle airplane mode on or off during test execution. | Yes | No effect on Simulator | Partial |
toggleDarkMode | Toggle dark mode on or off during test execution. | Yes | Simulator only | Partial |
travel | Simulate time travel by adjusting the device system clock. | Yes | No | Partial |
wait | Pause the flow for a fixed time. | Yes | Yes | Supported |
waitForAnimationToEnd | Wait for UI animations to complete before proceeding. | Yes | Yes | Supported |
Not supported in Astra Scout
All Maestro commands that have a page in this reference are supported. The three AI commands (assertWithAI, assertNoDefectsWithAI and extractTextWithAI) run through the AI CLI you configure in Settings → AI, see the AI assistant.
Maestro features that belong to Maestro Cloud or Maestro Studio (cloud uploads, notifications, hosted devices) are also out of scope, because Astra Scout runs fully locally without login.