Implementation:Getgauge Taiko ScrollTo
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, User_Interaction |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
Concrete tool for scrolling web page elements into view and performing pixel-based or element-targeted scroll operations provided by the Taiko browser automation library.
Description
This module exports two functions -- `scrollToElement` and `scroll` -- that handle different scrolling scenarios in browser automation.
- `scrollToElement(element, options)`** scrolls a specific element into the visible viewport using the browser's native `scrollIntoView` API. The algorithm:
1. Extracts `blockAlignment` and `inlineAlignment` values from the `options` parameter via `setScrollOptions`. These control the vertical (`block`) and horizontal (`inline`) alignment of the element within the viewport (e.g., `"start"`, `"center"`, `"end"`, `"nearest"`). 2. Executes a function in the browser context via `runtimeHandler.runtimeCallFunctionOn` that calls `this.scrollIntoView({ block, inline })` on the target element. For text nodes (`Node.TEXT_NODE`), the function operates on the parent element instead, since text nodes do not support `scrollIntoView` directly.
This function is used extensively as a prerequisite step by other Taiko actions (hover, click, dragAndDrop, etc.) to ensure the target element is visible before interaction.
- `scroll(e, px, scrollPage, scrollElement, direction)`** provides a dual-mode scroll capability:
1. **Page-Level Scroll (integer input):** When `e` is a number (or defaults to 100 if falsy), it evaluates the `scrollPage` callback function in the browser runtime, passing the pixel amount. This performs a page-level scroll by the specified number of pixels in the given direction.
2. **Element-Level Scroll (selector input):** When `e` is a selector, it finds the first matching element via `findFirstElement`, optionally highlights it in headful mode, and then executes the `scrollElement` callback function on that element via `runtimeCallFunctionOn`, passing `px` as the scroll amount. The action is wrapped in `doActionAwaitingNavigation` to handle any lazy-loading or infinite-scroll navigation that the scroll may trigger.
Both paths include error handling: if the runtime evaluation returns an error subtype, the error description is thrown as a JavaScript Error. The `scrollPage` and `scrollElement` parameters are callback functions injected by the caller (typically the directional scroll wrappers like `scrollUp`, `scrollDown`, `scrollLeft`, `scrollRight`), which define the actual scroll behavior for each direction.
Usage
Use `scrollToElement` whenever an element needs to be brought into view before interaction -- this is called internally by actions like `hover`, `click`, and `dragAndDrop`. Use `scroll` for explicit scroll operations in test scripts, such as scrolling down to load lazy content, scrolling within a specific scrollable container, or testing infinite scroll behavior. The `scroll` function backs the public Taiko API methods `scrollUp`, `scrollDown`, `scrollLeft`, and `scrollRight`.
Code Reference
Source Location
- Repository: Getgauge_Taiko
- File: lib/actions/scrollTo.js
- Lines: 1-69
Signature
const scrollToElement = async (element, options = {}) => { ... }
const scroll = async (e, px, scrollPage, scrollElement, direction) => { ... }
Import
const { scrollTo, scrollUp, scrollDown, scrollLeft, scrollRight } = require('taiko');
I/O Contract
Inputs
scrollToElement
| Name | Type | Required | Description |
|---|---|---|---|
| element | Element | Yes | A resolved Taiko Element wrapper whose underlying DOM node should be scrolled into the viewport. |
| options | object | No | Configuration object. Supports `blockAlignment` (string: `"start"`, `"center"`, `"end"`, `"nearest"`) for vertical alignment and `inlineAlignment` (string: same values) for horizontal alignment within the viewport. Defaults to `{}`. |
scroll
| Name | Type | Required | Description |
|---|---|---|---|
| e | number / Selector / string | No | The scroll target. If a number, specifies the pixel amount for page-level scrolling. If a selector or string, identifies the scrollable element to scroll within. Defaults to `100` if falsy. |
| px | number | Conditional | The number of pixels to scroll within the target element. Used only when `e` is a selector. |
| scrollPage | function | Yes | A callback function that performs page-level scrolling. Receives the pixel amount as its argument and is evaluated in the browser runtime. |
| scrollElement | function | Yes | A callback function that performs element-level scrolling. Receives the pixel amount as its argument and is executed on the target element via `runtimeCallFunctionOn`. |
| direction | string | Yes | A human-readable direction label (e.g., `"up"`, `"down"`, `"left"`, `"right"`) used in the return description string. |
Outputs
| Name | Type | Description |
|---|---|---|
| scrollToElement result | Promise<void> | Resolves with no value once the element has been scrolled into view. |
| scroll result | Promise<object> / Promise<string> | For page-level scrolling, returns an object `{ description: "Scrolled <direction> the page by <n> pixels" }`. For element-level scrolling, returns a string `"Scrolled <direction> <element description> by <px> pixels"`. |
Usage Examples
Basic Usage
const { openBrowser, goto, scrollDown, scrollUp, scrollRight, $, closeBrowser } = require('taiko');
(async () => {
await openBrowser();
await goto('https://example.com/long-page');
// Scroll down the page by 500 pixels
await scrollDown(500);
// Scroll up the page by 200 pixels
await scrollUp(200);
// Scroll within a specific scrollable container by 300 pixels
await scrollRight($('.horizontal-list'), 300);
await closeBrowser();
})();