Dev Scenario Docs
Reference / Commands

Command reference

Every command, option and selector a flow can use, with when to use it, what it does in the app and examples. The list comes from the same catalog the editor's autocomplete and validator use, and every example here is checked by the flow parser.

A flow is a plain .ds text file with one command per line: command(argument, option = value). Text in quotes matches what's on screen; @name pulls a value from a profile or translation. Durations are written 500ms or 10s.

launchApp("com.shop.app", clearState = true)
tap("Sign in").type(@username)
tap("Delete").siblingOf("Invoice 42")
assertVisible("Paid").below("Invoice 42")
All 129 entries, A to Z
.aboveaddContactaddMediaairplaneMode.androidanimationsanyappActionargs.argumentsassertCheckedassertCountassertDisabledassertEnabledassertFocusedassertNotCheckedassertNotVisibleassertTextassertThatassertVisibleback.below.childOfclassNameclearNotificationsclearState.clearStateclearText.clickableComments and line breakscontains.containsChildcopyTextdarkModedateday, month, yeardeleteContactsdismissInterruptingDialogsdoubleTapdragelse and else if.enabled.environmenteraseEvery command.excludingfilefingerprint.flagsFoldersforEachhideKeyboardidif.indexinstallApp.iOS.keepFileslabellaunchApp.leftOfloglongPressmeta$name and ${name}${NAME} run valuesnotVisiblenumberOfonCompleteonErroropenLinkopenNotificationspastepermission.permissionspinchInpinchOutplatformpoint@prefix.key translationspressKey@profile and profilespushFilerandomEmailrandomNamerandomNumberrandomTextreadregexresetPermissionsretry.rightOfscreenshotscrollscrollTosetClipboardsetFontScalesetLanguagesetLocationsetOrientationsetPermissionssetSystemPropertyshell.siblingOfskipIfstartRecordingstopAppstopRecordingswipetaptestTagtextText and escapestextOftype.type after tapuninstallAppusevalValues and units.visiblevisiblewaitwaitForwaitForAnimationswaitForIdlewaitForValuewaitUntilGonewifi

Flow Syntax 7

How a flow file is written. A flow runs top to bottom and stops at the first step that fails.

Every commandOptions any command takes

When to use Use optional for something that may or may not be there, such as a promo banner. Use retryOnFail for a step that sometimes fails for reasons outside the test.

In the app An optional step that fails shows as a warning, not a pass, and the flow goes on. retryOnFail runs the step again after a short pause; only the last failure counts.

Close a banner only if it shows up
tap("Not now", optional = true)

If "Not now" never appears, the step waits its full timeout and the flow continues. If an element is often missing, if (visible("Not now")) is faster because it doesn't wait.

Try a step up to three times
tap("Refresh", retryOnFail = 2)

One normal attempt, then up to two more when it fails.

optionalA failure is reported as a warning and the flow continues · true or false, default false retryOnFailRun the command again up to this many times when it fails · whole number
Values and unitsText, numbers, durations, percents, true and false, lists
Every kind of value
tap("Sign in", timeout = 10s)
wait(500ms)
tap(point(50%, 75%))
setFontScale(1.3)
launchApp(
    "com.shop.app",
    clearState = true, keepFiles = ["shared_prefs/keys.xml"],
)

Durations are 500ms, 10s or 2m, never a bare number of milliseconds. Words such as up, ios or landscape take no quotes.

Text and escapesQuotes, escapes and raw strings
Escape what would otherwise be read as code
assertVisible("She said \"hi\"")
assertVisible("Price: \$5")
assertVisible("Follow \@devscenario")
assertVisible(regex("""^Order #\d+$"""))

\", \\, \n, \t, \$ and \@ are the escapes. Triple quotes keep backslashes as written, which suits regular expressions.

Comments and line breaksComments, ; and calls over several lines
Comments, two steps on a line, a long call wrapped
// Log in as the demo user
tap("Email"); type("[email protected]")

type(
    "secret",
    into = "Password",
    hideKeyboard = true,
)
tap("Delete")
    .below("Invoice 42")

A line starting with . continues the step above it. Indentation has no meaning.

@profile and profilesTest data from a profile: @key and @profile.<name>.key

When to use Use them for anything that changes between environments or shouldn't be in the flow file: users, passwords, URLs.

In the app The value is filled in before the step runs. Values, secrets kept on your machine and values fetched over HTTP are all written the same way.

Read test data from the active profile, or a named one
type(@username, into = "Email")
type(@profile.staging.password, into = "Password")

@username reads the active profile, or the one set by use(…) above it. An email such as [email protected] stays plain text: an @ right after a letter or digit is not a reference.

@prefix.key translationsOne flow for every language of the app

Use it when the same test runs on an app in several languages.

In the app The text comes from the project's translations, in the language the app is using on that device.

Tap a button whatever the app's language is
tap(@langs.sign_in)
assertVisible(@langs.welcome_back)

langs is the prefix set on the app in Translations. See setLanguage to switch language in the middle of a run.

${NAME} run valuesValues given to the run from outside: --env and the mock server's address

Use it for values that come from outside the project, such as a CI build number. For values you keep in the project, use @key from a profile.

In the app Filled in inside strings only, always braced, always as text. A name the run wasn't given stays unfilled, unless the flow set a variable with that name.

A value you pass to the CLI
log("Testing build ${BUILD_NUMBER}")

BUILD_NUMBER is only an example name. It has a value because the run was started with --env BUILD_NUMBER=412.

The address of the embedded mock server
launchApp(
    "com.shop.app",
    arguments = args(mockBaseUrl = "${DEVTOOL_MOCK_BASE_URL}"),
)

The CLI sets DEVTOOL_MOCK_BASE_URL when a run serves mocks (a scenario selects a mock group, or --with-mocks), because the server's address is only known once it starts. It isn't a profile key, so @DEVTOOL_MOCK_BASE_URL doesn't read it.

A mock address you control, from a profile
launchApp("com.shop.app", arguments = args(mockBaseUrl = @mockUrl))

mockUrl is a key you add to a profile. It works the same in the app and in CI.

Selectors 9

How to say which element a step acts on. A plain string is the element's exact text. Selectors work the same on Android and iOS.

text("Login")Element with exactly this text (a plain string means the same)

Use it when the label on screen is stable and unique. It is what a plain string means, so tap("Login") is the usual way to write it.

Two ways to write the same thing
tap("Login")
tap(text("Login"))

Matches the whole text. "Login now" is not matched.

contains("Log")Element whose text contains this

Use it when part of the text changes, such as a name or a count.

Match part of a label
assertVisible(contains("items in your cart"))
waitFor(contains("Welcome"))
regex("^Order #\\d+$")Element whose text matches the regular expression

Use it when the text follows a pattern: order numbers, prices, dates.

Match a pattern
tap(regex("""^Order #\d+$"""))

Raw strings save escaping every backslash.

id("login_btn")Resource id (Android) or accessibility identifier (iOS)

When to use The most stable choice when your app has ids, because copy and translations can change without breaking the test.

Find by id
tap(id("login_btn"))

Android resource id, iOS accessibility identifier.

testTag("login")Compose test tag

Use it for Compose screens that set Modifier.testTag(…).

