testdriver/scroll-until-image.yaml
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

ArgumentTypeDescription
descriptionstringA description of the image and what it represents.
directionstring(Optional) The direction to scroll. Available directions are: up, down, left, right. Defaults to down.
distancenumber(Optional) The maximum number of pixels to scroll before giving up. Default is 10000.
methodstring(Optional) The method to use to scroll the page. Available methods are: mouse and keyboard. Defaults to keyboard.
pathstring(Optional) The relative path to the image file that needs to be matched on the screen.
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.

​
Example usage

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):
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.