---
title: "scroll-until-image"
sidebarTitle: "scroll-until-image"
description: "Scroll the screen until an image matching the description is found."
icon: "film-simple"
mode: "wide"
---

import Replay from "/snippets/tests/scroll-until-image-replay.mdx";
import Example from "/snippets/tests/scroll-until-image-yaml.mdx";

<Replay />
<Example />

## Description

The `scroll-until-image` command is used to scroll the screen in a specified direction until an image matching the given description is found. This is useful for navigating to visual elements that aren't initially visible on the screen.

## Arguments

|   Argument    |   Type    | Description                                                                                                             |
| :-----------: | :-------: | :---------------------------------------------------------------------------------------------------------------------- |
| `description` | `string`  | A description of the image and what it represents.                                                                      |
|  `direction`  | `string`  | (Optional) The direction to scroll. Available directions are: `up`, `down`, `left`, `right`. Defaults to `down`.        |
|  `distance`   | `number`  | (Optional) The maximum number of pixels to scroll before giving up. Default is `10000`.                                 |
|   `method`    | `string`  | (Optional) The method to use to scroll the page. Available methods are: `mouse` and `keyboard`. Defaults to `keyboard`. |
|    `path`     | `string`  | (Optional) The relative path to the image file that needs to be matched on the screen.                                  |
|   `invert`    | `boolean` | (Optional) If set to `true`, the command will scroll until the specified image is NOT detected. Default is `false`.     |

<Note>
  Use either the `description` or `path` argument to match an image on the
  screen. If you are using `path` argument, make sure to upload an accurate
  representation of the actual image and reference it relative to the current
  test path.
</Note>

## Example usage

```yaml
command: scroll-until-image
description: Submit at the bottom of the form
direction: down
```

Or, you can use the `path` argument to match an image on the screen (similar to [`match-image`](./match-image)):

```yaml testdriver/scroll-until-image.yaml
command: scroll-until-image
path: screenshots/button.png
direction: down
```

## Protips

- Use clear and concise descriptions for the image to improve detection accuracy.
- Adjust the `distance` value to control how far the command scrolls before giving up.
- Combine this command with other commands like `hover-image` or `match-image` to interact with the located image.

## Gotchas

- If the image can't be located within the specified `distance`, the command will fail.
- Ensure the description accurately represents the image to avoid detection issues.

---

The `scroll-until-image` command is ideal for navigating to visual elements that are off-screen and can't be located using text-based commands.