Find by Compose test tag
tap(testTag("checkout_button"))
label("Email")Accessibility label, or a text field's label, placeholder or hint

Use it for icon buttons with no visible text, or for text fields by their placeholder.

Find by accessibility label or field hint
tap(label("Close"))
tap(label("Email")).type("[email protected]")

When to use A last resort when nothing else identifies the element. Class names are fragile and differ between platforms.

Find by class, narrowed with a modifier
tap(className("android.widget.Switch")).below("Notifications")
any()Any element: only the modifiers after it narrow it

Use it when only position or state identifies the element, such as an unlabeled button under a heading.

Match anything, then narrow it
tap(any()).clickable().below("Card details")

any() on its own has nothing to look for and fails the parse.

point(540, 1200)A screen point, in pixels or percent (taps and gestures only)

Use it for things with no element behind them, such as a map or a canvas. Prefer an element whenever there is one, because points break across screen sizes.

Tap a screen position, in pixels or percent
tap(point(540, 1200))
tap(point(50%, 75%))

Works with taps and gestures only. Assertions and waits need an element.

Selector Modifiers 13

Chain these after a selector when one isn't enough. They combine, and every one must hold. A selector given as an option or an anchor keeps its modifiers inside the parentheses: drag("Card A", to = text("Done").below("Board")).

.index(0)0-based, when several match

Use it when several elements match and you want one by position. Prefer a relative modifier if the position has a meaning.

Pick the second match
tap(id("row")).index(1)

Counts from 0. With .below and the other spatial modifiers, matches are ordered nearest first, so .index(0) is the nearest.

.below(element)Nearest element below this one

Use it when the same label appears several times and a heading above it tells them apart.

The Edit button under a heading
tap("Edit").below("Shipping address")

The element must be entirely below the anchor. The nearest match wins.

.above(element)Nearest element above this one

Use it when the element you want sits over something easy to identify.

The total above the Pay button
assertVisible(regex("Total: .*")).above("Pay")
.leftOf(element)Nearest element left of this one

Use it for controls in a row, such as an icon before a label.

The checkbox to the left of a label
tap(any()).clickable().leftOf("I accept the terms")
.rightOf(element)Nearest element right of this one

Use it for values and controls that follow a label in a row.

The switch to the right of a label
tap(className("android.widget.Switch")).rightOf("Dark theme")
.childOf(element)Inside this element

Use it to look inside one part of the screen: a dialog, a list row, a card.

Only inside the cart
tap("Remove").childOf(testTag("cart"))
tap("Delete").childOf(any().containsChild("Invoice 42"))

The element can be at any depth inside the ancestor. The second line taps Delete inside the row that holds "Invoice 42".

.containsChild(element)Has this element inside it

Use it to pick a container by what it holds, such as the row with a certain name in it.

The row whose direct child says "Invoice 42"
tap(any()).containsChild("Invoice 42")

Direct children only. To go deeper, nest it inside .childOf, as in the childOf example.

.siblingOf(element)Shares a parent with this element

Use it for a control next to a label in the same row, without measuring position.

The Delete button beside an invoice
tap("Delete").siblingOf("Invoice 42")

The two elements share a parent. The anchor itself never matches.

.enabled()Only enabled elements (enabled(false): only disabled ones)

Use it to skip a disabled copy of a button, or to assert that one is disabled.

Only the enabled Save button
tap("Save").enabled()
assertVisible("Save").enabled(false)
.clickable()Only clickable elements

Use it when a label and its button both match and you want the part that takes taps.

Only what can be tapped
tap(contains("Settings")).clickable()
.visible()Only elements on screen

Use it when an off-screen or hidden copy of an element also matches.

Only what is on screen
assertCount(id("row").visible(), 5)
.excluding("ClassA")Ignore elements under subtrees of these classes

Use it when a large container, such as a web view, holds text you don't want to match.

Ignore everything inside these classes
tap("Continue").excluding("android.webkit.WebView")

Takes one or more class names. Elements under them are ignored.

.type after tapTap a field and type into it on one line

Use it for the tap-then-type pair that fills most forms.

Same as tap("Password") followed by type(@password)
tap("Password").type(@password, hideKeyboard = true)
tap(id("email"))
    .below("Sign in")
    .type("[email protected]", clearFirst = true)

Modifiers before .type refine the tapped element. It runs as two steps. Only tap can be followed by .type, and into is left out.

App Lifecycle 6

stopAppStop the app process

Use it to test what happens when the app is killed: a resume after a crash, or data saved before exit. Follow it with launchApp.

