Dev Scenario Docs Beta
Reference / Commands

Command reference

Every command a flow can use, generated from the same catalog the editor's autocomplete and validator use — so this list always matches what the app accepts.

A flow is a YAML file with one command per line. Text in quotes matches what's on screen; @name pulls a value from a profile or translation.

App Lifecycle 7

launchAppLaunch the app (single appId for both platforms)
launchApp: {appId}
appIdSingle id used for both platforms · string androidAppIdAndroid package id · string iOSAppIdiOS bundle id · string clearStateClear app state before launching · bool stopAppStop a running instance first · bool argumentsLaunch arguments string · string permissionsGrant/deny permissions before launching (avoids OS prompt) · selector
stopAppStop the app process
stopApp
killAppForce-kill the app process (alias for stopApp)
killApp
clearStateClear app data and state
clearState
installAppInstall an APK or IPA on the device
installApp: "app-debug.apk"
uninstallAppUninstall an app from the device by package id
uninstallApp: com.example.app

Tap & Gesture 9

tapOnTap an element by text, id, or accessibility label
tapOn: "Text"
countNumber of taps (defaults to 1) · int repeatAlias for count · int timeoutMax wait for the target to appear (ms) · durationms quickSkip post-tap window-stable + idle waits · bool pointTap a point as "x,y" or percentage "50%,75%" · string offsetXX offset from the element center (px) · int offsetYY offset from the element center (px) · int childOfConstrain match to descendants of another element · selector
longPressOnLong-press an element
longPressOn: "Text"
durationHow long to hold (ms) · durationms
doubleTapOnDouble-tap an element
doubleTapOn: "Text"
swipeSwipe in a direction (UP, DOWN, LEFT, RIGHT)
swipe:
    direction: UP
    duration: 300
directionSwipe direction · enum durationDuration in milliseconds · durationms fromStart element (alternative to a directional swipe) · selector toEnd element (alternative to a directional swipe) · selector startStart point as "x,y" or percentage "50%,75%" · string endEnd point as "x,y" or percentage · string
scrollScroll the current scrollable container
scroll
scrollUntilVisibleScroll until an element appears on screen
scrollUntilVisible:
    element: "My Text"
    direction: DOWN
elementAlias for text — element to scroll to · string fromSwipe anchor: gesture starts at this element's center (must be inside the scrollable region) · selector directionScroll direction · enum maxScrollsMaximum number of scroll attempts before giving up · int timeoutMax wait in milliseconds · durationms speedSwipe velocity (Android only) · enum, slow | fast durationPer-step swipe duration in ms; lower = faster but may overshoot the target. Default is a controlled scroll. Overrides speed. · durationms
pinchInZoom out / pinch in gesture on the screen
pinchIn
pinchOutZoom in / pinch out gesture on the screen
pinchOut
dragAndDropDrag one element onto another
dragAndDrop:
    from:
      id: "card_a"
    to:
      id: "drop_zone"
fromSource selector · selector, required toTarget selector · selector, required durationDrag duration in ms · durationms speedDrag speed (px per step) · int

Input 11

inputTextType text into a field (focuses the selector first when provided)
inputText: "Your text"
textText to type · string, required idField id to focus before typing · string labelVisible label or placeholder of the field to focus · string accessibilityAccessibility label of the field · string index0-based index when multiple fields match · int clearFirstErase the field before typing · bool hideKeyboardAfterDismiss the keyboard after typing · bool
eraseTextErase N characters from the focused field
eraseText: 5
inputRandomEmailType a random email address
inputRandomEmail
inputRandomNumberType a random number
inputRandomNumber
inputRandomTextType randomly generated text (configurable length)
inputRandomText:
    length: 12
lengthNumber of characters · int
inputRandomNameType a randomly generated person name
inputRandomName
copyTextFromCopy an element's text to the clipboard
copyTextFrom: "Text"
extractTextExtract an element's text into a reusable variable
extractText:
    id: otp
    into: OTP_CODE
