t.scroll Method

Important

When TestCafe interacts with an off-screen DOM element, it scrolls that element into view. There is usually no need to use the scroll action.

Scrolls the target element to a specified position. If no target is specified, the document body is scrolled. Can be chained with other TestController methods.

Syntax

scroll(posX, posY)

t.scroll([target,] posX, posY[, options]) → this | Promise<any>
Parameter Type/Value Description
target (optional) Function | String | Selector | Snapshot | Promise Identifies the webpage element to scroll. If unspecified, TestCafe scrolls the document body. See Select Target Elements.
posX  Number The absolute location of the final scroll position on the horizontal axis
posY  Number The absolute location of the final scroll position on the vertical axis
options (optional) Object A set of options with additional parameters for the action. See Options.

scroll(position)

t.scroll([target,] position[, options]) → this | Promise<any>
Parameter Type/Value Description
target (optional) Function | String | Selector | Snapshot | Promise Identifies the webpage element to scroll. If unspecified, TestCafe scrolls the document body. See Select Target Elements.
position  ‘left’ | ‘right’ | ‘bottom’ | ‘topLeft’ | ‘topRight’ | ‘bottomLeft’ | ‘bottomRight’ | ‘center’ TestCafe scrolls the element to this position.
options (optional) Object A set of options with additional parameters for the action. See Options.

Example

In the example below, TestCafe scrolls the target container’s bottom right corner into view.

import { Selector } from 'testcafe';
fixture`Scroll Action`
    .page('http://example.com');
test('Scroll the container', async t => {
    const container = Selector('#container');
    await t
        .scroll(container, 'bottomRight');
});

Select Target Elements

Use the selector parameter to identify the target of a DOM event.

You can pass any of the following objects as a selector:

  • A CSS selector string.

    test('My Test', async t => {
    
        // Click will be performed on the first element
        // that matches the CSS selector.
        await t.click('#submit-button');
    });
    
  • A selector.

    import { Selector } from 'testcafe';
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    const lastItem = Selector('.toc-item:last-child');
    
    test('My Test', async t => {
    
        // Click will be performed on the element selected by
        // the 'getLastItem' selector.
        await t.click(lastItem);
    });
    
  • A client-side function that returns a DOM element.

    test('My Test', async t => {
    
        // Click will be performed on the element returned by the function,
        // which is the third child of the document's body.
        await t.click(() => document.body.children[2]);
    });
    
  • A DOM node snapshot.

    import { Selector } from 'testcafe';
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    test('My Test', async t => {
        const topMenuSnapshot = await Selector('#top-menu');
    
        // Click will be performed on the element whose snapshot
        // is specified. This is an element with the '#top-menu' ID.
        await t.click(topMenuSnapshot);
    });
    
  • A Promise returned by a selector.

    import { Selector } from 'testcafe';
    
    const submitButton = Selector('#submit-button');
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    test('My Test', async t => {
    
        // Click will be performed on the element specified by the selector
        // as soon as the promise is resolved.
        await t.click(submitButton());
    });
    

TestCafe waits for the target element to become visible before it executes an action. If this does not happen within the selector timeout, the test fails.

TestCafe cannot interact with background elements. If a different element overlaps the action target, TestCafe waits for this element to disappear. If this does not happen within the selector timeout, TestCafe performs the action with the element on top of the original target. Learn more about stacking and z-index on MDN.

Note

The upload action is an exception to this rule — it does not check the visibility of the target input.

Options

Offset options apply to t.scroll, t.scrollBy and t.scrollIntoView actions.

{
    offsetX: Number,
    offsetY: Number,
}
Parameter Type Description Default
offsetX, offsetY Number Coordinates that define the action’s starting point. If positive, TestCafe calculates coordinates relative to the top-left corner of the target element. If negative, they are calculated relative to the bottom-right corner. Top left corner of the target element

The example below scrolls the element until different corners of the element are visible.

import { Selector } from 'testcafe';
fixture `Scroll Actions`
    .page `http://www.example.com/`;
test('Scroll element into view', async t => {
    const target = Selector('#target');
    await t.scrollIntoView(target);
    // No offset, scrolls until the element's center is visible
    await t.scrollIntoView(target, { offsetX: 1, offsetY: 1 });
    // Scrolls until the top left corner of the element is visible
    await t.scrollIntoView(target, { offsetX: -1, offsetY: -1 });
    // Scrolls until the bottom right corner of the element is visible
});