Kill the app, then start it again
tap("Save draft")
stopApp
launchApp("com.shop.app")
assertVisible("Draft saved")
Stop another app
stopApp("com.android.chrome")
argumentApp id (default: the flow's appId)
clearStateClear app data and state

Use it to wipe data without starting the app, or to wipe another app the test touches. To wipe and start, use launchApp(clearState = true).

In the app Stops the app and deletes its data, as if newly installed.

Wipe the app, or another one
clearState
clearState("com.example.companion")
argumentApp id (default: the flow's appId)

Limits On iOS, Keychain items stay. On a physical iPhone, the app being cleared needs the native iOS in-app SDK. Without it the step warns and the flow goes on.

installAppInstall an APK or IPA on the device

Use it to test a fresh install or an upgrade from an older build.

Upgrade from the previous build
installApp("builds/app-1.2.apk")
launchApp("com.shop.app")
tap("Create demo data")
installApp("builds/app-1.3.apk")
launchApp("com.shop.app")
assertVisible("Demo data")
argumentPath of the APK or IPA
uninstallAppUninstall an app from the device

Use it to start from nothing, such as a first-launch test on a physical iPhone where clearState isn't available.

Remove the app, install it again
uninstallApp("com.example.app")
installApp("builds/app.ipa")
argumentApp id (default: the flow's appId)
launchAppLaunch the app

When to use First step of nearly every flow. Also use it to restart the app partway through, to check that data survives a restart.

In the app Stops the app if it is running, applies the settings below, starts it and leaves it on its first screen.

Start an app
launchApp("com.shop.app")

The id is the Android package or iOS bundle id. Left out, as in launchApp(), the step uses the first app id the flow names, then the app set for the run. With neither, it fails.

Start clean, with the camera allowed and a demo mode on
launchApp(
    "com.shop.app",
    clearState = true,
    permissions = args(camera = true),
    arguments = args(mode = "demo"),
)

Setting permissions here means the system dialog never appears over the first screen.

Every setting, chained one per line
launchApp("com.shop.app")
    .android("com.shop.app.debug")
    .iOS("com.shop.ios")
    .clearState()
    .keepFiles("shared_prefs/keys.xml", "databases/seed.db")
    .permissions(notifications = true, location = false)
    .arguments(mode = "demo")
    .flags("isTest")
    .environment(SERVER_ENV = "staging")
The same app id options, written in the call
launchApp(
    androidAppId = "com.shop.app.debug",
    iosAppId = "com.shop.ios",
    flags = ["isTest"],
    environment = args(SERVER_ENV = "staging"),
)
launchApp(
    "com.shop.app",
    keepFiles = ["shared_prefs/keys.xml"], clearState = true,
)
argumentapp id for both platforms (default: the run's app) androidAppIdAndroid package id · text iosAppIdiOS bundle id · text clearStateClear app data before launching · true or false, default false keepFilesWith clearState: files or folders to keep (Android debug builds, iOS simulators, iPhones with the in-app SDK) · list of text permissionsPermissions to set before launch: true grants, false revokes · args(camera = true, …) argumentsAndroid intent extras, iOS launch arguments · args(name = "value", …) flagsiOS launch arguments that are words on their own; Android warns · list of text environmentEnvironment variables the app starts with (iOS); Android warns · args(name = "value", …)

launchApp Settings 8

Options of launchApp. Write each as an option in the call, launchApp(clearState = true), or chained one per line, launchApp().clearState(). Setting the same one both ways, or twice, is an error. Examples show the app id; see launchApp for when you can leave it out.

.androidThe app id on Android

Use it when one flow runs on both platforms and the Android package differs from the iOS bundle id.

Different ids per platform
launchApp()
    .android("com.shop.app")
    .iOS("com.shop.ios")

The option form is androidAppId.

.iOSThe app id (bundle id) on iOS

Use it with .android when the bundle id differs from the Android package.

Set only the iOS id
launchApp("com.shop.app").iOS("com.shop.ios")

The option form is iosAppId. Android runs use com.shop.app.

.permissionsPermissions to set before launch: true grants, false revokes

Use it whenever a screen asks for a permission at launch, so the system dialog never gets in the way. Also use false to test what the app does when refused.

In the app Sets the permissions before the app starts. true grants, false revokes.

Allow notifications, refuse location
launchApp("com.shop.app")
    .permissions(notifications = true, location = false)

The app starts with notifications on and shows its "no location" state. No system dialog appears.

Allow everything
launchApp("com.shop.app", permissions = args(all = true))

Limits Both platforms: camera, location, microphone, notifications, photos, contacts, calendar, bluetooth. iOS: health, homekit, medialibrary, motion, reminders, siri, speech, usertracking. Android: phone, storage, sms.

.clearStateClear app data before launching (no argument: true)

Use it when a test must start logged out, as on a fresh install.

In the app Stops the app, wipes its data, then starts it.

Start from a clean app
launchApp("com.shop.app").clearState()
launchApp("com.shop.app", clearState = true)

Limits On iOS, Keychain items stay, so an app that keeps its login there stays logged in; uninstallApp and installApp give a true fresh start. A physical iPhone needs the native iOS in-app SDK. Without it the step warns and the app starts with its data.

.keepFilesWith clearState: files or folders to keep (Android debug builds, iOS simulators, iPhones with the in-app SDK)

Use it with clearState to keep the one thing you don't want to redo each run, such as a device registration or a seeded database.

In the app Clears the app's data except these files and folders. Paths are relative to the app's data folder. A folder keeps everything in it, and * matches any characters.

Log out, but stay registered on this device
launchApp("com.shop.app")
    .clearState()
    .keepFiles("shared_prefs/device_id.xml", "databases/*.db")

The app starts logged out and skips device registration. Without clearState the list is ignored.

The same flow on Android and iOS
launchApp("com.shop.app")
    .clearState()
    .keepFiles("shared_prefs/device_id.xml", "Library/Preferences/device.plist")

A path that doesn't exist on a platform keeps nothing there, and isn't an error.

Limits Works on Android debug builds, iOS simulators, and physical iPhones with the in-app SDK. On other Android builds, and on a physical iPhone without the native iOS in-app SDK, nothing is cleared: the step warns and the flow goes on, with the app's data still there. Paths differ by platform, such as shared_prefs/keys.xml on Android and Library/Preferences/keys.plist on iOS; list both for a flow that runs on both.

.argumentsAndroid intent extras, iOS launch arguments

Use it to put the app into a test state from outside: a mock server, a demo account, a feature on or off.

In the app Android receives them as string intent extras. iOS receives them as launch arguments, which the app reads from UserDefaults.

Point the app at a mock server
launchApp("com.shop.app")
    .arguments(mockBaseUrl = "http://10.0.2.2:8080", onboarding = false)

Android: intent.getStringExtra("mockBaseUrl"). iOS: UserDefaults.standard.string(forKey: "mockBaseUrl").

A name with a dot, and a flow variable
val user = "ann"
launchApp(
    "com.shop.app",
    arguments = args("ds.mutation" = "off", user = "${user}"),
)

Values are quoted (numbers, true and false may be bare). Write "${name}" for a variable.

.flagsiOS launch arguments that are words on their own

Use it for an iOS app that checks for a word in its launch arguments, the common way to switch on a UI-testing mode.

In the app Each flag reaches the app as a launch argument on its own, with no value.

Turn on the app's UI-testing mode
launchApp("com.shop.app").flags("isTest", "SkipSelfie")

iOS: ProcessInfo.processInfo.arguments.contains("isTest") is true.

Limits iOS only. On Android the app launches without them and the step warns. Use arguments there.

.environmentEnvironment variables the app starts with (iOS)

Use it for an iOS app that reads settings from environment variables, such as which server to use.

In the app The app starts with these environment variables set.

Run against staging
launchApp("com.shop.app")
    .environment(SERVER_ENV = "staging", LOG_LEVEL = "debug")

iOS: ProcessInfo.processInfo.environment["SERVER_ENV"] is "staging".

Limits iOS only. On Android the app launches without them and the step warns. Use arguments there.

Tap & Gesture 9

tapTap an element or a screen point

When to use The step you use most: buttons, links, rows, tabs.

In the app Waits for the element to appear, up to timeout, then taps its center and waits for the screen to settle.

Tap a button, giving a slow screen more time
tap("Sign in")
tap("Pay", timeout = 30s)
Tap several times
tap(id("plus"), count = 3)

Adds 3 to a quantity.

Tap off-center, such as a link inside a long label
tap("Terms and privacy", offsetX = 120, offsetY = 0)

Offsets are pixels from the element's center.

argumentelement or point(x, y) countNumber of taps · whole number, default 1 timeoutMax wait for the element to appear · duration (500ms, 10s) offsetXHorizontal offset from the element center (px) · whole number offsetYVertical offset from the element center (px) · whole number
doubleTapDouble-tap an element or a screen point

Use it for maps and images that zoom, and for anything that opens on a double tap.

Zoom a photo
doubleTap(id("photo"))
argumentelement or point(x, y)
longPressLong-press an element or a screen point

Use it for context menus, drag handles and selection modes.

Open the context menu of a row
longPress("Invoice 42", duration = 2s)
tap("Delete")
argumentelement or point(x, y) durationHow long to hold · duration (500ms, 10s)
swipeSwipe across the screen, or from an element, in a direction

Use it to go through pages and carousels, dismiss a card or a sheet, or pull to refresh.

In the app The finger moves in the direction you name, across the screen or starting on an element. A shorter duration makes a sharper fling.

Next page of a carousel
swipe(left)
Dismiss a bottom sheet by dragging it down
swipe(down, from = id("sheet_handle"), duration = 600ms)
Pull to refresh
swipe(down, from = "Inbox")
argumentSwipe direction · up | down | left | right durationSwipe duration · duration (500ms, 10s) fromElement the gesture starts on: its text, or a nested selector · element
scrollScroll the screen, or from an element, one step

Use it to move a list one step. To reach a specific element, use scrollTo, which stops as soon as it is there.

In the app The finger moves in the direction you name, so scroll(up), the default, moves a list towards its end.

One step down a list, then back
scroll
scroll(down, speed = slow, distance = 0.3)
Scroll a horizontal tab row, not the screen
scroll(left, from = "Showcase")

from starts the gesture on that element, so only that row moves. distance is a share of the screen, from 0.1 to 0.95. The default is 0.6.

argumentScroll direction · up | down | left | right speedSwipe speed · word, slow | fast distanceFraction of the screen to scroll (0.1-0.95) · number, default 0.6 fromElement the gesture starts on: its text, or a nested selector · element
scrollToScroll until an element is on screen

Use it when the element is further down a list and you don't know how far.

In the app Scrolls, checks, scrolls again, and stops once the element is on screen. Fails when maxScrolls or timeout runs out.

Find a row far down a list
scrollTo("Terms of service")
tap("Terms of service")

direction is the way the finger moves: up, the default, moves towards the end of a list; use down to go back towards the top.

Back up, in one list, with limits
scrollTo(
    id("row_1"),
    direction = down,
    from = id("orders_list"),
    maxScrolls = 30,
    timeout = 20s,
    speed = slow,
)
Set the time of each swipe
scrollTo("Footer", duration = 400ms)

duration overrides speed. By default it tries 20 scrolls on Android and 10 on iOS.

argumentelement directionScroll direction · word, default up, up | down | left | right maxScrollsScroll attempts before giving up · whole number timeoutMax wait · duration (500ms, 10s) speedSwipe speed · word, slow | fast durationDuration of each swipe; overrides speed · duration (500ms, 10s) fromElement the gesture starts on: its text, or a nested selector · element
dragDrag one element onto another

Use it to reorder a list, move a card between columns, or drop a pin.

In the app Presses the first element, moves to the target and lets go.

Move a card to another column
drag("Card A", to = text("Done").below("Board"))
Lists that only start dragging after a long press
drag(id("row_3"), to = id("row_1"), duration = 800ms, longPress = true)
Between screen points
drag(point(20%, 50%), to = point(80%, 50%))
argumentElement to drag: its text, point(x, y), or a nested selector toDrop target: its text, point(x, y), or a nested selector · element durationHow long the move takes (default: a fast move) · duration (500ms, 10s) longPressPress long before moving, for an element dragged only after a long press · true or false, default false
pinchInPinch in (zoom out) on the screen

Use it to zoom out on a map, a photo or a chart.

Zoom out
pinchIn

Limits On Android this needs the in-app SDK.

pinchOutPinch out (zoom in) on the screen

Use it to zoom in on a map, a photo or a chart.

Zoom in, then check the detail appears
pinchOut
assertVisible("Street view")

Limits On Android this needs the in-app SDK.

Input 7

eraseErase characters from the focused field

Use it to delete the last few characters, for example to test how a field reacts to editing. To empty a field, use clearText.

In the app Works on the field with focus.

Delete the last five characters
erase(5)
argumentNumber of characters to erase
clearTextFocus a text field and clear it

Use it to empty a field that already has text in it, before typing or to test validation.

In the app Focuses the field and clears it.

Empty a field and check the error
clearText(id("email_input"))
assertVisible("Email is required")
argumentelement
copyTextCopy an element's text to the clipboard

Use it to test copy buttons' targets, or to carry a value such as a code from one field to another.

In the app Copies the element's text to the device clipboard.

Copy a code and paste it elsewhere
copyText(id("promo_code"))
tap("Enter code")
paste
argumentelement
pastePaste the clipboard into the focused field

Use it after copyText or setClipboard, to test paste handling.

In the app Pastes the clipboard into the field with focus.

Paste into a focused field
setClipboard("SAVE10")
tap("Promo code")
paste
setClipboardSet the device clipboard

Use it to test screens that read the clipboard, such as "Paste your one-time code".

Put a code on the clipboard
setClipboard("123456")
tap("Paste code")
argumentClipboard text
typeType text, into the focused field or into the field a selector picks

When to use Fill in any text field.

In the app Finds the field if you name one and taps it, or types into whichever field has focus. A plain text on into is the field's label, placeholder or hint.

Fill in a form
type("[email protected]", into = "Email")
type(@password, into = id("password"), hideKeyboard = true)
Replace what's in a field
type("New name", into = "Full name", clearFirst = true)

The field is emptied first, so the old text is gone.

Test data that never repeats
tap("Email")
type(randomEmail("example.com"))

For a sign-up form that refuses an address it has seen. See randomEmail for the others. Random values can't use into, so tap the field first.

argumentthe text to type, or randomEmail(domain?), randomNumber(n), randomText(n), randomName() intoThe field to type into; a plain text is its label, placeholder or hint. Without it, the focused field · element clearFirstErase the field before typing · true or false, default false hideKeyboardDismiss the keyboard after typing · true or false, default false
valSet a variable: a read of an element's text (textOf, numberOf as a number), the date (day, month, year, date) or a value; later steps read it as $name or ${name}

Use it to remember something from the screen for a later step, or to work a value out.

In the app textOf and numberOf read an element; anything else is computed. Later steps read it as $name or ${name}, and it lasts for the whole run, including later units of a scenario.

Check that a discount was applied
val before = numberOf(id("total"))
tap("Apply SAVE10")
val expected = before - 10
assertThat(numberOf(id("total")) == expected)
Keep a text and use it later
val orderId = textOf(id("order_id"))
tap("My orders")
assertVisible("Order $orderId")
Change a variable
val attempts = 1
attempts = attempts + 1
log("Attempt ${attempts}")

Without val, name = value sets it too. Names use letters, digits and _.

argumentname = value

Assertions 10

Checks. A check that fails stops the flow, unless it is optional. An assertion gives the element the run's default wait to appear (at least 10 s); to wait longer, put waitFor with a timeout in front of it.

assertVisibleCheck that an element is on screen

When to use The check you use most: did we reach the right screen, did the message appear.

Check a screen and a partial text
tap("Sign in")
assertVisible("Welcome back")
assertVisible(contains("items in your cart"))
Check an element in a specific place
assertVisible("Paid").below("Invoice 42")
argumentelement
assertNotVisibleCheck that an element is not on screen

Use it to confirm that something went away or was never shown: an error, a deleted row, a paywall.

The deleted row is gone
tap("Delete")
assertNotVisible("Invoice 42")
argumentelement
assertCheckedCheck that a checkbox or switch is checked

Use it for checkboxes, switches and radio buttons that should be on.

Remember me stays on
tap("Remember me")
assertChecked(id("rememberMe"))
argumentelement
assertNotCheckedCheck that a checkbox or switch is not checked

Use it for checkboxes, switches and radio buttons that should be off.

A switch starts off
assertNotChecked(id("marketing_emails"))
argumentelement
assertEnabledCheck that an element is enabled

Use it to check that a button turns on once a form is valid.

Submit turns on after a valid email
type("[email protected]", into = "Email")
assertEnabled(id("submit_btn"))
argumentelement
assertDisabledCheck that an element is disabled

Use it to check that a button stays off until a form is complete.

Submit is off on an empty form
assertDisabled(id("submit_btn"))
argumentelement
assertFocusedCheck that a field or control has input focus

Use it to check that the cursor lands in the right field, such as search on open or the next field after an error.

Search opens ready to type
tap(label("Search"))
assertFocused(id("search_field"))
argumentelement
assertTextCheck that an element's text equals a value

Use it when one element's exact text matters, such as a total. assertVisible would pass on the same text anywhere on the screen.

The price label says exactly this
assertText(id("price_label"), equals = "\$9.99")
argumentelement equalsExpected text · text, required
assertCountCheck how many elements match a selector

Use it to check how many results, rows or items there are.

Three items in the cart
assertCount(id("cart_row"), 3)
assertCount(id("cart_row").visible(), count = 3)
argumentelement countExpected number of matches · whole number, required
assertThatCheck a comparison of variables and values, e.g. a balance after a transfer

Use it to compare values: a balance after a transfer, a total against a sum.

In the app Compares with ==, !=, <, <=, >, >= and works out + - * /. When it fails, the message shows both sides.

A transfer took exactly 100 off the balance
val before = numberOf(id("balance"))
tap("Send 100")
assertThat(numberOf(id("balance")) == before - 100)
Allow for rounding
val rate = numberOf(id("rate"))
assertThat(rate == 1.25, tolerance = 0.01)
argumenta comparison of values: == != < <= > >= with + - * / toleranceNumbers this close count as equal · number

Wait 6

waitForWait until an element is on screen

Use it when a screen can take longer than the default wait: after a login, a payment, a large download. Not needed before tap or type on the same element, which already wait.

In the app Checks until the element appears, then moves on at once. Fails when timeout runs out. The default is the run's wait timeout, at least 10 s.

Wait for a slow screen
tap("Pay")
waitFor("Payment complete", timeout = 60s)
waitFor(contains("Welcome"))
argumentelement timeoutMax wait in ms (default: the run's wait timeout) · duration (500ms, 10s)
waitUntilGoneWait until an element is gone from the screen

Use it for spinners and progress bars, so the next step doesn't run too early.

Wait for a spinner to finish
tap("Refresh")
waitUntilGone(id("spinner"), timeout = 20s)
argumentelement timeoutMax wait in ms (default: the run's wait timeout) · duration (500ms, 10s)
waitPause for a time, or wait until a text appears or disappears

When to use A last resort, for something with no visible signal. It always takes the full time and makes flows slow; prefer waitFor or waitUntilGone.

Pause for a moment
wait(2s)
argumentA duration in ms, or a text to wait for (up to 10 s)
waitForAnimationsWait until the screen stops changing (0.3 s unchanged)

Use it before a screenshot, or a tap that animation throws off.

In the app Waits until the screen has not changed for 0.3 s. Gives up after timeout, by default 3 s.

Let the screen stop moving
tap("Open menu")
waitForAnimations(timeout = 5s)
screenshot("menu")
timeoutMax wait in ms (default 3000) · duration (500ms, 10s)
waitForIdleWait until the device UI is idle

Use it when the app is still busy after a step and no element tells you when it's done.

Wait until the device UI is idle
waitForIdle(timeout = 10s)
timeoutMax wait in ms (default: the run's wait timeout) · duration (500ms, 10s)
waitForValueWait until a Request key from Profiles has the value you expect

Use it when a backend needs time: wait for an order to ship or an email to arrive before going on. Works with a Request key from Profiles, which fetches a value over HTTP.

In the app Fetches the value again every interval until it matches. Fails when timeout runs out.

Wait for a backend status
tap("Place order")
waitForValue(
    @orderStatus,
    equals = "Shipped",
    timeout = 2m,
    interval = 5s,
)
Wait until a value holds a text
waitForValue(@lastEmailSubject, contains = "Your receipt")

Use equals or contains, not both. By default it reads every 3 s for up to 1 minute.

argumentRequest key to read again, as @key equalsWait until the value is exactly this · text containsWait until the value contains this · text timeoutMax wait in ms · duration (500ms, 10s), default 60s intervalTime between reads in ms · duration (500ms, 10s), default 3s

Navigation 4

backPress the device back button

Use it to leave a screen the way a user would, and to test back handling.

Leave a details screen
tap("Invoice 42")
back
assertVisible("Invoices")
hideKeyboardDismiss the software keyboard

Use it when the keyboard covers the next thing you need to tap.

Reveal the button under the keyboard
type("[email protected]", into = "Email")
hideKeyboard
tap("Continue")
pressKeyPress a hardware key

Use it to submit with the keyboard's Enter key, or for hardware keys.

Submit a search with Enter
type("shoes", into = "Search")
pressKey(enter)
Hardware keys
pressKey(home)
pressKey(volume_up)
argumentKey name

Limits Android: home, back, enter, tab, escape, volume_up, volume_down, power, menu, recent, delete, backspace, arrow_up, arrow_down, arrow_left, arrow_right. iOS: enter, backspace, delete, tab, escape, back.

screenshotSave a screenshot of the screen, or of one element

Use it to keep a picture of a screen in the run's artifacts, for a report or a review.

In the app Saves a file with the run. It doesn't compare with anything, and the flow goes on.

Keep the whole screen, or one element
screenshot("checkout")
screenshot("summary", crop = id("summary"))

crop takes text, contains, regex, id, testTag, className and .index. A failed step takes a screenshot on its own, so you don't need one for failures.

argumenta name for the file cropCrop to this element · element

Device 13

setOrientationRotate the device

Use it to test landscape layouts, and that state survives a rotation.

The form keeps its text when rotated
type("Ann", into = "Name")
setOrientation(landscape)
assertVisible("Ann")
setOrientation(portrait)
argumentOrientation · portrait | landscape

Limits On iOS this needs the XCUITest runner. The in-app SDK can't rotate the device.

setFontScaleSet the device font scale

Use it to test that text doesn't overflow or get cut off at large accessibility sizes.

Large text
setFontScale(1.5)
launchApp("com.shop.app")
assertVisible("Continue")
argumentScale factor

Limits Android only.

addContactAdd a contact to the device's address book (Android, iOS simulator)

Use it to test contact pickers and address-book import without setting up a device by hand.

Have a contact to pick
addContact(
    "Test Contact",
    phone = "555555555",
    email = "[email protected]",
)
tap("Choose contact")
argumentDisplay name phonePhone number · text emailEmail address · text

Limits Android and iOS simulators, not physical iPhones.

deleteContactsDelete every device contact with a name (Android); none there is fine

Use it to clean up after addContact, or to start with no matching contact.

In the app Deletes every contact with that name. Finding none is fine.

Start clean
deleteContacts("Test Contact")
argumentDisplay name of the contacts to delete

Limits Android only. On an iOS simulator, erase the simulator to clear contacts.

addMediaAdd an image or video to the device gallery

Use it to test photo pickers and uploads with a known image.

In the app Adds an image or video to the device gallery. The path is inside the project folder.

Pick a known photo
addMedia("fixtures/avatar.png")
tap("Change photo")
argumentImage or video inside the project folder, relative to the flow file

Limits On iOS, simulators only.

clearNotificationsDismiss all notifications

Use it to start with an empty shade, so that a notification check sees only the new one.

Empty the shade
clearNotifications

Limits Android only.

openNotificationsOpen the notification shade

Use it to test a push notification: see it, tap it, land on the right screen.

Open a push notification
openNotifications
tap("Your order has shipped")
assertVisible("Order details")

Limits Android only.

startRecordingStart recording the screen

Use it to keep a video of a tricky stretch of a flow.

In the app Records the screen to the run's artifacts until stopRecording, or until the flow ends.

Record the checkout
startRecording("checkout")
tap("Pay")
waitFor("Payment complete")
stopRecording
argumentRecording name
stopRecordingStop the screen recording

Use it to end a recording begun with startRecording.

End the recording
startRecording
tap("Pay")
stopRecording
appActionRun an action the app registered, e.g. reset state and open a screen; returned values become variables (in-app SDK driver only)

When to use The fast way into a test state: let the app do it in code instead of tapping through setup screens. Seed a user, reset a cart, open a screen.

In the app Runs code you registered in the app with registerAction. Values the action returns become flow variables.

Set up a user without touching the UI
appAction("seedUser", timeout = 30s, args = args(plan = "pro"))
tap("Profile")
assertVisible("Pro plan")

Android: DevScenarioInstrumentation.registerAction("seedUser") { args -> … }. iOS: DevScenarioAppInstrumentation.registerAction("seedUser") { args in … }. The default limit is 1 minute.

argumentthe name the app registered the action under timeoutHow long the app gets to finish the action · duration (500ms, 10s), default 1m argsValues the action receives · args(name = "value", …)

Limits Needs the in-app SDK driver. The step fails on the others.

setPermissionsGrant or deny app permissions

Use it to change a permission during a flow, such as revoking the camera and checking how the screen reacts. To set one before the app starts, use launchApp.permissions.

In the app true grants, false revokes. all covers every permission.

Revoke while the app runs
setPermissions(camera = false, location = true)
tap("Scan")
assertVisible("Camera access is off")
Everything at once, for another app
setPermissions(all = true, appId = "com.example.companion")
<permission>camera, location, notifications, all, …: true grants, false revokes · true or false appIdApp id (default: the flow's app) · text
setLocationSet the device GPS location

Use it for maps, delivery areas, and features limited to a country.

In the app Moves the device's reported GPS position.

Pretend to be in Tbilisi
setLocation(41.7151, 44.8271)
tap("Find stores near me")
assertVisible("Rustaveli Ave")
argumentlatitude, longitude
setSystemPropertySet system properties inside the app (in-app SDK driver only; other drivers warn)

Use it to pass a value to app code while it runs, such as a test-run marker or an environment name.

In the app Hands the value to the app through the in-app SDK. One per call, always stored as text.

Tell the app it's in a test
setSystemProperty("isTestRun", "true")
setSystemProperty("env", "staging")
argumentname, value

Limits Needs the in-app SDK driver. On the others the step finishes with a warning, and nothing is set.

Files 4

Read, check and change the files of the app under test, such as a log it writes or a setting it keeps. read and file take a file name relative to the app's folder, or regex("…") for the newest match. To put a file from this computer where the system file picker lists it, use pushFile.

readRead a text file of the app under test. Chain .lastLine(), .firstLine(), .contains(text) or .equals(text), inside val, assertThat or if; a regex picks the newest match

Use it to check what the app wrote to a file, such as a log of the screens it opened or the analytics events it sent.

In the app Reads a text file of the app into a value. Chain .lastLine(), .firstLine(), .contains("…") or .equals("…"), inside val, assertThat or if. A missing file fails the step, and the message lists what the folder holds. The read step's log names the file and its size. A comparison with == and a failed assertion show the value, cut to 200 characters.

Check that the app logged a screen
launchApp("com.example.app")
tap("Profile")
assertThat(read("screens.log").lastLine() == "Profile")

Passes when the last line of the app's screens.log is exactly Profile. A trailing newline doesn't count as a line.

Look at the last line, or the whole file
assertThat(read("screens.log").lastLine().contains("Profile"))
assertThat(read("screens.log").firstLine() == "Home")
assertThat(read("screens.log").contains("Checkout"))
assertThat(read("screens.log").contains("Error") == false)
Find a log whose name changes by date
assertThat(read(regex("log-.*\\.txt")).lastLine() == "My Screen")

The regex matches a file's name or its path in the folder. With several matches, the newest one is read.

Keep the text and use it later
val content = read("screens.log")
log("Screens so far: $content")
assertThat(content.contains("Home"))
Branch on what the file holds
if (read("settings.txt").contains("onboarded")) {
    tap("Skip")
}
Another folder or app
val cached = read("app.log", folder = cache)
val other = read("export.csv", folder = external, appId = "com.example.other")
argumenta file name or regex("…"), inside the app's folder

Limits Android needs a debuggable build, except for folder = external. An iPhone needs a development-signed build, and this hasn't yet been run on a physical iPhone. Text only, up to 5 MB.

fileChange a file of the app under test: .createIfNotExists(), .write(text) replaces it, .append(text) adds a line, .clear(), .delete(); .exists() inside val, assertThat or if

Use it to set up a file before a test, to feed the app data, or to clean up after one.

In the app Changes a file of the app. .write replaces everything, .append adds a line at the bottom, .clear empties the file, and .createIfNotExists makes an empty one. Folders in the path are made when needed. Clearing or deleting a missing file does nothing. .exists() goes inside val, assertThat or if.

Start from a clean log, then check what the run wrote
file("screens.log").clear()
launchApp("com.example.app")
tap("Profile")
assertThat(read("screens.log").contains("Profile"))
Where a new file goes
file("notes/test.txt").createIfNotExists()

Android: /data/user/0/<app id>/files/notes/test.txt, the same place as context.filesDir. iOS: <app's data container>/Documents/notes/test.txt. The notes folder is made when needed.

Create, write, add to and remove a file
file("notes/test.txt").createIfNotExists()
file("notes/test.txt").write("first line")
file("notes/test.txt").append("second line")
assertThat(read("notes/test.txt").lastLine() == "second line")
file("notes/test.txt").delete()

The file ends as first line, then second line, before it is deleted.

Give the app a setting before it starts
file("config.json").write("{\"beta\": true}")
launchApp("com.example.app")
assertVisible("Beta features")
Do something only when a file is there
if (file("draft.txt").exists()) {
    file("draft.txt").delete()
}
assertThat(file("draft.txt").exists() == false)
Use a variable in a name or text
val day = "2026-02-10"
file("log-$day.txt").append("Started on $day")
Another folder or app, or the newest match
file("app.log", folder = cache).clear()
file("data.db-wal", folder = data, appId = "com.example.other").delete()
file(regex("log-.*\\.txt")).delete()
argumenta file name or regex("…"), inside the app's folder

Limits Android needs a debuggable build, except for folder = external. An iPhone needs a development-signed build and can't delete a file: use .clear(). This hasn't yet been run on a physical iPhone. There .append rewrites the file, so a line the app writes at that moment can be lost. Up to 64 KB of text in a step.

FoldersWhere in the app's storage read and file look

In the app folder = files is the default: files/ on Android, Documents/ on iOS. cache is cache/ on Android and Library/Caches/ on iOS. data is the root of the app's data. external is /sdcard/Android/data/<app>/files on Android, and iOS has none, so the step fails there. Paths stay inside the folder: no absolute paths and no . or .. parts.

The same file name in two folders
file("app.log").write("in files")
file("app.log", folder = cache).write("in cache")
assertThat(read("app.log", folder = cache) == "in cache")
pushFilePut a file where the system file picker finds it

Use it to test file pickers and "open file" flows without preparing a device by hand.

In the app Android: the file goes to Downloads. iOS: it goes to the app's Documents folder.

A file made from text in the flow
pushFile("note.txt", content = "Hello from the test")
tap("Attach file")
A file from the project
pushFile(path = "fixtures/report.pdf")
pushFile("invoice.pdf", path = "fixtures/report.pdf")
Into another iOS app's Documents
pushFile("note.txt", content = "Hi", appId = "com.example.files")

Use content or path, not both. content also works in regression bundles; path files aren't packed into them.

argumentFile name on the device (default: the name of path) contentText written to the file · text pathHost file to copy, inside the project folder, relative to the flow file · text appIdiOS: app whose Documents folder gets the file (default: the flow's appId) · text

Limits On iOS, the file picker shows the folder only when the app sets UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace.

Device Actions 6

resetPermissionsRevoke all runtime permissions of an app (Android)

Use it to get the permission dialogs back, to test what a first-time user sees.

In the app Revokes all the app's runtime permissions.

See the first-run dialog again
resetPermissions(appId = "com.shop.app")
launchApp("com.shop.app")
assertVisible("Allow")

The app id can also be the plain argument: resetPermissions("com.shop.app").

argumentApp id appIdApp id · text, required

Limits Android only.

fingerprintSimulate a fingerprint / Face ID / Touch ID on an emulator or simulator

Use it to test biometric login, both accepted and refused.

Log in with a fingerprint
tap("Log in with fingerprint")
fingerprint
assertVisible("Welcome back")
A failed match, or a chosen finger (Android emulator)
fingerprint(match = false)
fingerprint(fingerId = 2)
matchfalse simulates a finger or face that isn't enrolled · true or false, default true fingerIdEnrolled finger id (Android emulator) · whole number, default 1
darkModetrue: Switch the device to dark theme; false: the opposite

Use it to test dark theme, or to take screenshots in both themes.

Both themes
darkMode(true)
screenshot("home-dark")
darkMode(false)
screenshot("home-light")
argumenttrue or false
wifitrue: Turn Wi-Fi on (Android); false: the opposite

Use it to test offline states and how the app recovers.

The offline message, then recovery
wifi(false)
tap("Refresh")
assertVisible("No connection")
wifi(true)
tap("Retry")
argumenttrue or false

Limits Android only.

airplaneModetrue: Turn airplane mode on (Android); false: the opposite

Use it to test having no network at all: no Wi-Fi and no mobile data.

Fully offline
airplaneMode(true)
tap("Sync")
assertVisible("You're offline")
airplaneMode(false)
argumenttrue or false

Limits Android only.

animationstrue: Restore animation scales to 1 (Android); false: the opposite

When to use Turn them off to make flows faster and steadier, or on to test the animations themselves.

In the app Sets the device's animation scales to 0 or back to 1.

Faster, steadier runs
animations(false)
launchApp("com.shop.app")
argumenttrue or false

Limits Android only.

Flow Control 13

Decide what runs, and repeat it.

shellRun an adb shell (Android) or allowed simctl (iOS simulator) command on the run's device

When to use The way out when no command does what you need: read a device setting, change a system value.

In the app Runs on the run's device. Avoid it for taps and typing: tap and type also reach dialogs and bottom sheets.

A command on Android
shell("settings put system screen_brightness 50")
A command on an iOS simulator
shell("status_bar booted override --time 9:41")
argumentCommand line

Limits Android runs adb shell. iOS simulators run simctl with spawn, privacy, status_bar, location, push, ui or pbcopy on this run's simulator only.

useFrom this line on, bare @key reads this param profile, also in the later steps and scenarios of the run; another use(...) switches profiles. @profile.<profile>.<key> reads one key of any profile

Use it to pick which profile a bare @key reads, for example a staging user or a production-like user.

In the app From this line on, including later units of the run. A later use switches. A key the profile doesn't have fails, even if the active profile has it.

Read this unit's test data from one profile
use(@profile.staging)
type(@username, into = "Email")

@profile.staging.username reads a single key without switching.

argument@profile.<profile>
setLanguageResolve @prefix.key translations in another language for the rest of the run, including later units and scenarios. Only Dev Scenario's lookup changes, not the device or app language

Use it to check a screen in another language within one run.

In the app Changes which language @prefix.key translations read. It doesn't change the language of the device or the app, so switch those in the app first.

Check the same screen in Spanish
tap("Language")
tap("Español")
setLanguage("Spanish")
assertVisible(@langs.welcome)
Only one app's translations, by language code
setLanguage("ka", app = "Shop")
argumentLanguage name or code (e.g. Spanish, es) appTranslation app name, id or prefix; omit for every app · text
dismissInterruptingDialogsFrom this line on (true) or off (false): a tap that a dialog or sheet intercepts closes it (Back on Android, the in-app SDK's dismiss on iOS) and taps again. Off: the tap fails. Off by default; carries into later units of the run. Assertions never close anything. Android and iOS in-app SDK drivers only

Use it when dialogs you don't control may pop up at any time and block a tap, such as a rating prompt.

In the app From this line on, a tap blocked by a dialog or sheet closes it (Back on Android, the SDK's dismiss on iOS) and taps again. Off, the default, the tap fails. Assertions never close anything.

Don't let popups fail the run
dismissInterruptingDialogs(true)
tap("Checkout")
dismissInterruptingDialogs(false)

It carries into later units of the run until turned off.

argumenttrue closes an intercepting dialog and taps again, false fails the tap

Limits In-app SDK drivers only. UIAutomator and the XCUITest runner ignore it.

logWrite a message to the run log

Use it to leave notes and values in the run log, which helps when reading a failure.

Note a value
val total = numberOf(id("total"))
log("Total before discount: $total")
argumentMessage
ifRun a block when a condition holds; visible(any selector, timeout = …) works as the whole condition, without else

Use it for things that differ between platforms or runs, such as a dialog that sometimes appears.

In the app visible("text") looks once, without waiting, so a missing element costs nothing. The step log shows which way it went.

Handle either dialog, or none
if (platform == ios && visible("Allow")) {
    tap("Allow")
} else if (visible("OK")) {
    tap("OK")
} else {
    log("No dialog")
}
Any selector, with a wait
if (visible(id("promo"), timeout = 2s)) {
    tap(id("promo_close"))
}

With a selector other than plain text, or a timeout, it must be the whole condition, with no else.

Compare values
val balance = numberOf(id("balance"))
if (balance < 100) {
    tap("Top up")
}

Use &&, || and parentheses to combine. ! isn't supported: use notVisible, != or an else.

argumenta condition: platform == ios, visible("text"), notVisible("text"), permission(camera) == allowed, comparisons, && ||
retryRun commands again until they pass

Use it when several steps must pass together and may need another go, such as refreshing until a status changes. For a single step, retryOnFail is shorter.

In the app Runs the whole block again from the top if a step in it fails, up to times, by default 3. The flow fails only if the last attempt fails.

Refresh until the status changes
retry(times = 5) {
    tap("Refresh")
    assertVisible("Status: Shipped")
}
timesMax attempts · whole number, default 3 optionalA failure is a warning; the flow continues · true or false
forEachRun commands once for each element a selector matches

Use it to do the same steps for each row of a list.

In the app Runs the block once per match. Inside it, ${item.text}, ${item.index}, ${item.id} and ${item.testTag} describe the element. Variables go back to how they were once the loop ends.

Open each order, check it, go back
forEach(regex("^Order #.*")) {
    tap("${item.text}")
    assertVisible("Order details")
    back
}
argumentelement
skipIfSkip the rest of the flow when a condition holds

Use it at the top of a flow that doesn't apply everywhere, such as an Android-only feature, or a login step when already logged in.

In the app Ends the flow there, reported as skipped, not failed.

Skip on one platform, or depending on the screen
skipIf(platform == android)
skipIf(visible("Already logged in"))
skipIf(notVisible(id("beta_banner"), timeout = 1s))

Join conditions with &&: all must hold. Without timeout, visible and notVisible take the default wait; timeout = 0s looks once.

argumentplatform == …, visible(…) or notVisible(…), joined by &&
onCompleteSteps to run after the flow (onComplete) or after a failure (onError); at the top level of a flow

Use it to tidy up after a pass: log out, delete test data, take a final screenshot.

In the app Runs after the flow passes. A step that fails here is reported, but doesn't change the result. Both blocks go at the top level of a flow, not inside another block.

A final picture on a pass, evidence on a failure
onComplete {
    screenshot("end")
}
onError {
    screenshot("failure")
}
metaThe flow's metadata, first line of the flow; runs nothing

Use it to label a flow for filtering and reports.

In the app Runs nothing. tags work with the CLI's --filter-tag; externalKey links the flow to a test case in your test-management tool.

Label a flow
meta(
    externalKey = "TC-1234",
    tags = [smoke, login],
    owner = "qa-team",
    requirement = "PROJ-42",
    severity = critical,
)
launchApp("com.shop.app")
externalKeyTest case key · text tagsTags · list ownerOwner · text requirementRequirement it covers · text severityHow bad a failure is · word
else and else ifThe other branch of an if

Use it when each case needs its own steps. See if for a full example.

Two branches
if (platform == ios) {
    tap("Allow While Using App")
} else {
    tap("While using the app")
}
onErrorSteps to run after the flow fails or times out

Use it to collect evidence or clean up when something goes wrong, so a failure doesn't affect the next test.

In the app Runs after a failure or a timeout. It can't change the result: the flow stays failed.

Log out even after a failure
onError {
    screenshot("failed-state")
    tap("Log out", optional = true)
}

Values & Conditions 14

What goes inside val, if, skipIf, assertThat and type.

textOfRead an element's text

Use it with val to keep a text exactly as shown.

Read a text
val name = textOf(id("profile_name"))
log("Logged in as $name")

The step waits for the element, and fails if it never appears.

dateThe date now, in a format you choose

Use it to check a date the app shows, or to work with a file named by date.

In the app Writes the date now as text. It uses the device's clock and time zone on Android and this computer's on iOS. With no format it writes 2026-02-10. It takes yyyy, yy, MM, M, dd, d, HH, H, mm, m, ss and s, and text in single quotes is kept as written. mm is the month, unless it follows an hour or comes before seconds. It has no names of months or days.

Use it directly in a step
assertVisible(date("dd/MM/yyyy"))
type(date("dd/MM/yyyy"), into = "Date")
tap(contains(date("yyyy")))
Keep it for a longer text
val today = date("dd/MM/yyyy")
assertVisible("Paid on $today")
Read today's log
val today = date("yyyy-MM-dd")
assertThat(read("logs/$today.log").contains("My Screen"))
assertThat(read(date("yyyy-MM-dd'.txt'")).contains("My Screen"))
Date and time together
val stamp = date("yyyy-MM-dd HH:mm:ss")
log("Started at $stamp")
day, month, yearToday's day, month or year, as a number

When to use Use them to compare or calculate with a part of today's date.

In the app Each gives a number without a leading zero: day() gives 4, month() gives 11 and year() gives 2026. For leading zeros, use date("dd").

Keep each part
val day = day()
val month = month()
val year = year()
log("It is day $day of month $month in $year")
Compare in a condition
if (day() == 1) {
    assertVisible("New statement")
}
assertThat(year() >= 2026)
numberOfRead the first number in an element's text

Use it for prices, balances and counts, so you can do arithmetic on them.

In the app Keeps only the first number: "$1,234.50" becomes 1234.5. Fails if the text has no number.

Read a balance and compare it inline
val balance = numberOf(id("balance"))
assertThat(numberOf(id("balance_after")) == balance - 100)
randomEmailA new email address to type

Use it for sign-ups that reject an address they've already seen.

With your own domain, or the default test.example.com
type(randomEmail("example.com"))
type(randomEmail())
randomNumberRandom digits to type

Use it for numeric fields: phone numbers, references.

Six digits, the default, or any length
type(randomNumber())
type(randomNumber(9))
randomTextRandom characters to type

Use it for names of things that must be unique, or to fill a field to a length.

Ten characters, the default, or any length
type(randomText())
type(randomText(200))
randomNameA random person's name to type

Use it for name fields.

Type a name
tap("Full name")
type(randomName())
platformWhich platform the run is on

Use it in if and skipIf for steps that differ by platform.

Only on iOS
if (platform == ios) {
    tap("Allow")
}

Only == works here: platform != ios fails the parse. Use else, or platform == android.

visible(…)True when an element is on screen now

Use it in if and skipIf. For a chained filter on a selector, see .visible.

With text, combined, or with a selector and a wait
if (visible("Allow") && platform == ios) {
    tap("Allow")
}
if (visible(id("promo"), timeout = 2s)) {
    tap(id("promo_close"))
}
notVisible(…)True when an element is not on screen now

Use it in if and skipIf to do something only when an element is absent.

Log in only if needed
if (notVisible("Log out")) {
    tap("Log in")
}
permission(…)Compare a permission's state with allowed or denied

Use it to act on a permission's current state.

Ask only when not yet allowed
if (permission(camera) == denied) {
    tap("Enable camera")
}

Limits Android only. iOS can't report a permission's state, so the condition never holds there.

args(…)A set of names and values

When to use Options such as permissions, arguments, environment and appAction's args take one.

Names and values, quoted when a name isn't a plain word
launchApp(
    "com.shop.app",
    arguments = args(mode = "demo", "ds.mutation" = "off"),
)
$name and ${name}Read a variable inside text

Use it to put a value you read or worked out into a step.

In the app Variables are read when the step runs. Bare names work in expressions, and $name or ${name} inside text.

In text and in an expression
val count = numberOf(id("count"))
val next = count + 1
log("Now $count, next ${next}")
assertThat(next > count)

Arithmetic and <, > need numbers: read prices with numberOf, not textOf.