> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# scroll-until-image

> Scroll the screen until an image matching the description is found.

<div className="replay-block">
  <iframe src="https://app.testdriver.ai/replay/68a5b9b5a194743845ca64bc?share=7M6G5hRzDqJAQ7ACVrtHg&embed=true&timestamp=90000&playbackRate=5" width="1000" height="350" />
</div>

```yaml testdriver/scroll-until-image.yaml highlight={5-7} theme={null}
version: 6.0.0
steps:
  - prompt: scroll until image of a house appears, then click on it and assert the home insurance page is loaded
    commands:
      - command: scroll-until-image
        description: a pink colored house
        direction: down
      - command: hover-image
        description: a pink colored house
        action: click
      - command: assert
        expect: Home Insurance page appears
```

## 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 scroll clicks before giving up. Default is `100`.                                      |
|    `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 theme={null}
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 theme={null}
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.