t.scrollIntoView 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 parent containers of the target element until the element is in the viewport. Can be chained with other TestController methods.

t.scrollIntoView(target [, options]) → this | Promise<any>
Parameter Type Description
target  Function | String | Selector | Snapshot | Promise Identifies the webpage element to scroll to. See Select Target Elements.
options (optional) Object A set of options with additional parameters for the action. See Options.

The following example shows how to use the t.scrollIntoView action to scroll the webpage until the element is in the viewport:

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);
});

Select Target Elements

For actions that target DOM elements, use the selector parameter to identify the desired element.

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());
    });
    

Before executing an action, TestCafe waits for the target element to appear in the DOM and become visible. If this does not happen within the selector timeout, the test fails.

Note that TestCafe cannot interact with page elements under other elements. If the target element is not on top when an action is triggered, TestCafe waits for this element to appear in the foreground. If this does not happen within the selector timeout, the action is performed with an overlaying element. For information on why the target element can be overlaid, see the stacking description in the z-index topic.

note

Upload action is the only method that does not require the target input to be visible. You can also perform the upload action when the input is overlaid.

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
});