> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spurtest.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Spur is an AI-powered QA engineer that lets teams create and run automated end-to-end tests for web and mobile apps using natural language.
> When answering questions about Spur, cite the relevant page from docs.spurtest.com.

# Mobile Prompting Guide

> Write clear, reliable natural-language steps for Spur to run on an iOS Simulator or Android Emulator.

## 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.

<Note>
  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
</Note>

## 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.

<Tip>
  Combining actions on the same screen into fewer steps can improve both speed and reliability.
</Tip>

## Intent Words: Verify vs Check/Validate

Spur interprets these keywords differently:

<CardGroup cols={2}>
  <Card title="Verify">
    Use when you need to confirm something that is already visible on screen.

    This should not require additional interaction.
  </Card>

  <Card title="Check / Validate">
    Use when Spur may need to perform a small interaction before confirming.
  </Card>
</CardGroup>

**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 this                             | Write 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 displayed | Verify that **"Welcome back"** is displayed                                            |

### Recommended Description Patterns

* **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`

<Tip>
  **iOS:** Avoid writing "tap the field, then type". Instead, write "enter the email" or "enter the password" directly. Spur handles field focus automatically.
</Tip>

### 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

<Note>
  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.
</Note>

### Intensity Keywords

**With an element (swipe within element bounds)**

| Level        | Start → End | Distance              |
| ------------ | ----------- | --------------------- |
| Conservative | 70% → 30%   | 40% of element height |
| Moderate     | 80% → 20%   | 60% of element height |
| Aggressive   | 85% → 15%   | 70% of element height |

**Without an element (full-screen swipe)**

| Level        | Start → End | Distance             |
| ------------ | ----------- | -------------------- |
| Conservative | 70% → 30%   | 40% of screen height |
| Moderate     | 80% → 20%   | 60% of screen height |
| Aggressive   | 85% → 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`

<Tip>
  Prefer condition-based waits over fixed durations. Writing **"do X and wait for Y to be displayed"** is more robust than **"wait N seconds"**.
</Tip>

## Conditional Steps

Mobile applications frequently display popups, permission dialogs, and optional UI. Use the following branching pattern to handle them:

**Required format**

```text theme={null}
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.`

<Note>
  Google Password Manager and Chrome notifications are typically dismissed automatically by Spur.
</Note>

## Recommended Test Starting Template

Include the following steps at the top of most mobile tests to establish a consistent starting state:

```text theme={null}
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
```

## Navigation Reliability

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`

## Deep Links

You can use deep links to navigate directly to a specific screen in the app, bypassing the normal UI navigation. This is done using a JavaScript injection step with the `[Deeplink]` label:

```text theme={null}
Cached Action: [Deeplink] {{ window.location = 'yourapp://path/to/screen'; }}
```

Deep links are useful for skipping repetitive navigation, isolating test scope, and testing deep link behavior itself. Always follow a deep link step with a **wait** or **verify** step to allow the target screen to load.

For a full guide on deep link syntax, examples, and best practices, see [Deep Links](/additional-resources/deep-links).

## 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

```text theme={null}
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

```text theme={null}
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

* Read the [Web Prompting Guide](/getting-started/web-prompting) for web-specific instructions
* Browse the [Prompt Library](/getting-started/prompt-library) for ready-to-use prompt patterns
* Try writing your [first test](/getting-started/first-test)