> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/running-tests/running-locally.md).

# Running locally

A local run executes a test on the device connected to your Mac, with live screenshots in the console.

|                   |                                                                                  |
| ----------------- | -------------------------------------------------------------------------------- |
| **Platforms**     | Android · iOS                                                                    |
| **Where it runs** | Your Mac, against one connected device                                           |
| **Parallelism**   | One test at a time — use a [test plan](/running-tests/test-plans.md) to run many |
| **Queues**        | None. A local run starts immediately                                             |
| **Watch out**     | Local runs are metered the same way as cloud runs                                |

## Prerequisites

* Drizz desktop app installed and signed in
* One emulator, simulator or USB-connected device
* A physical Android device unlocked — Drizz refuses a locked device
* The app under test available on the device or in the app list

## Copy this

A complete test against ShopEase, the demo app used throughout these docs. Swap the package name and the screen labels for your app's.

```
# ShopEase — search for a product and open it

OPEN_APP com.shopease.android
Wait Until 5 Seconds

Validate that the home screen is visible

Tap on the search icon
Wait Until 2 Seconds

Type running shoes in the search field
Tap on the first search result
Wait Until 3 Seconds

Validate that the product detail page is visible

CLEAR_APP com.shopease.android
```

## Run a test

1. Open the Connect Device screen.
2. Select your emulator, simulator or attached device.
3. Confirm the device shows as connected. Connect once per session.
4. Select the app under test from the app list. Drizz installs and launches it if it isn't already present.
5. Click run — for the open file in the editor, or for the lines you have selected.
6. Confirm the first step reports a status decorator beside its line in the editor.

## Platform differences

{% tabs %}
{% tab title="Android" %}

* Connect an emulator or a USB device with **Developer options** and **USB debugging** enabled.
* `CLEAR_APP com.shopease.android` wipes app data between runs.
* Disable the emulator soft keyboard. It covers elements and the tap after a `Type` fails as undoable.
  {% endtab %}

{% tab title="iOS" %}

* Connect a simulator, or a physical device trusted by the Mac.
* `CLEAR_APP` has no effect on iOS. Log out in-app, or reinstall between tests.
* iOS steps run roughly twice as slow as the equivalent Android steps.
  {% endtab %}
  {% endtabs %}

## What the console shows

| Element                            | Content                                                     |
| ---------------------------------- | ----------------------------------------------------------- |
| **Live execution step level**      | The device screen at the moment the step ran                |
| **Step classification**            | How the line was read — tap, type, validate, scroll, system |
| **Explainable reasoning per step** | Why Drizz selected the element it selected                  |
| **Status decorator in the editor** | Pending, running, passed or failed, beside the line         |
| **Timestamps**                     | Per-step duration                                           |
| **Token usage in the run banner**  | DT spent so far on this run                                 |

Steps that resolve from cache appear as *"Predicted Action drizzing fast ⚡"* and finish in a fraction of the time — see [Caching](/running-tests/caching.md). Cached steps are the cheapest step category; Vision AI steps are the most expensive.

When the run ends Drizz writes a report: a run summary, per-step outcomes with before and after screenshots, the logs, and a failure summary. See [Reading a report](/reports-and-debugging/reading-a-report.md).

## Stop a run

1. Click stop.
2. Wait for the step in flight to finish. Drizz releases the device and writes a report for the steps that ran.

{% hint style="success" %}
If the UI sits on **"Stopping"**, wait. Drizz has a safety-net timeout that recovers a stuck stop. If it hasn't cleared after that, restart the desktop app — see [Troubleshooting](/reports-and-debugging/troubleshooting.md).
{% endhint %}

## Local run limits

A local run cannot do any of the following. Use a [test plan](/running-tests/test-plans.md) instead.

| Limit                   | Detail                                   |
| ----------------------- | ---------------------------------------- |
| **One test per run**    | Multiple tests in one run require a plan |
| **No parallelism**      | One test at a time                       |
| **Local devices only**  | Cloud and private devices are plan-only  |
| **Manual trigger only** | CI triggers a plan, not a local run      |
| **No quality gate**     | A pass/fail threshold is a plan setting  |

## Common mistakes

| What you do                                | What happens                                                    |
| ------------------------------------------ | --------------------------------------------------------------- |
| Leave the emulator soft keyboard enabled   | It covers elements and the tap after a `Type` fails as undoable |
| Judge suite speed on the first run         | The cache is cold. Runs two and three are the honest measure    |
| Rely on `CLEAR_APP` for clean state on iOS | It's a no-op there — the next run reuses state                  |
| Force-quit the app on a stuck "Stopping"   | The timeout recovers it, and you lose the partial report        |
| Lock the phone mid-run                     | The run fails on the next step. Keep it awake and unlocked      |

## Next

* [Test plans](/running-tests/test-plans.md)
* [Reading a report](/reports-and-debugging/reading-a-report.md)
* [When a step fails](/reports-and-debugging/when-a-step-fails.md)

***

*Last updated: 6 August 2026*