scrollUntilVisible

Scroll automatically until a target element becomes visible on screen.

Scrolls the screen in a specified direction until a target element is visible.

Parameters

The following parameters configure the scrollUntilVisible command.

Parameter	Type	Description
element	string or object	Required. The selector for the element to find. To select the element, you can use any of the available selectors.
direction	string	(Optional). The direction to scroll. Accepts DOWN, UP, LEFT, or RIGHT. Defaults to DOWN.
timeout	integer	(Optional). The maximum time in milliseconds to scroll while searching for the element. If the timeout is reached before the element is found, the test fails. Defaults to 20000 milliseconds.
speed	integer	(Optional). The scroll speed, specified as a value from 0 to 100. Higher values result in faster scrolling. Defaults to 40.
visibilityPercentage	integer	(Optional). The percentage of the element, from 0 to 100, that must be visible in the viewport for the scroll to stop. Defaults to 100.
centerElement	boolean	(Optional). If true, the command keeps scrolling until the element is more than 30% away from the viewport edge (e.g. in the top 70% when scrolling down). If the element cannot reach that position (e.g. it is the last list item), the command stops after a few attempts. Defaults to false.

INFO

By default, an element is considered visible if it is fully displayed in the viewport.

How it works

The command checks whether the target element is visible. If not, it swipes from the center of the screen toward the edge (to 10% from the edge in the chosen direction), checks again, and repeats until the element is found or the timeout is reached.

This behavior works well when the whole screen scrolls (e.g. a full-screen list). When only part of the screen is scrollable (such as a bottom sheet, a fragment, or a small widget), the swipe may miss the scrollable region. For those layouts, use a custom scroll loop. The Custom scrolling for screen fragments shows how you can do it.

Usage examples

The following examples demonstrate how to use the scrollUntilVisible command.

Scroll to an element with specific text

This example scrolls down until an element containing the text "My text" is visible.

- scrollUntilVisible:
    element: "My text"
    direction: DOWN

Scroll to an element by ID

This example scrolls down until a view with a matching ID becomes visible.

- scrollUntilVisible:
    element:
      id: ".*some_view_id"
    direction: DOWN

Center an element after scrolling

Use centerElement: true to keep scrolling until the target is not only visible but also more than 30% away from the viewport edge. The example below stops when "Item 6" meets that condition.

- scrollUntilVisible:
    centerElement: true
    element:
      text: "Item 6"