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

# Flows

> Write E2E tests in natural language

Flows are the heart of BugRadar. A **flow** is a test written in natural language that describes what you want your agent to do in your app or website.

[Flows](https://www.veed.io/embed/b5b5b186-193e-4c4c-b246-c35dcfbb5ae8?watermark=0\&color=default\&sharing=0\&title=1)

## What is a Flow?

A flow is a set of instructions that the agent follows to interact with your app or website. Instead of writing code or recording clicks, you simply describe what you want to test in natural language.

**Example Flow:**

```
Search for "wireless mouse".
Open the top result.
Add it to the cart.
Open the cart.
Verify the cart contains the wireless mouse.
```

The agent interprets these instructions, finds the relevant UI elements, and executes a series of actions, verifying results at each step.

## Creating a Flow

### Method 1: Quick Create

1. Navigate to the **[Flows](https://usebugradar.com/flows)** page
2. Click **Create Flow**
3. Enter a flow name (required)
4. Write your instructions in natural language
5. Click **Create Flow**

### Method 2: Create in Suite

Create a flow directly within a suite:

1. Navigate to the **[Flows](https://usebugradar.com/flows)** page
2. Expand a suite
3. Click **Create Flow** within the suite
4. Follow the same steps as Quick Create
5. The flow is automatically added to the suite

### Method 3: Define in Your Repo

Keep flows in version control and sync them from your repository — see [Code-Managed Flows](/docs/code-managed-flows.md).

## Writing Effective Flow Instructions

Use **Save all** in the flow editor to save your edited flows and suites. Saving also refreshes unchanged flows and suites. Changes you make while a save is in progress remain unsaved until you save again.

See [Writing Effective Flow Instructions](/docs/writing-effective-flow-instructions.md)
for guidance and examples.

## Supported Agent Actions

**Universal Actions** (work on both mobile and web):

| Action | Example Instruction |
| - | - |
| **Enter Text** | "Enter 'Joe Banana' in the name field" |
| **Clear** | "Clear the text from the email field" |
| **Verify** | "Verify that 'Welcome back!' appears on screen" |
| **Wait** | "Wait for the loading indicator to disappear" |
| **Drag and Drop** | "Drag the yellow card to the 'Drop here' area" |
| **Long Press** | "Long press on the 'Share' button" |
| **Find on Page** | "Find 'Billing' on the page" *(jumps to the first match — Cmd/Ctrl+F on web, native scroll-into-view on mobile — much faster than swiping/scrolling)* |
| **Run Hook** | "Run `${hooks:Generate Test Order}`. Then search for the returned order number" |
| **Set Variable** | "Save the displayed order number as a variable called order\_id" |
| **Get Variable** | "Get the variable order\_id and enter it in the confirmation field" |
| **Set Clipboard** | "Set the clipboard to 'PROMO2024', then tap Paste in the coupon field" *(not supported on physical iOS devices or Firefox/WebKit)* |
| **Read Clipboard** | "Copy the invite link, then read the clipboard and verify it contains /invite/" *(not supported on Firefox/WebKit)* |
| **Set Appearance Mode** | "Switch to dark mode and verify the header is readable" *(light or dark; the app keeps running, and the change is undone when the flow ends, or when the suite ends if the flow runs in a suite)* |
| **Check Email Inbox** | "Check the email inbox for the verification code and enter it" *(requires the Lease email address setup hook — see [OTP Testing](/docs/guides-otp-testing.md))* |
| **Check SMS Inbox** | "Check the SMS inbox for the login code and enter it" *(requires the Lease phone number setup hook — see [OTP Testing](/docs/guides-otp-testing.md))* |

**Mobile-Only Actions**:

| Action | Example Instruction |
| - | - |
| **Tap** | "Tap the login button" |
| **Swipe** | "Swipe right on the slider" |
| **Pinch** | "Pinch to zoom in on the map until San Francisco takes up the entire screen" |
| **Hide Keyboard** | "Hide the keyboard" |
| **Press Home** | "Press the home button, then reopen the app and verify the draft is still there" *(app stays in memory)* |
| **Terminate App** | "Terminate the app" *(kills the process; follow with Reopen App for a cold launch)* |
| **Reopen App** | "Reopen the app and verify the user is still logged in" |
| **Open Deeplink** | "Open the deeplink 'myapp\://profile/123'" |
| **Open App Clip** | "Open the App Clip at [https://example.com/e/abc123](https://example.com/e/abc123)" *(iOS cloud simulators only — see [Testing App Clips](/docs/guides-app-clips.md))* |
| **Install Full App** | "Install the full app" *(iOS cloud simulators only; after an App Clip step — see [Testing App Clips](/docs/guides-app-clips.md))* |
| **Change Location** | "Change location to longitude -122.4194, latitude 37.7749" *(suite-scoped: persists across all flows in the suite* |
| **Set Device Locale** | "Set the device locale to de\_DE, then verify German pricing is shown" *(changes the device's language & region setting; the app restarts to pick it up; persists until changed. To start the whole run in a language, use [Language & region](/docs/language-and-region.md))* |
| **Set Orientation** | "Flip the device to landscape" or "Rotate back to portrait" |
| **Toggle Airplane Mode** | "Turn airplane mode on" (Android only) |
| **Set Network Condition** | "Simulate a slow 3G network, then restore full speed" — presets: full, offline, gprs, edge, slow\_3g, fast\_3g, lte (Android only) |
| **Set Biometric Enrollment** | "Enroll Face ID, then open the app" *(enrolled or not enrolled; iOS simulators only; undone when the flow ends, or when the suite ends if the flow runs in a suite)* |
| **Match Biometric** | "When the Face ID prompt appears, provide a matching face" or "...a non-matching face" *(works for Face ID and Touch ID; enroll first; iOS simulators only)* |
| **Run Appium Script** | `run_appium_script {"command": "mobile: deviceInfo"}` *(for device capabilities no other action covers)* |

**Web-Only Actions**:

| Action | Example Instruction |
| - | - |
| **Click** | "Click the login button" |
| **Scroll** | "Scroll down until the settings option appears" |
| **Hover** | "Hover over the dropdown menu" |
| **Right Click** | "Right-click on the image" |
| **Double Click** | "Double-click to edit the text" |
| **Upload File** | "Upload photo.jpg using the profile picture button" |
| **Navigate** | "Navigate to [https://example.com/settings](https://example.com/settings)" |
| **Refresh** | "Refresh the page" |
| **Go Back** | "Go back to the previous page" |
| **Go Forward** | "Go forward to the next page" |
| **Hotkey** | "Press Control+c to copy the text" |
| **Run JS** | "Run JS: `document.querySelectorAll('script').length` and verify at least 3 scripts are loaded" |
| **Run Playwright Command** | `run_playwright_command {"target":"page","command":"emulate_media","args":{"reduced_motion":"reduce"}}` |
| **Read Console Logs** | "Read the browser console logs and verify there are no errors" |
| **Read Network Logs** | "Read the network logs and verify the POST to /api/login returned 200" |
| **Read Cookies** | "Read the browser cookies and verify a session cookie exists" |
| **Set Network Condition** | "Throttle the network to slow 3G, then restore full speed" — presets: full, offline, gprs, edge, slow\_3g, fast\_3g, lte (Chromium-family browsers) |
| **Close Extension** | "Close the extension popup and return to the website" *(only when the run loads a [Chrome extension](/docs/web-testing.md#testing-with-chrome-extensions))* |

## Running Flows

### Running a Single Flow

1. Find your flow in the Flows table
2. Click the **Play** button (▶️)
3. Select your app. Type to search by app or environment name. If your apps
   are in more than one environment, the list groups them by environment and
   shows the chosen app's environment
4. For a mobile app, choose a simulator or emulator model and OS version, or
   select a real device
5. Click **Run Flow**

Virtual-device runs default to the latest supported permutation. **Fast launch**
choices usually start sooner; every listed permutation is supported.

To test across two devices, edit the flow, open **Advanced**, and set **Number
of devices** to **2**. Choose both devices when you run it. See
[Multi-Device Testing](/docs/multi-device-testing.md) for details.

### Running Multiple Flows

Select multiple flows using checkboxes:

1. Check the boxes next to flows you want to run
2. Click **Run** in the floating action bar
3. Select your app
4. Click **Run Flows**

A bulk run can mix one-device and two-device flows. If any selected flow uses
two devices, choose **Device 1** and **Device 2**; one-device flows run on
Device 1.

> [!TIP]
>
> **Shift-Click Selection**: Hold Shift and click to select a range of flows
> quickly

### Running a Folder

Run everything in a [folder](#organizing-tests-with-folders) at once:

1. Check the box next to the folder and click **Run** in the floating action
   bar, or click the three dots (**⋯**) next to the folder and select **Run**
2. Select your app
3. Click **Run**

Checking a folder selects it as one unit: you don't check the tests inside it.
You can check other flows and suites alongside it.

To run a folder from the [API](/docs/api-runs.md), copy its ID from the folder's **⋯**
menu (**Copy folder ID**).

What runs:

* Every suite and flow beneath the folder, in its subfolders at any depth.
* Each suite runs in full, including flows it holds that are filed in other folders.
* A flow that belongs to a suite runs only as part of that suite. If the suite
  is outside this folder, running this folder skips the flow.
* A flow that isn't in any suite runs on its own.
* Each flow runs at its active version. In a [branch run](#running-a-folder-on-a-branch),
  tests stored in your repo run as they are on that branch, except inside a
  suite made in the dashboard, where they run at your default branch's version.

A notification confirms the run and links to its results. If some tests
couldn't start, it says how many. The results are named after the folder.
They show the folder's subfolders and suites, each with a combined status, and
the flows directly in it. The results keep the folder as it was when the run
started, even if you move tests or folders later.

On the **Runs** page, a batch with more than one run groups its flows and
suites by folder, in the same order as the Flows page. Folders start closed and
show how many tests passed, failed, are running, or are queued, and say
**Installing app** while a test's app installs. Check the box
next to a folder to select every run in it.

#### Running a Folder on a Branch

A folder from your [repo](/docs/code-managed-flows.md) can run on a branch. Pick the
branch in the run dialog. The run takes the folder's tests from that branch,
plus any tests made in the dashboard and placed in the folder.

### Auto-Retries

BugRadar can automatically re-run a failed flow before reporting it as failed. Configure this in **[Settings → Agent](https://usebugradar.com/settings?tab=agent)**.

* **Retries**: Set how many times a failed run is retried (0–5, default 1). A flow is only marked failed after all attempts are exhausted — if any attempt passes, the flow is reported as passed.
* **Intelligent Retries**: On by default. Retries are focused on flows with a track record of passing; flows that are consistently failing aren't retried. Turn it off to retry every failure.

## Managing Flows

### Editing a Flow

1. Click the pencil icon (✏️) next to a flow or click on the flow row
2. Modify the name or instructions
3. Click **Save Changes**

### Viewing Version History

Flows maintain a complete version history:

1. Click **Edit** on a flow
2. Click the **Version History** tab
3. View all previous versions with timestamps
4. Click **Revert** to restore a previous version

### Duplicating a Flow

To create a copy of an existing flow:

1. Click the three dots (**⋯**) next to a flow
2. Select **Duplicate**
3. A copy is created with "(Copy)" appended to the name
4. Edit the duplicate as needed

### Deleting a Flow

1. Click the three dots (**⋯**) next to a flow
2. Select **Delete**
3. Confirm deletion

### Snoozing a Test

Snooze a test to stop it running with the rest of your tests, for example while a known bug is being fixed, without deleting it.

Click the three dots (**⋯**) next to the test and select **Snooze**. Select **Unsnooze** to bring it back. Snoozing adds the built-in `snoozed` label, so you can also add or remove that label like any other. Every workspace has this label. **[Settings → Labels](https://usebugradar.com/settings?tab=labels)** marks it **Built in**. It can't be renamed or deleted.

A snoozed test is skipped by every run that picks tests as a group: suites, folders, labels, [automations](/docs/automations.md), branch and commit runs, and BugRadar's pull-request test runs. This holds for runs from the dashboard, the [API](/docs/api-runs.md), MCP, the CLI, and the [GitHub Action](/docs/ci-cd-integration.md#snoozed-tests). `snoozed` wins over other labels: a test labeled both `regression` and `snoozed` is skipped in a `regression` run.

* A run that names exactly one test, and no suite, folder, or label, still runs it. Use this to check a snoozed test on its own. Automations always skip it, even one that runs only that test.
* When every other test in a suite is snoozed, the suite's setup test is skipped too.
* Adding `snoozed` to a suite does nothing special. Snooze the suite's tests instead.

Skipped tests show as **Snoozed** in the run results and count as neither passed nor failed. A run where every selected test is snoozed passes and reads **0 ran, all N snoozed**.

To snooze a [code-managed](/docs/code-managed-flows.md) test from your repo, add `snoozed` to its `labels`. See [Labels](/docs/code-managed-files.md#labels).

## Organizing Flows with Suites

Suites help you organize related flows and run them together.

### Adding a Flow to Suites

**Method 1: During Creation**

* When creating a flow, select which suites it should belong to

**Method 2: After Creation**

1. Click the three dots (**⋯**) next to a flow
2. Select **Attach to Suite**
3. Check the suites you want to add the flow to
4. Click **Save**

**Method 3: From Suite View**

1. Expand a suite
2. Click **Add Existing Flows**
3. Select flows to add
4. Click **Add Flows**

### Removing a Flow from a Suite

1. Expand the suite containing the flow
2. Click the three dots (**⋯**) next to the flow
3. Select **Remove from Suite**
4. Confirm removal

## Organizing Tests with Folders

Folders sort your flows and suites on the **[Flows](https://usebugradar.com/flows)** page, for example by feature area, then sub-area, then the variants under test. A folder holds flows, suites, and other folders, nested as deep as you like. Folders change where a test is listed, not how it runs. You can also [run a whole folder](#running-a-folder).

Each flow and suite sits in one folder, or at the top level. To put a flow in several groups, add it to several suites. A suite in a folder can include flows from other folders. A flow that a suite includes shows under that suite only, not again in its own folder.

The **All flows** view shows top-level folders and suites first, then your [sections](#grouping-tests-into-sections), then the **Standalone flows** and **Auth flows** sections. Click a folder to expand it. In the **All flows** and **Suites** views, click a suite to list its auth flow and flows underneath. The **Flows** and **Labels** views stay flat.

Within each folder and section, the folders and tests you made come first: folders, then suites, then flows, each by name. Folders and tests from your repo come after them, sorted the same way. Once you drag something within a folder or section, everything in it keeps the order you set, and new tests land at the end. Inside a repo folder, the folders from your repo stay first, by name.

### Creating a Folder

* Click **New** → **New folder** to create a top-level folder.
* To create something inside a folder, click the three dots (**⋯**) next to it and select **New folder**, **New flow**, or **New suite**.
* The editor's sidebar lists your folders and suites together, in the same order as on the Flows page. Click **New** next to **Suites & folders** to add a folder or suite, or use a folder's **⋯** menu to add a folder, flow or suite inside it, or to rename it.

Type the folder's name, then press Enter or click away to save. Press Esc to cancel. Folder names must be unique within their parent folder.

### Renaming a Folder

1. Click the three dots (**⋯**) next to the folder
2. Select **Rename**
3. Edit the name, then press Enter

### Moving Tests and Folders

* Drag a flow, suite, or folder to where you want it. A blue line shows where it will land: between two rows, or inside a folder. Hold it over a closed folder to open it. At the top level, flows reorder within their own section and can't move above folders and suites; drop a flow inside a folder to file it there.
* Or click the three dots (**⋯**) next to it, select **Move to…**, and choose a folder or **Top level**. Click **New folder** in that dialog to move into a folder you create on the spot.

To move several at once, check them and click **Move to…** in the selection bar. A folder can't move into itself or into a folder inside it.

Flows and suites from your repo move the same way, into any folder or section. Folders from your repo can only go into a section.

### Deleting a Folder

1. Click the three dots (**⋯**) next to the folder
2. Select **Delete**
3. Confirm deletion

Deleting a folder also deletes everything in it: its subfolders and every flow and suite inside them. Flows and suites from your repo aren't deleted: they move to the top level. The confirmation says how many tests will be deleted, and names any suites in other folders that will lose flows. If a flow in the folder is the login step of a suite outside it, change that suite's login step first.

To bring a deleted folder back, click **Undo** in the message that appears after deleting. Everything returns where it was. Undo isn't available once that message closes, and it fails if a folder with the same name now sits in the same place.

### Grouping Tests into Sections

A section is a heading on the **All flows** view, such as **Release** or **One-off**, that groups top-level folders, suites, and flows. Sections are always open. They change where a test is listed, not how it runs. To run a group of tests from CI or the API, use [labels](/docs/api-labels.md#run-by-label).

* **Add a section:** click **+ Add section** above **Standalone flows** (hidden while a search or filter is on), or click **New section** in the **Move to…** dialog to create one and pick it.
* **Fill a section:** drag a folder, suite, or flow onto the section's heading or between its rows. Or select **Move to…** and choose the section. Moving an item into a folder takes it out of its section.
* **Run a section:** open the **⋯** menu on its heading and select **Select all**, then click **Run** in the floating action bar.
* **Rename or delete a section:** click the three dots (**⋯**) next to its heading. Deleting a section moves its items back to the top; click **Undo** in the message that appears to bring it back. Undo fails if another section now has the same name.

The editor's sidebar shows the same sections and can do all of this except **Select all**. In the details panel, click **Change** next to **Folder** to move a flow or suite into a section.

Folders, suites, and flows from your repo can go in sections too. A test stays in its section when you move it in the repo, as long as a flow keeps its file name, a suite keeps its folder name, and it stays at the top level. A renamed repo folder, flow file, or suite folder comes back outside its section. Auth flows always stay under **Auth flows** and can't go into a section.

### Code-Managed Tests

The top folder from a [code-managed](/docs/code-managed-flows.md) repo shows the repo's name; the folders inside it don't repeat it. Repo folders can't be renamed, deleted, or moved into folders from the dashboard, but a top-level repo folder can go into a section. You can put flows, suites, and folders made in the dashboard inside repo folders.

Code-managed flows and suites start in their directory's folder (see [Folders](/docs/code-managed-files.md#folders)). Drag them or use **Move to…** to reorder them or put them in any folder or section. A push moves a test only when its file moves in the repo. To see each test where its file is, select **Show repo file structure**, the folder tree button at the start of the toolbar above the list. Dragging is off in that view.

## Flow Status and Results

### Status Types

| Status | Meaning |
| - | - |
| **Pending** | Flow hasn't been run yet |
| **Running** | Flow is currently executing |
| **Passed** | Flow completed successfully |
| **Failed** | Flow encountered an error |
| **Snoozed** | Flow is [snoozed](#snoozing-a-test), so group runs skip it |

### Viewing Results

Cache attempts that stop before sending an action to the device are hidden from the normal step list. They remain available in debug mode. Actual execution failures remain visible.

Click on any status badge to view detailed results:

* **Screenshots**: Visual snapshots at each step
* **Action Log**: Every action performed by the agent
* **Console and Hook Output**: Long output starts as a truncated preview. Select **Show more** to expand it, **Show less** to return to the preview, or the output heading to collapse or reopen it.
* **Errors**: Any issues encountered
* **Timeline**: Duration of each step
* **Device Info**: Device type and OS version used

### Sharing a Run Batch

On the **Runs** page, select the link icon beside a batch's eye icon or inside its results to share the entire batch.

## Advanced Features

### Attaching Files

[Adding Images to Flows](https://www.veed.io/embed/a7625008-f873-4c2f-a7e4-7ef781025d42?watermark=0\&color=\&sharing=0\&title=1)

Add reusable files to your flow instructions:

1. Open a flow's Advanced options and add a file in the Files section.
2. Click the + beside a file to insert its `${file:filename.xyz}` reference in the instructions. You can also type the reference yourself.
3. Files marked **Used in this flow** are prepared when that flow runs. Dimmed **Available** files are saved for reuse but are not prepared for that flow. Open a file's three-dot menu to delete it from the shared library.

Sequential suite flows share a device session, so a file prepared by an earlier flow may still be present for a later flow. Reference the file in each flow that needs it so that flow prepares it explicitly. Parallel suite flows use separate sessions.

### Using Hooks

[Adding Hooks to Flows](https://www.veed.io/embed/720a1987-f583-42c1-99df-1dd04b9f13d7?watermark=0\&color=default\&sharing=0\&title=1)

Hooks are reusable scripts that run before or after your flow:

**Setup Hooks**: Run before the flow (e.g., "Clear app data and restart")
**Teardown Hooks**: Run after the flow (e.g., "Logout and clear cache")

1. Click **Edit** on a flow
2. Click **Add Hook**
3. Select **Setup** or **Teardown**
4. Write the hook instructions
5. Save the flow

You can read more about hooks [here](/docs/hooks.md).

### Run Caching

When enabled, flows that have previously passed will use cached action sequences for faster execution (5-8x speedup). Run caching is best-effort and enabled by default.

Cached actions cost 90% less than uncached actions (10% of the cost).

On a run’s Details tab, **Action breakdown** shows the recorded cache setting and the run’s **Cost** in actions. Each AI action costs 1 action and each cached action 0.1. Select the cost to see AI actions, State cache, and Semantic cache counts added up; keyboard users can focus the cost and press Enter. If the run did not record its setting, it shows **Not recorded**.

The **Cache rate** tile on [Overview](https://usebugradar.com/overview) shows cached actions as a percentage of all actions. It follows the selected date range, app, and workspace scope. Partially cached runs contribute their cached and uncached actions separately. The percentage uses action counts, not billing; periods with no actions show an empty value.

To see the cache rate day by day, open the **Usage & billing** chart on Overview and select **% of actions**. It covers the selected billing cycle across your whole company, not the tile's date range, app, or workspace filters. Each day's actions are split into AI and cached actions. Days with no actions are left empty.

**How it works:**

* After a flow passes successfully, the action sequence is cached
* Subsequent runs replay the cached actions with a smaller, faster model
* If a step cannot be replayed safely (e.g., because of a UI change or a setup-hook value BugRadar cannot substitute), the agent handles that step live. Independent earlier steps can still use the cache.
* Replay can resume after live execution when BugRadar can verify the required action completed and the app matches a later checkpoint; otherwise the remaining steps run live. Runs that include live steps receive a fresh review.

**Using hooks?** How a hook passes a value to the flow affects whether the flow can be cached. See [Hooks and Run Caching](/docs/hooks.md#hooks-and-run-caching).

**Preview deployments:** Web runs can reuse cached navigation across deployments when `BASE_URL` or `API_BASE_URL` is supplied as a [build variable](/docs/variables.md#build-variables), suite/flow variable, or setup-hook export. Setting only the registered web `url` or a variable in Settings → Environments does not opt into this origin reuse. For CI previews, pass the deployment origin as `BASE_URL` through the Action's `variables` input as well as setting `url`; see [Web Setup](/docs/ci-cd-integration.md#web-setup).

The variable must be an HTTP(S) origin, such as `https://preview.example.com`, with an optional trailing `/` and no other path, query string, fragment, or credentials. For supported cached navigation whose destination matches the recorded `BASE_URL` or `API_BASE_URL` origin, BugRadar replaces that leading origin with the current value of the same variable while preserving the path and query. Other destination origins are not rewritten by this mechanism. These named origins qualify without the changing-value learning period required for custom hook exports. Ambiguous values and embedded redirect URLs still require live execution.

Reuse stays within the same app and environment and remains subject to UI checkpoint checks. Keep production and preview targets in separate BugRadar environments. Other changing variables still follow their existing caching rules.

Manage it in **[Settings → Agent Features](https://usebugradar.com/settings)**.

### Run caching modes

Workspace owners and admins choose **Off**, **Standard**, or **Semantic cache** under **Settings → Agent → Run caching**.

* **Off** runs every step with the live agent.
* **Standard** reuses successful steps when the screen closely matches. Workspaces already using run caching start in this mode.
* **Semantic cache** also finds equivalent controls when the screen changes. It is experimental and requires **UI/UX Agent** reviews.

Selecting Standard or Semantic cache also enables at least one auto-retry if retries were off. If reviews are later disabled, Semantic cache is paused. You can still select Standard or Off.

For dashboard-authored flows, use **Advanced options → Run caching**. New flows use **Use workspace setting**. Choose **Off** to disable caching for a flow, or **Standard** to keep it on Standard even when the workspace uses Semantic cache. A flow cannot exceed its workspace’s mode: choosing Semantic cache in a Standard workspace still uses Standard. Code-managed flow controls remain read-only; set `caching_mode` in YAML instead.

Semantic cache mode tries Standard caching first. When it cannot reuse a step, it compares a successful, reviewed recording with the current screen and finds the control that does the same thing. If the match is unclear, blocked, or missing, the live agent handles the action.

The initial release supports eligible clicks, taps, and text entry on web and iOS. Android, unlabeled image targets, and retries use the normal agent and Standard cache where supported. Some actions still need the live agent, so Semantic cache does not guarantee a faster run.

Hooks execute again with current inputs and fresh results. Caching never reuses an old hook result. Variable extraction also stays live. Runs using Semantic cache get a fresh UI/UX Agent review, including runs that only record actions for future use. They cannot inherit an earlier pass.

Run details show the recorded **Cache setting** and the run’s **Cost** in actions, with AI actions, State cache, and Semantic cache counts. These counts describe the actions the run actually took, independently of the selected cache setting. Historical runs without a saved setting show **Not recorded**.

## Troubleshooting

### Flow Fails Immediately

**Possible Causes:**

* App build is missing or corrupted
* Bundle ID mismatch
* App crashes on launch

**Solutions:**

* Check that your app has a default build
* Verify the bundle ID is correct
* Test the app build manually first

### Agent Can't Find Elements

**Possible Causes:**

* UI element description is ambiguous
* Element isn't visible on screen
* Element loads after a delay

**Solutions:**

* Disambiguate by purpose or nearby label rather than visual attributes. Prefer "Tap the 'Submit' button under the password field" over "Tap the blue submit button in the bottom right" — describing pixel position or color locks the test to today's UI.
* Add a wait when the element loads asynchronously: "Wait for the order summary to appear, then continue."

## Next Steps

* [Organize flows with Suites →](/docs/suites.md)
* [Automate flows with Schedules →](/docs/automations.md)
* [Integrate with our CI/CD →](/docs/ci-cd-integration.md)
* [Manage flows in your repo →](/docs/code-managed-flows.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.