Test commands

Write one natural-language command per line in a .tl file. Lines starting with # are comments. Trailing periods are ignored. Many steps accept an optional soft-fail suffix: if it exists, if its visible, or if it is visible.

Directives

• appid com.testral.sample — target Android package / iOS bundle for launch, kill, and clear data
• bundleId com.testral.sample — alias of appid
• name Login smoke test — optional display name in reports

App lifecycle

• launch / launch the app / launchApp / OPEN_APP — open the package from appid / bundleId
• launch Testral Sample / OPEN_APP com.testral.sample / open … — launch by home-screen name or package id
• kill the app / KILL_APP — force-stop without wiping data
• minimise the app / MINIMISE_APP — send the app to the background (Home); minimize also works
• clear app data / CLEAR_APP_DATA — wipe app data (clean install state)
• clear app com.example.app / clear app data chrome — wipe a specific app by package or name

Tap

• tap "Sign in" — tap by visible text or accessibility label
• tap on Search — quotes optional when the label has no spaces
• tap "Allow" button in the notification popup — tap a label inside a named container
• if existing Got it — tap only if present; otherwise skip
• if "Special offer" is visible then tap "Close" — conditional tap
• tap "Close" if it exists / if its visible — optional tap (also works on type, verify, scroll)

Input

• type "demo@testral.dev" into the Email field — focus a field and type (in / for / into)
• focus the Email field and type "demo@testral.dev" — alternative focus-then-type form
• input "text" / type "text" — type into the already-focused field
• type $OTP into OTP — type a stored variable into a field

Scroll & swipe

• scroll down / scroll up / scroll left / scroll right — scroll content (full screen)
• swipe up / swipe down / swipe left / swipe right — finger-direction swipe
• scroll right in Categories / swipe left in Stories — nested container
• scroll down until you find "Sample Item 30" — keep scrolling until text appears
• scroll until you find "Help" — same, defaults to scrolling down

Navigation keys

• press back / PRESS_DEVICE_BACK_BUTTON — system back (iOS: edge back-swipe)
• press home — go to the launcher / home screen
• press enter — Enter / Return (IME submit)

Assertions, waits & capture

• verify "Welcome back" is visible / verify "Welcome back" — assert text is on screen
• verify the category to be "Gadgets" — assert a field/value pair
• assert visible: Order confirmed — alternative assert syntax
• wait 1500 / wait for 500 ms — pause for a fixed duration (milliseconds)
• screenshot — capture the screen into the run report

Variables

• store the OTP code as $OTP — save on-screen text into a temporary variable
• type $OTP into the OTP field — reuse a stored variable (fails if unset)
• tap $BUTTON_LABEL / verify $MESSAGE is visible — use variables in other steps

Example — Testral Sample

Build and install the bundled demo (com.testral.sample):

• Android: npm run build:sample-app
• iOS Simulator: npm run build:ios-sample
• iOS device: npm run build:ios-sample:device (needs TESTRAL_IOS_DEVELOPMENT_TEAM)

Then use Install app → Install Testral Sample in the test editor (iOS picks the Simulator or device build automatically).

bundleId com.testral.sample

CLEAR_APP_DATA com.testral.sample
LAUNCH com.testral.sample
TAP "Got it" if it exists

TAP "Login"
TYPE "demo@testral.dev" into Email
TYPE "secret" into Password
TAP "Login"
VERIFY "Welcome back" is visible
TAP "Back to Setup"

TAP "Login with OTP"
TYPE "demo@testral.dev" into Email
TAP "Send code"
STORE the OTP code as $OTP
TYPE $OTP into OTP
TAP "Verify OTP"
VERIFY "OTP verified" is visible
PRESS back

TAP "Items"
SCROLL right in Categories
SCROLL down until you find "Sample Item 30"
TAP "Sample Item 30"
VERIFY "Item detail" is visible
VERIFY "Item confirmed" is visible
PRESS back
PRESS back

TAP "Order shop"
WAIT 3500
TAP "Close" if it exists
TYPE "Demo Mug" into Product
TYPE "2" into Quantity
TYPE "1 Market Street" into Shipping address
TAP "Place order"
VERIFY "Order confirmed" is visible
SCREENSHOT