> 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/creating-and-running-a-plan.md).

# Creating & Running a plan

Eight steps create a plan. One button runs it. The run screen reports progress while it runs.

|                         |                                                                               |
| ----------------------- | ----------------------------------------------------------------------------- |
| **Platforms**           | Android · iOS (real-device build required)                                    |
| **You need first**      | A registered app build, and at least one saved test                           |
| **Set per plan**        | Devices · concurrency · dataset · quality gate                                |
| **Concurrency ceiling** | The lower of available devices and lockable pool size                         |
| **Watch out**           | Reordering tests changes execution order only — it never edits the test files |

## Prerequisites

* Access to Drizz Cloud
* A registered app build — APK, or iOS real-device build, under 500 MB
* At least one saved test in the project
* A dataset, if any test uses `{{variables}}`

## Create the plan

1. Open the **Test Plans** section in Drizz Cloud and click **Create Test Plan**.
2. Enter a name, an optional description, and the project. Name it for what it covers — `Checkout_Regression`, `Login_Sanity`. This name appears in every report and every CI log.
3. Select the provider: emulator, simulator or real device. See [Devices](/running-tests/devices.md).
4. Select the registered app build. iOS plans require a real-device build; a simulator build is rejected here. Uploads cap at 500 MB.
5. Select the device configuration: model, OS version and device type. Hold this configuration steady across runs of the same plan.
6. Select the test cases from your saved tests.
7. Drag the test cases into execution order. This sets run order only; it does not modify the test files.
8. Click **Save**.
9. Confirm the plan appears in the Test Plans list with a run control. The plan stays editable — adding, removing or reordering tests and changing devices does not discard run history.

## Configure the run

Four settings, all stored on the plan rather than in the scripts.

| Setting             | What it does                                                                                                                                          |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Devices**         | How many devices the plan can use, and of what kind. If nothing is free, the run waits rather than failing — see [Devices](/running-tests/devices.md) |
| **Concurrency**     | How many tests run at once                                                                                                                            |
| **Dataset binding** | The values every `{{variable}}` in every test in the plan resolves from                                                                               |
| **Quality gate**    | The pass threshold the plan must clear to count as passed                                                                                             |

### Concurrency ceilings

Two limits apply on top of the number you set.

| Cap                          | Effect                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------ |
| **Devices available to you** | 6 free devices means 6 tests at once, whatever you set                         |
| **Lockable pool size**       | A 4-row pool means at most 4 parallel runs — each run leases a row exclusively |

A suite that runs 10-wide needs 10 or more rows in the pool — see [Lockable pools](/writing-tests/which-variable/lockable-pools.md).

### Dataset binding

Bind a dataset if any test in the plan uses `{{variables}}`. Every `{{variable}}` in every test in the plan resolves from it, so the same suite runs against staging and production with no script change.

{% hint style="warning" %}
Bind a dataset to any plan containing variables, **even an empty one**. A plan with variables and no dataset bound misclassifies `SET` commands and the run goes wrong quietly. 
{% endhint %}

### Quality gate

The threshold the plan must clear to count as passed — for example, pass if 90% or more of tests pass. This is the number a CI job gates on. At 100%, one flaky test blocks every build.

## Run the plan

{% tabs %}
{% tab title="From the dashboard" %}

1. Open the plan.
2. Click **Run**.
3. Confirm the run screen opens and reports allocated devices.
   {% endtab %}

{% tab title="From CI" %}

1. Authenticate against the API — see [Authenticate](/automate-and-integrate/authenticate.md).
2. Upload the build — see [Upload a build](/automate-and-integrate/upload-a-build.md).
3. Trigger the plan — see [Trigger a run](/automate-and-integrate/trigger-a-run.md).
4. Confirm the trigger response returns a run identifier.

There is no run-status endpoint. CI can start a plan but cannot wait on it or gate a build on the outcome — see [CI/CD](/automate-and-integrate/ci-cd.md).
{% endtab %}
{% endtabs %}

Drizz allocates devices, installs the build, and starts tests up to the concurrency limit. Runs that can't get a device wait in the queue.

## Watch the run

| Area                | Contents                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Summary**         | Total tests, passed, failed, errored, and completion status                                                   |
| **Thread view**     | One lane per parallel thread, each with its own identifier, for following a single test through a 10-wide run |
| **Per-test detail** | Status, healed-step count, elapsed time, start and finish timestamps, and the device it ran on                |
| **Artifacts**       | Screenshots, step logs and the recording, per test attempt                                                    |
| **Run history**     | The same plan's previous runs                                                                                 |

Expand a test to see its step list. Expand a step to see its before and after screenshots and reasoning — see [When a step fails](/reports-and-debugging/when-a-step-fails.md).

## Edit a plan after it has run

None of these modify authored tests, and none discard run history:

* Add or remove test cases.
* Reorder test cases.
* Change devices, OS versions or the provider.
* Swap the dataset.
* Point the plan at a new build.

## Common mistakes

| What you do                                                             | What happens                                                             |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Set concurrency above your pool size                                    | Extra runs wait on a lease, and the suite takes longer                   |
| Set the quality gate to 100%                                            | One flaky test blocks every build                                        |
| Change the device model between runs of the same plan                   | Real regressions read as flakiness                                       |
| Reorder tests to fix a failure                                          | If test B needs test A's state, make it explicit in the script           |
| Run the plan without rebinding the dataset after switching environments | The suite runs green against the wrong backend                           |
| Trigger from CI and assume it gates the build                           | There's no run-status endpoint. CI can start a plan but can't wait on it |

## Next

* [Devices](/running-tests/devices.md)
* [Reading a report](/reports-and-debugging/reading-a-report.md)
* [Statuses](/reports-and-debugging/statuses.md)

***

*Last updated: 6 August 2026*