intoVariable name to store the value in · string, required
clearTextFieldFocus and clear an input field reliably
clearTextField:
    id: "email_input"
pasteTextPaste clipboard contents into the focused field
pasteText
setClipboardSet the device clipboard to a specific text value
setClipboard: "Pasted text"

Assertions 11

assertVisibleCheck that the user can see something on screen (text or id)
assertVisible: "Text"
enabledAlso assert the element is enabled · bool checkedAlso assert the element is checked · bool
assertNotVisibleCheck that something is hidden (for example, error or loading)
assertNotVisible: "Text"
assertCheckedCheck that a checkbox or switch is checked
assertChecked:
    id: rememberMe
assertNotCheckedCheck that a checkbox or switch is not checked
assertNotChecked:
    id: rememberMe
assertEnabledAssert that an element is enabled (interactive)
assertEnabled:
    id: "submit_btn"
assertDisabledAssert that an element is disabled (non-interactive)
assertDisabled:
    id: "submit_btn"
assertContainsTextAssert that text appears somewhere in the accessible tree
assertContainsText: "Expected text"
assertTextEqualsAssert that an element's text equals an exact value
assertTextEquals:
    id: "price_label"
    expected: "$9.99"
expectedExpected text value · string, required
assertCountAssert how many elements match a selector
assertCount: { text: "Item", count: 3 }
textText matcher · string idId matcher · string countExpected count · int, required
assertFocusedAssert that a field or control currently has input focus
assertFocused:
    id: "search_field"
assertToastAssert transient toast text appears
assertToast: "Saved"

Wait 7

waitUntilVisibleWait until the screen is ready before checking or taking a screenshot
waitUntilVisible:
    element: "Text"
    timeout: 5000
elementAlias for text — element to wait for · string timeoutMax wait in ms · durationms
waitUntilNotVisibleWait until an element disappears from the screen
waitUntilNotVisible:
    element: "Loading"
    timeout: 10000
elementAlias for text — element to wait for · string timeout · durationms
waitForAnimationToEndWait for UI animations to settle before continuing
waitForAnimationToEnd:
    timeout: 5000
timeout · durationms
waitForPause execution for a fixed duration (ms)
waitFor: 2000
waitForTextWait until text appears anywhere on screen
waitForText: "Welcome"
waitForNetworkWait for a network request/response signal
waitForNetwork:
    urlContains: "/api/login"
    status: 200
urlContainsSubstring of the URL to match · string urlMatchesRegex matched against the full URL · string methodHTTP method to match · enum statusHTTP status code to wait for · int timeoutMax wait in milliseconds · durationms
waitUntilIdleWait until the device UI is idle (no pending animations or events)
waitUntilIdle:
    timeout: 10000
timeout · durationms

Navigation 5

backPress the device back button
back
hideKeyboardDismiss the software keyboard
hideKeyboard
pressKeyPress a hardware key (HOME, ENTER, BACK, etc.)
pressKey: ENTER
takeScreenshotCapture a visual proof image
takeScreenshot: screenshot_name
compareScreenshotCompare a current screenshot against a baseline
compareScreenshot:
    baseline: checkout.png
    threshold: 0.02
baselineBaseline screenshot filename · string, required thresholdTolerance (0.0–1.0) · number

Device 12

setSystemPropertySet JVM system properties inside the app via the in-app instrumentation SDK (silently no-ops in other driver modes)
setSystemProperty:
    isTestRun: true
    name: John
isTestRunExample flag — any key/value is accepted; every value is stored as a string · string
setLocationOverride the device GPS location
setLocation:
    latitude: 40.7128
    longitude: -74.0060
latitudeLatitude · number, required longitudeLongitude · number, required
setPermissionsGrant or deny app permissions
setPermissions:
    all: allow
