> 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/writing-tests/tap/scroll.md).

# Scroll

`Scroll` moves the viewport, either by a fixed amount or until a named target comes into view.

|                  |                                                                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Platforms**    | Android · iOS                                                                                                                                         |
| **Default step** | 50% of the screen                                                                                                                                     |
| **Max scrolls**  | 20 (configurable per app)                                                                                                                             |
| **Direction**    | Up, down, left, right — the direction your thumb moves                                                                                                |
| **Watch out**    | <p>Scoll direction is determined by human interpretation of thumb movement on UI<br>Eg. To scroll page upwards direction would be "up" not "down"</p> |

## Prerequisites

* A connected device or emulator
* An open test file
* A screen that has finished loading before the scroll runs

## Copy this

```
OPEN_APP com.shopease.android
Wait Until 5 Seconds

Tap on the cart icon
Wait Until 3 Seconds

Scroll down until "Proceed to Pay" is visible
Validate that Proceed to Pay is visible
Tap on Proceed to Pay
```

## Write a scroll step

1. Confirm the screen has finished loading — add a `Wait` or a `Validate` above the scroll.
2. Write `Scroll <direction> until "<target>" is visible`, with the target in quotes.
3. Add `inside <container>` when the screen has more than one scrollable region.
4. Add a step size or a max-scroll override when the default 50% step or 20-scroll limit doesn't reach the target.
5. Run the test and confirm the report shows the scroll resolving before the validation.

## Parameters

| Parameter        | Syntax                                                                                          | Default                             | Notes                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- |
| **Direction**    | `Scroll up` · `down` · `left` · `right`                                                         | None — always state it              | The direction your thumb moves, not the direction the content moves                           |
| **Target**       | `until "<target>" is visible`                                                                   | None                                | Quote the target. Quotes give Drizz an exact string to match instead of a phrase to interpret |
| **Step size**    | `by <n>%` · `in steps of <n>%` · `with scroll percentage of <n>%` · `Scroll every time by <n>%` | 50% of the screen                   | Drops to 35% automatically when Drizz detects a scroll had no effect                          |
| **Max scrolls**  | `with max of <n> scrolls` · `(Max scroll - <n>)`                                                | 20                                  | Configurable per app — some apps run at 25, 30 or 40                                          |
| **Container**    | `inside <container>`                                                                            | The scrollable region Drizz selects | Required on screens with more than one scrollable region                                      |
| **Repeat count** | `Scroll thrice`                                                                                 | One scroll                          | Fixed scrolls only; scroll will only happen once                                              |

`until`, `till` and `untill` all work, and `Swipe` is interchangeable with `Scroll`.

To change the defaults for your app rather than per command, ask your Drizz contact. They're per-app settings.

## Scroll until a target is visible

```
Scroll down until "Proceed to Pay" is visible
Scroll up until "Home" tag is visible
Scroll right until "Next" CTA is visible
Scroll down until "Apply Coupon" is visible
Scroll up until "Back to Top" is visible
```

The target can be described rather than named:

```
Scroll down until you find 4 product cards under "Beauty"
Scroll down until items appear under "Snacks"
Scroll up until offers are visible under "Top Deals"
```

Name the container on screens with more than one scrollable region:

```
Scroll down inside product list until "Add to Cart" is visible
Scroll right inside categories until "Electronics" is visible
Scroll down inside reviews until "Write a Review" is visible
```

## Fixed scroll

Not ideal way of using the command as it could toss the reliability.

`Scroll until` stops when it finds the target. A fixed scroll moves the set distance whether or not the target is on screen.

## Tuning the step and the limit

Both can be set on the command:

```
Scroll up until "Choose a customer type" is visible in steps of 30%
Scroll down until "Order Summary" is visible with max of 40 scrolls
Scroll down inside product list with scroll percentage of 30%
Scroll Up until you find "Other" (Max scroll - 50, Scroll every time by 100%)
```

## Hitting the limit fails the step

A scroll that runs out its max-scroll count without finding the target **stops without failing**. The test stops and the next actionable command won't run reliably.

## One target per command

Bringing two things into view takes two scroll commands.\
Note: The target can have primary target and secondary target. Example- Scroll up until "Chocolates" is visible under "Kids" header.

```
Scroll down until "Order Summary" is visible
Scroll down until "Proceed to Pay" is visible
```

## Self-healing

When a scroll is blocked by a sticky header, an overlapping element or a nested scroll view, Drizz detects that the screen didn't move and retries with a reduced step. The report shows the reduced scroll distance. It is automatic. It also indicates that the container being scrolled is not the intended one.

## Common mistakes

<table data-search="false"><thead><tr><th>What you wrote</th><th>What happens</th></tr></thead><tbody><tr><td><code>Scroll until Proceed to Pay</code> — no quotes, no direction</td><td>Drizz has to infer both. Unstable across runs and devices</td></tr><tr><td><code>Scroll down</code> when you meant to reveal content above</td><td>Down moves your thumb down, which reveals content <em>above</em>. Use <code>Scroll up</code></td></tr><tr><td><code>Scroll down until "Checkout" is visible</code> with nothing after it</td><td>If the target is never found, the step stops silently and the next command runs on the wrong screen</td></tr><tr><td><code>Scroll down until "Total" and "Proceed" are visible</code></td><td>One target per command. Write two lines</td></tr><tr><td>A scroll on a screen with a horizontal carousel and a vertical list</td><td>The wrong region moves. Name the container: <code>Scroll down inside product list</code></td></tr><tr><td><code>Scroll down until "Item 200" is visible</code> in a 300-item list</td><td>Stops at 20 scrolls by default. Raise it on the command, or ask for a per-app default</td></tr><tr><td>A scroll issued while the screen is still loading</td><td>Nothing scrolls, or the wrong container does. Wait for the screen first</td></tr><tr><td>A script written against the old scroll-back behavior</td><td>Since August 2026 the viewport stays where the last target was found. Split it into two scroll commands</td></tr></tbody></table>

## Next

* [Validate](/writing-tests/tap/validate.md) — what to put after a scroll
* [Waits & timing](/writing-tests/waits-and-timing.md) — scrolling a screen that hasn't settled
* [Command index](/writing-tests/command-index.md) — every command in one table

***

*Last updated: 6 August 2026*