t.takeElementScreenshot Method

Takes a screenshot of the specified page element.

t.takeElementScreenshot(selector[, path][, options])
Parameter Type Description
selector Function | String | Selector | Snapshot | Promise Identifies the webpage element whose screenshot should be taken. See Select Target Elements.
path (optional) String The screenshot file's relative path and name. The path is relative to the root directory specified in the runner.screenshots API method or the -s (--screenshots) command line option. This path overrides the relative path the default or custom path patterns specify.
options (optional) Object Options that define how the screenshot is taken. See details below.

The example below demonstrates how to use t.takeElementScreenshot action.

import { Selector } from 'testcafe';

fixture `My fixture`
    .page `http://devexpress.github.io/testcafe/example/`;

test('Take a screenshot of a fieldset', async t => {
    await t
        .click('#reusing-js-code')
        .click('#continuous-integration-embedding')
        .takeElementScreenshot(Selector('fieldset').nth(1), 'my-fixture/important-features.png');
});

The options object contains the following properties:

Property Type Description Default
scrollTargetXscrollTargetY Number If the target element is too big to fit into the browser window, the page is scrolled to put this point to the center of the viewport. The coordinates of this point are calculated relative to the target element. If the numbers are positive, the point is positioned relative to the top-left corner of the element. If the numbers are negative, the point is positioned relative to the bottom-right corner. If the target element fits into the browser window, these properties have no effect. The center of the element. If the crop rectangle is specified, its center. If the crop rectangle is larger than the viewport, the center of the viewport.
includeMargins Boolean Specifies whether to include target element's margins in the screenshot. When it is enabled, the scrollTargetX, scrollTargetY and crop rectangle coordinates are calculated from the corners where top and left (or bottom and right) margins intersect. false
includeBorders Boolean Specifies whether to include target element's borders in the screenshot. When it is enabled, the scrollTargetX, scrollTargetY and crop rectangle coordinates are calculated from the corners where top and left (or bottom and right) internal edges of the element intersect. true
includePaddings Boolean Specifies whether to include target element's paddings in the screenshot. When it is enabled, the scrollTargetX, scrollTargetY and crop rectangle coordinates are calculated from the corners where top and left (or bottom and right) edges of the element's content area intersect. true
crop Object Allows you to crop the target element on the screenshot. Crops to the whole element or, if it does not fit into the viewport, its visible part.

An object assigned to the crop property has the following fields.

Field Type Description
top Number The top edge of the cropping rectangle. The coordinate is calculated from the element's top edge. If a negative number is passed, the coordinate is calculated from the element's bottom edge.
left Number The left edge of the cropping rectangle. The coordinate is calculated from the element's left edge. If a negative number is passed, the coordinate is calculated from the element's right edge.
bottom Number The bottom edge of the cropping rectangle. The coordinate is calculated from the element's top edge. If a negative number is passed, the coordinate is calculated from the element's bottom edge.
right Number The right edge of the cropping rectangle. The coordinate is calculated from the element's left edge. If a negative number is passed, the coordinate is calculated from the element's right edge.

Crop Rectangle

Example

fixture `My fixture`
    .page `http://www.example.com/`;

test('Take a screenshot of my new avatar', async t => {
    await t
        .click('#change-avatar')
        .setFilesToUpload('#upload-input', 'img/portrait.jpg')
        .click('#submit')
        .takeElementScreenshot('#avatar', {
            includeMargins: true,
            crop: {
                top: -100,
                left: 10,
                bottom: 30,
                right: 200
            }
        });
});

You can take a screenshot of the entire page with the t.takeScreenshot method.

See Screenshots and Videos for more information on taking screenshots.

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.

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.