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")
No command matches that filter.
All 129 entries, A to Z
Flow Syntax 7
How a flow file is written. A flow runs top to bottom and stops at the first step that fails.
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.
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.
tap("Refresh", retryOnFail = 2)
One normal attempt, then up to two more when it fails.
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.
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.
; and calls over several lines// 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.
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.
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.
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(@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.
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.
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.
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.
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.
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.
tap("Login")
tap(text("Login"))
Matches the whole text. "Login now" is not matched.
Use it when part of the text changes, such as a name or a count.
assertVisible(contains("items in your cart"))
waitFor(contains("Welcome"))
Use it when the text follows a pattern: order numbers, prices, dates.
tap(regex("""^Order #\d+$"""))
Raw strings save escaping every backslash.
When to use The most stable choice when your app has ids, because copy and translations can change without breaking the test.
tap(id("login_btn"))
Android resource id, iOS accessibility identifier.
Use it for Compose screens that set Modifier.testTag(…).
tap(testTag("checkout_button"))
Use it for icon buttons with no visible text, or for text fields by their placeholder.
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.
tap(className("android.widget.Switch")).below("Notifications")
Use it when only position or state identifies the element, such as an unlabeled button under a heading.
tap(any()).clickable().below("Card details")
any() on its own has nothing to look for and fails the parse.
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(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")).
Use it when several elements match and you want one by position. Prefer a relative modifier if the position has a meaning.
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.
Use it when the same label appears several times and a heading above it tells them apart.
tap("Edit").below("Shipping address")
The element must be entirely below the anchor. The nearest match wins.
Use it when the element you want sits over something easy to identify.
assertVisible(regex("Total: .*")).above("Pay")
Use it for controls in a row, such as an icon before a label.
tap(any()).clickable().leftOf("I accept the terms")
Use it for values and controls that follow a label in a row.
tap(className("android.widget.Switch")).rightOf("Dark theme")
Use it to look inside one part of the screen: a dialog, a list row, a card.
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".
Use it to pick a container by what it holds, such as the row with a certain name in it.
tap(any()).containsChild("Invoice 42")
Direct children only. To go deeper, nest it inside .childOf, as in the childOf example.
Use it for a control next to a label in the same row, without measuring position.
tap("Delete").siblingOf("Invoice 42")
The two elements share a parent. The anchor itself never matches.
Use it to skip a disabled copy of a button, or to assert that one is disabled.
tap("Save").enabled()
assertVisible("Save").enabled(false)
Use it when a label and its button both match and you want the part that takes taps.
tap(contains("Settings")).clickable()
Use it when an off-screen or hidden copy of an element also matches.
assertCount(id("row").visible(), 5)
Use it when a large container, such as a web view, holds text you don't want to match.
tap("Continue").excluding("android.webkit.WebView")
Takes one or more class names. Elements under them are ignored.
Use it for the tap-then-type pair that fills most forms.
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
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.
tap("Save draft")
stopApp
launchApp("com.shop.app")
assertVisible("Draft saved")
stopApp("com.android.chrome")
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.
clearState
clearState("com.example.companion")
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.
Use it to jump straight to a screen and skip the taps to get there, or to test that your deep links work.
In the app The system opens the link, in your app when it handles the link.
openLink("shop://orders/42")
assertVisible("Order #42")
openLink("https://example.com/reset?token=abc")
Use it to test a fresh install or an upgrade from an older 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")
Use it to start from nothing, such as a first-launch test on a physical iPhone where clearState isn't available.
uninstallApp("com.example.app")
installApp("builds/app.ipa")
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.
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.
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.
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")
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,
)
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.
Use it when one flow runs on both platforms and the Android package differs from the iOS bundle id.
launchApp()
.android("com.shop.app")
.iOS("com.shop.ios")
The option form is androidAppId.
Use it with .android when the bundle id differs from the Android package.
launchApp("com.shop.app").iOS("com.shop.ios")
The option form is iosAppId. Android runs use com.shop.app.
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.
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.
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.
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.
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.
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.
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.
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.
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.
launchApp("com.shop.app")
.arguments(mockBaseUrl = "http://10.0.2.2:8080", onboarding = false)
Android: intent.getStringExtra("mockBaseUrl"). iOS: UserDefaults.standard.string(forKey: "mockBaseUrl").
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.
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.
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.
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.
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
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("Sign in")
tap("Pay", timeout = 30s)
tap(id("plus"), count = 3)
Adds 3 to a quantity.
tap("Terms and privacy", offsetX = 120, offsetY = 0)
Offsets are pixels from the element's center.
Use it for maps and images that zoom, and for anything that opens on a double tap.
doubleTap(id("photo"))
Use it for context menus, drag handles and selection modes.
longPress("Invoice 42", duration = 2s)
tap("Delete")
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.
swipe(left)
swipe(down, from = id("sheet_handle"), duration = 600ms)
swipe(down, from = "Inbox")
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.
scroll
scroll(down, speed = slow, distance = 0.3)
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.
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.
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.
scrollTo(
id("row_1"),
direction = down,
from = id("orders_list"),
maxScrolls = 30,
timeout = 20s,
speed = slow,
)
scrollTo("Footer", duration = 400ms)
duration overrides speed. By default it tries 20 scrolls on Android and 10 on iOS.
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.
drag("Card A", to = text("Done").below("Board"))
drag(id("row_3"), to = id("row_1"), duration = 800ms, longPress = true)
drag(point(20%, 50%), to = point(80%, 50%))
Use it to zoom out on a map, a photo or a chart.
pinchIn
Limits On Android this needs the in-app SDK.
Use it to zoom in on a map, a photo or a chart.
pinchOut
assertVisible("Street view")
Limits On Android this needs the in-app SDK.
Input 7
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.
erase(5)
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.
clearText(id("email_input"))
assertVisible("Email is required")
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.
copyText(id("promo_code"))
tap("Enter code")
paste
Use it after copyText or setClipboard, to test paste handling.
In the app Pastes the clipboard into the field with focus.
setClipboard("SAVE10")
tap("Promo code")
paste
Use it to test screens that read the clipboard, such as "Paste your one-time code".
setClipboard("123456")
tap("Paste code")
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.
type("[email protected]", into = "Email")
type(@password, into = id("password"), hideKeyboard = true)
type("New name", into = "Full name", clearFirst = true)
The field is emptied first, so the old text is gone.
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.
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.
val before = numberOf(id("total"))
tap("Apply SAVE10")
val expected = before - 10
assertThat(numberOf(id("total")) == expected)
val orderId = textOf(id("order_id"))
tap("My orders")
assertVisible("Order $orderId")
val attempts = 1
attempts = attempts + 1
log("Attempt ${attempts}")
Without val, name = value sets it too. Names use letters, digits and _.
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.
When to use The check you use most: did we reach the right screen, did the message appear.
tap("Sign in")
assertVisible("Welcome back")
assertVisible(contains("items in your cart"))
assertVisible("Paid").below("Invoice 42")
Use it to confirm that something went away or was never shown: an error, a deleted row, a paywall.
tap("Delete")
assertNotVisible("Invoice 42")
Use it for checkboxes, switches and radio buttons that should be on.
tap("Remember me")
assertChecked(id("rememberMe"))
Use it for checkboxes, switches and radio buttons that should be off.
assertNotChecked(id("marketing_emails"))
Use it to check that a button turns on once a form is valid.
type("[email protected]", into = "Email")
assertEnabled(id("submit_btn"))
Use it to check that a button stays off until a form is complete.
assertDisabled(id("submit_btn"))
Use it to check that the cursor lands in the right field, such as search on open or the next field after an error.
tap(label("Search"))
assertFocused(id("search_field"))
Use it when one element's exact text matters, such as a total. assertVisible would pass on the same text anywhere on the screen.
assertText(id("price_label"), equals = "\$9.99")
Use it to check how many results, rows or items there are.
assertCount(id("cart_row"), 3)
assertCount(id("cart_row").visible(), count = 3)
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.
val before = numberOf(id("balance"))
tap("Send 100")
assertThat(numberOf(id("balance")) == before - 100)
val rate = numberOf(id("rate"))
assertThat(rate == 1.25, tolerance = 0.01)
Wait 6
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.
tap("Pay")
waitFor("Payment complete", timeout = 60s)
waitFor(contains("Welcome"))
Use it for spinners and progress bars, so the next step doesn't run too early.
tap("Refresh")
waitUntilGone(id("spinner"), timeout = 20s)
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.
wait(2s)
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.
tap("Open menu")
waitForAnimations(timeout = 5s)
screenshot("menu")
Use it when the app is still busy after a step and no element tells you when it's done.
waitForIdle(timeout = 10s)
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.
tap("Place order")
waitForValue(
@orderStatus,
equals = "Shipped",
timeout = 2m,
interval = 5s,
)
waitForValue(@lastEmailSubject, contains = "Your receipt")
Use equals or contains, not both. By default it reads every 3 s for up to 1 minute.
Device 13
Use it to test landscape layouts, and that state survives a rotation.
type("Ann", into = "Name")
setOrientation(landscape)
assertVisible("Ann")
setOrientation(portrait)
Limits On iOS this needs the XCUITest runner. The in-app SDK can't rotate the device.
Use it to test that text doesn't overflow or get cut off at large accessibility sizes.
setFontScale(1.5)
launchApp("com.shop.app")
assertVisible("Continue")
Limits Android only.
Use it to test contact pickers and address-book import without setting up a device by hand.
addContact(
"Test Contact",
phone = "555555555",
email = "[email protected]",
)
tap("Choose contact")
Limits Android and iOS simulators, not physical iPhones.
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.
deleteContacts("Test Contact")
Limits Android only. On an iOS simulator, erase the simulator to clear contacts.
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.
addMedia("fixtures/avatar.png")
tap("Change photo")
Limits On iOS, simulators only.
Use it to start with an empty shade, so that a notification check sees only the new one.
clearNotifications
Limits Android only.
Use it to test a push notification: see it, tap it, land on the right screen.
openNotifications
tap("Your order has shipped")
assertVisible("Order details")
Limits Android only.
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.
startRecording("checkout")
tap("Pay")
waitFor("Payment complete")
stopRecording
Use it to end a recording begun with startRecording.
startRecording
tap("Pay")
stopRecording
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.
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.
Limits Needs the in-app SDK driver. The step fails on the others.
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.
setPermissions(camera = false, location = true)
tap("Scan")
assertVisible("Camera access is off")
setPermissions(all = true, appId = "com.example.companion")
Use it for maps, delivery areas, and features limited to a country.
In the app Moves the device's reported GPS position.
setLocation(41.7151, 44.8271)
tap("Find stores near me")
assertVisible("Rustaveli Ave")
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.
setSystemProperty("isTestRun", "true")
setSystemProperty("env", "staging")
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.
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.
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.
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)
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.
val content = read("screens.log")
log("Screens so far: $content")
assertThat(content.contains("Home"))
if (read("settings.txt").contains("onboarded")) {
tap("Skip")
}
val cached = read("app.log", folder = cache)
val other = read("export.csv", folder = external, appId = "com.example.other")
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.
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.
file("screens.log").clear()
launchApp("com.example.app")
tap("Profile")
assertThat(read("screens.log").contains("Profile"))
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.
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.
file("config.json").write("{\"beta\": true}")
launchApp("com.example.app")
assertVisible("Beta features")
if (file("draft.txt").exists()) {
file("draft.txt").delete()
}
assertThat(file("draft.txt").exists() == false)
val day = "2026-02-10"
file("log-$day.txt").append("Started on $day")
file("app.log", folder = cache).clear()
file("data.db-wal", folder = data, appId = "com.example.other").delete()
file(regex("log-.*\\.txt")).delete()
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.
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.
file("app.log").write("in files")
file("app.log", folder = cache).write("in cache")
assertThat(read("app.log", folder = cache) == "in cache")
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.
pushFile("note.txt", content = "Hello from the test")
tap("Attach file")
pushFile(path = "fixtures/report.pdf")
pushFile("invoice.pdf", path = "fixtures/report.pdf")
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.
Limits On iOS, the file picker shows the folder only when the app sets UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace.
Device Actions 6
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.
resetPermissions(appId = "com.shop.app")
launchApp("com.shop.app")
assertVisible("Allow")
The app id can also be the plain argument: resetPermissions("com.shop.app").
Limits Android only.
Use it to test biometric login, both accepted and refused.
tap("Log in with fingerprint")
fingerprint
assertVisible("Welcome back")
fingerprint(match = false)
fingerprint(fingerId = 2)
Use it to test dark theme, or to take screenshots in both themes.
darkMode(true)
screenshot("home-dark")
darkMode(false)
screenshot("home-light")
Use it to test offline states and how the app recovers.
wifi(false)
tap("Refresh")
assertVisible("No connection")
wifi(true)
tap("Retry")
Limits Android only.
Use it to test having no network at all: no Wi-Fi and no mobile data.
airplaneMode(true)
tap("Sync")
assertVisible("You're offline")
airplaneMode(false)
Limits Android only.
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.
animations(false)
launchApp("com.shop.app")
Limits Android only.
Flow Control 13
Decide what runs, and repeat it.
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.
shell("settings put system screen_brightness 50")
shell("status_bar booted override --time 9:41")
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.
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.
use(@profile.staging)
type(@username, into = "Email")
@profile.staging.username reads a single key without switching.
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.
tap("Language")
tap("Español")
setLanguage("Spanish")
assertVisible(@langs.welcome)
setLanguage("ka", app = "Shop")
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.
dismissInterruptingDialogs(true)
tap("Checkout")
dismissInterruptingDialogs(false)
It carries into later units of the run until turned off.
Limits In-app SDK drivers only. UIAutomator and the XCUITest runner ignore it.
Use it to leave notes and values in the run log, which helps when reading a failure.
val total = numberOf(id("total"))
log("Total before discount: $total")
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.
if (platform == ios && visible("Allow")) {
tap("Allow")
} else if (visible("OK")) {
tap("OK")
} else {
log("No dialog")
}
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.
val balance = numberOf(id("balance"))
if (balance < 100) {
tap("Top up")
}
Use &&, || and parentheses to combine. ! isn't supported: use notVisible, != or an else.
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.
retry(times = 5) {
tap("Refresh")
assertVisible("Status: Shipped")
}
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.
forEach(regex("^Order #.*")) {
tap("${item.text}")
assertVisible("Order details")
back
}
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.
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.
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.
onComplete {
screenshot("end")
}
onError {
screenshot("failure")
}
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.
meta(
externalKey = "TC-1234",
tags = [smoke, login],
owner = "qa-team",
requirement = "PROJ-42",
severity = critical,
)
launchApp("com.shop.app")
Use it when each case needs its own steps. See if for a full example.
if (platform == ios) {
tap("Allow While Using App")
} else {
tap("While using the app")
}
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.
onError {
screenshot("failed-state")
tap("Log out", optional = true)
}
Values & Conditions 14
What goes inside val, if, skipIf, assertThat and type.
Use it with val to keep a text exactly as shown.
val name = textOf(id("profile_name"))
log("Logged in as $name")
The step waits for the element, and fails if it never appears.
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.
assertVisible(date("dd/MM/yyyy"))
type(date("dd/MM/yyyy"), into = "Date")
tap(contains(date("yyyy")))
val today = date("dd/MM/yyyy")
assertVisible("Paid on $today")
val today = date("yyyy-MM-dd")
assertThat(read("logs/$today.log").contains("My Screen"))
assertThat(read(date("yyyy-MM-dd'.txt'")).contains("My Screen"))
val stamp = date("yyyy-MM-dd HH:mm:ss")
log("Started at $stamp")
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").
val day = day()
val month = month()
val year = year()
log("It is day $day of month $month in $year")
if (day() == 1) {
assertVisible("New statement")
}
assertThat(year() >= 2026)
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.
val balance = numberOf(id("balance"))
assertThat(numberOf(id("balance_after")) == balance - 100)
Use it for sign-ups that reject an address they've already seen.
type(randomEmail("example.com"))
type(randomEmail())
Use it for numeric fields: phone numbers, references.
type(randomNumber())
type(randomNumber(9))
Use it for names of things that must be unique, or to fill a field to a length.
type(randomText())
type(randomText(200))
Use it for name fields.
tap("Full name")
type(randomName())
Use it in if and skipIf for steps that differ by platform.
if (platform == ios) {
tap("Allow")
}
Only == works here: platform != ios fails the parse. Use else, or platform == android.
Use it in if and skipIf. For a chained filter on a selector, see .visible.
if (visible("Allow") && platform == ios) {
tap("Allow")
}
if (visible(id("promo"), timeout = 2s)) {
tap(id("promo_close"))
}
Use it in if and skipIf to do something only when an element is absent.
if (notVisible("Log out")) {
tap("Log in")
}
Use it to act on a permission's current state.
if (permission(camera) == denied) {
tap("Enable camera")
}
Limits Android only. iOS can't report a permission's state, so the condition never holds there.
When to use Options such as permissions, arguments, environment and appAction's args take one.
launchApp(
"com.shop.app",
arguments = args(mode = "demo", "ds.mutation" = "off"),
)
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.
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.