> For the complete documentation index, see [llms.txt](https://docs.does.qa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.does.qa/test-steps/runner/loop.md).

# Loop

Repeat a set of steps for a fixed count or until a condition is met.

Loop repeats a set of steps inside it. Use it to retry actions until an element appears, poll for changing state, or run the same steps multiple times with different data.

![Loop Test Step](https://static.does.qa/assets/nodes/runner_loop.png)

On the canvas, the Loop shows your Label. With no Label, it shows the iteration count such as "Loop 5 times" (your Times value) or "Loop until condition".

## When to use it

* Retry a Touch until a loading spinner disappears and a button becomes clickable.
* Wait for a status message to change from Processing to Complete.
* Repeat form submission for multiple records without duplicating steps.
* Poll an API until a response field matches an expected value.

Use Until condition mode with a [Check](/test-steps/check.md) step in the Condition slot. The Loop reports passed when the Check succeeds within the Maximum iterations you set.

## Configure

### Basics

| Field         | What to set                                                                                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Steps**     | The steps to run on each iteration.                                                                                                                                                    |
| **Mode**      | `Fixed count` (repeat a set number of times) or `Until condition` (repeat until a Check step passes)                                                                                   |
| **Times**     | For Fixed count: how many iterations to run. Default 5.                                                                                                                                |
| **Condition** | For Until condition: a [Check](/test-steps/check.md) step in a separate slot. The Loop passes when the Check passes, and fails if the Check is still failing after Maximum iterations. |

### Advanced

| Field                                 | What to set                                                                                  |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Label**                             | Optional name shown in the step list and results                                             |
| **Maximum iterations**                | For Until condition: stop and fail the Loop after this many tries.                           |
| **Delay between iterations**          | Seconds to wait between each iteration. Default 5. Set 0 when steps already include waits.   |
| **If a step fails**                   | `Stop` (default, fail the Loop immediately) or `Continue` (carry on with the next iteration) |
| **When should screenshots be taken?** | `On Failures` (default) or `Always`                                                          |
| **Status on fail**                    | [Failed Status](/test-step-options/failed-status.md)                                         |

{% hint style="info" %}
**Pro tip:** Combine Loop Until condition with [Check Displayed](/test-steps/check/check-displayed.md) or [Check Text](/test-steps/check/check-text.md) to wait for UI state without a fixed Pause. The Loop stops as soon as the Check passes.
{% endhint %}

## Built-in Values inside a Loop

Two [Built-in Values](/values/built-in-values.md) track progress inside a Loop:

| Name               | Description                            | Example |
| ------------------ | -------------------------------------- | ------- |
| **loopIteration**  | Current iteration number (starts at 1) | 3       |
| **loopIterations** | Total iterations for Fixed count mode  | 10      |

Use `$loopIteration` in a Set Value or form field to vary data on each pass.

In Results, each iteration appears as its own row, such as "Iteration 2 of 5".

## Flow Builder example

A typical Loop that retries until an element is shown:

1. Add a **Loop** step
2. Set **Mode** to `Until condition`
3. Under **Steps**, add **Touch** the Refresh button Element
4. Under **Condition**, add **Check Displayed** on the Success message Element
5. Set **Maximum iterations** and **Delay between iterations** as needed

On each iteration, the Loop runs its Steps, then the Condition. It passes when the Condition passes, or fails after reaching Maximum iterations.

### Example flow structure

```
Loop (Until condition)
├── Steps: Touch (Refresh button)
└── Condition: Check Displayed (Success message)
```

The Loop runs the Steps on each iteration, then checks the Condition. It continues until the Condition passes.

## Related

* [Condition](/test-steps/runner/condition.md)
* [Choose Flow Branch shapes](/better-coverage/choose-flow-branch-shapes.md)
* [Step Group](/test-steps/step-group.md)
* [Wait For Element To Be Displayed](/test-steps/runner/wait-for-element-to-be-displayed.md)
* [Pause](/test-steps/runner/pause.md)
* [Runner](/test-steps/runner.md)

**Tags:** `runner`, `loop`, `repeat`, `retry`, `iteration`, `until`, `poll`