> ## 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-text

> Scroll the screen until the specified text is found.

<div className="replay-block">
  <iframe src="https://app.dashcam.io/replay/6866b26704a2f851a9161ae1?share=HUDabZvGLKtVkuXOjKqQQ&embed=true&timestamp=90000&playbackRate=5" width="1000" height="350" />
</div>

```yaml testdriver/scroll-until-text.yaml highlight={9-11} theme={null}
version: 6.0.0
steps:
  - prompt: login
    commands:
      - command: run
        file: testdriver/snippets/login.yaml
  - prompt: scroll until text testdriver socks
    commands:
      - command: scroll-until-text
        text: testdriver socks
        direction: down
  - prompt: assert testdriver socks appears on screen
    commands:
      - command: assert
        expect: TestDriver Socks appears on screen
```

## Description

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

## Arguments

|   Argument  |    Type   | Description                                                                                                             |
| :---------: | :-------: | :---------------------------------------------------------------------------------------------------------------------- |
|    `text`   |  `string` | The text to find on the screen. Longer and unique are better. Note this is **case sensitive**                           |
| `direction` |  `string` | (Optional) The direction to scroll. Available directions are: `up`, `down`, `left`, `right`. Defaults to `down`.        |
|   `method`  |  `string` | (Optional) The method to use to scroll the page. Available methods are: `mouse` and `keyboard`. Defaults to `keyboard`. |
|  `distance` |  `number` | (Optional) The maximum number of scroll clicks before giving up. Default is `100`.                                      |
|   `invert`  | `boolean` | (Optional) If set to `true`, the command will scroll until the specified text is NOT detected. Default is `false`.      |

<Note>
  If the method is `keyboard` it just searches for the string by doing `ctrl + f`.
  This is helpful if there is a single string match that you want to operate with.

  If you are using `mouse` method, the command will manually scroll the page (based on the `distance`) until the text is found.
</Note>

## Example usage

```yaml theme={null}
command: scroll-until-text
text: Sign Up
direction: down
distance: 1000
```

## Protips

* Use unique and specific text to improve detection accuracy.
* Adjust the `distance` value to control how far the command scrolls before giving up.
* If you don't specify a `distance`, the command will scroll 5 clicks at a time, giving up after reaching 100 clicks.

## Gotchas

* If the text can't be located within the specified `distance`, the command will fail.
* Ensure the text is visible and matches exactly, as variations in font size, style, or screen resolution may affect detection accuracy.
* Note that `text` is case-sensitive, so **Sign Up** and **sign up** would be treated as different strings.

***

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