allApply to every permission · enum permissionsPer-permission map · selector
permissionsGrant or deny app permissions (alias for setPermissions)
permissions:
    all: allow
allApply to every permission · enum permissionsPer-permission map · selector
toggleAirplaneModeToggle airplane mode on/off
toggleAirplaneMode
setDeviceOrientationChange device orientation (portrait, landscape)
setDeviceOrientation: landscape
setFontScaleChange device font scale for accessibility testing
setFontScale: 1.5
addMediaPush an image or video file to the device gallery
addMedia: "path/to/image.png"
clearNotificationsDismiss all notifications from the notification shade
clearNotifications
openNotificationsPull down the notification shade
openNotifications
startRecordingStart recording the device screen
startRecording: recording_name
stopRecordingStop an active screen recording
stopRecording

Device Actions 16

darkModeSwitch device to dark theme
darkMode
lightModeSwitch device to light theme
lightMode
setDarkModeSwitch device to dark theme
setDarkMode
setLightModeSwitch device to light theme
setLightMode
wifiOnEnable Wi-Fi on the device
wifiOn
wifiOffDisable Wi-Fi on the device
wifiOff
airplaneOnEnable airplane mode
airplaneOn
airplaneOffDisable airplane mode
airplaneOff
fingerprintSimulate fingerprint / biometric authentication
fingerprint
clearAppDataWipe app data and cache for a package
clearAppData: com.example.app
resetPermissionsRevoke all runtime permissions for an app
resetPermissions: com.example.app
disableAnimationsSet all animation scales to 0 (faster tests)
disableAnimations
enableAnimationsRestore default animation scales
enableAnimations
screenshotCapture a device screenshot via native device action
screenshot
recordScreenRecord device screen via native device action
recordScreen
gpsLocationSet mock GPS coordinates
gpsLocation:
    lat: 41.6938
    long: 44.8015
lat · number, required long · number, required

Flow Control 9

runScriptRun a JavaScript file
runScript: script.js
retryRetry a block of commands until it succeeds
retry:
    times: 3
    commands:
      tapOn: "Submit"
times · int, required commands · commands, required
forEachRun commands for each matching element
forEach:
    textRegex: "Item.*"
    commands:
      log: "${item.text}"
textRegexRegex matched against element text · string idRegexRegex matched against element id · string commands · commands, required
setLanguageResolve @prefix.key translations in another language for the rest of the run, including later units and scenarios. 
setLanguage: Spanish
appTranslation app name, id or prefix; omit for every app · string languageLanguage name or code (e.g. Spanish, es) · string, required
logEmit a custom JSONL debug event
log: "About to submit"
shellRun an ADB shell or simctl escape-hatch command
shell: "settings get system screen_brightness"
skipIfSkip the rest of the flow if a condition is met
skipIf:
    visible: "Already logged in"
visibleSkip if this text/id is visible · selector notVisibleSkip if this text/id is NOT visible · selector
runIfConditionally execute nested commands
runIf:
    visible: "Welcome"
    commands:
      tapOn: "Continue"
visibleRun if this text/id is visible · selector notVisibleRun if this text/id is NOT visible · selector platformRun only on a specific platform · enum, Android | iOS commandsCommands to execute when the condition is met · commands, required
ifConditionally run nested commands (C-style: `if (cond):`)
if (location == allowed):
    assertVisible: "Text"

Smart Commands 4

smartTapSemantic tap on a detected list or grid item
smartTap:
    target: listItem
    index: 0
targetDetected target name · string, required index0-based item index · int
smartAssertSemantic assert on a detected list or grid item
smartAssert:
    target: listItem
    index: 0
    hasText: "Expected text"
target · string, required index · int hasTextExpected text in the matched item · string
smartScrollSemantic scroll to detected list
smartScroll:
    target: list
    direction: down
target · string, required direction · enum
smartInputInListItemSemantic input in a detected list item
smartInputInListItem:
    index: 0
    text: "Input text"
index · int, required text · string, required