Skip to main content

​
Overview

Spur controls emulators and simulators and interacts with mobile applications the same way a human tester would. The agent sees what is on screen and performs actions — taps, types, scrolls, and waits — based on your instructions. You can also provide high-level instructions and let the agent determine the appropriate interactions. To author a mobile test, provide a clear test name, a description, and the individual steps required to achieve the goal.
Write each step as though you are instructing a colleague who is holding the phone.
  • Use plain English
  • Do not include code, selectors (IDs, XPath), or coordinates

​
Step Formatting Standards

Follow this structure for every test:
  1. Write one or more sentences per step to describe a single logical action.
  2. Combine related actions on the same screen into one step when they read naturally together.
Combining actions on the same screen into fewer steps can improve both speed and reliability.

​
Intent Words: Verify vs Check/Validate

Spur interprets these keywords differently:

Verify

Use when you need to confirm something that is already visible on screen.This should not require additional interaction.

Check / Validate

Use when Spur may need to perform a small interaction before confirming.
Examples
  • Verify that "Welcome back" is displayed
  • Verify that the user is logged in
  • Check that the cart shows "1" item (may need to open the cart)

​
Identifying Elements

Use visible cues so the agent can reliably locate the correct target.
Instead of thisWrite this
Click element with resource-id “login_btn”Tap the Log in button
Tap button at coordinates (350, 680)Tap the shopping bag icon with a plus, in the bottom right of the product card
Assert element “welcome_text” is displayedVerify that “Welcome back” is displayed
  • Text + position: “Tap Settings in the top right.”
  • Icon + position: “Tap the gear icon in the top right.”
  • Disambiguation: “Tap the first product in the list.”

​
Supported Actions

​
Tap / Click

Tap and Click are interchangeable in Spur.
  • Tap Sign In
  • Tap the back arrow in the top left
  • Tap the first product in the list

​
Tap and Hold (Long Press)

Use when you need to trigger a context menu, drag handle, or secondary action.
  • Long press the profile photo to open the context menu
  • Tap and hold the message bubble until the actions menu appears

​
Type (Text and Numeric Entry)

Where possible, combine credential entry into a single instruction.
  • Enter "user@example.com" as email and "MyPassword!" as password and tap Continue
  • Type "KALLAX" into the search bar
  • Enter 10038 as the zipcode and tap Done
iOS: Avoid writing “tap the field, then type”. Instead, write “enter the email” or “enter the password” directly. Spur handles field focus automatically.

​
Scroll / Swipe

The most reliable approach is to scroll until a specific element is visible.
  • Scroll down until the "Add" button is visible, then tap it
  • Scroll down until "Instructions" is visible, then tap it
Direction reminders
  • Swipe up → reveals content below (scrolls down)
  • Swipe left → reveals content to the right
Fine control (optional)
  • Scroll down (moderately) until the dropdown is visible

​
Swipe Distance Specification

​
Distance Formats

You can specify swipe distance in four ways:
  • Position-based — bottom, top, middle
  • Percentage — 30%, 50%, 60%
  • Pixels — 100, 200, 300
  • Intensity keywords — conservative, moderate, aggressive

​
Swipe Context

When you specify a target element, the swipe is performed within that element’s bounds. When no element is specified, Spur performs a full-screen swipe.

​
Intensity Keywords

With an element (swipe within element bounds)
LevelStart → EndDistance
Conservative70% → 30%40% of element height
Moderate80% → 20%60% of element height
Aggressive85% → 15%70% of element height
Without an element (full-screen swipe)
LevelStart → EndDistance
Conservative70% → 30%40% of screen height
Moderate80% → 20%60% of screen height
Aggressive85% → 15%70% of screen height

​
Wait

Three patterns that work well:
  • Wait for the app to load
  • Wait 2 seconds
  • Tap "Start session" and wait for the main screen to be displayed
Prefer condition-based waits over fixed durations. Writing “do X and wait for Y to be displayed” is more robust than “wait N seconds”.

​
Conditional Steps

Mobile applications frequently display popups, permission dialogs, and optional UI. Use the following branching pattern to handle them: Required format 
If <condition> is displayed, do <action>. Otherwise, skip this step.
Examples
  • If "Join our email list" is displayed, tap "No, thank you". Otherwise, skip this step.
  • If "Turn On Bluetooth" is displayed, tap "Not now". Otherwise, skip this step.
Google Password Manager and Chrome notifications are typically dismissed automatically by Spur.
Include the following steps at the top of most mobile tests to establish a consistent starting state: 
Wait for the app to load
If already logged in, skip this step. Otherwise, enter "user@email.com" as email and "Password1" as password and tap Continue
Verify that the user is signed in
When a step begins with the keyword navigate, Spur applies an additional transition wait (controlled by navigate_segment_transition_delay). This ensures that screenshots are captured after the screen transition completes. Example
  • navigate to the Settings screen and wait for "Settings" to be displayed

​
Known Limitations

Be aware of the following constraints when authoring mobile tests:
  • Pinch / zoom gestures are not supported.
  • Infinite scroll without a stopping condition can cause endless scrolling. Always include a visibility condition (e.g., “scroll until <element> is visible”).
  • Heavy animations can cause timing issues. Add a wait-for-visible condition after the animation completes.
  • Hybrid WebView screens can be harder for the agent to detect. If taps repeatedly fail, rewrite the element description to include additional visual cues.

​
Quick Reference

Copy-and-paste templates for common mobile testing flows.

​
Login and Dismiss Popup

Wait for the app to load
If "Join our email list" is displayed, tap "No, thank you". Otherwise, skip this step.
If already logged in, skip this step. Otherwise, enter "user@example.com" as email and "Password1!" as password and tap Continue
Verify that "Home" is displayed

​
Search and Add to Cart

Wait for the app to load
Type "KALLAX" into the search bar
Tap the first result
Tap "Add to cart" and wait for "Added" to be displayed
Verify that the cart icon shows "1" item

​
Next Steps