Screenshots and Videos

TestCafe allows you to take screenshots and record videos during tests.

Screenshots

TestCafe allows you to take screenshots of the application at any moment during test run, or whenever a test fails. You can use screenshots during the debugging process, to pin-point the reason for test failure.

Important

TestCafe cannot take screenshots and videos of remote browsers.

Prerequisites for Screenshots

Screenshot functionality requires .NET 4.0 or newer installed on Windows machines and an ICCCM/EWMH-compliant window manager on Linux.

Take Screenshots at Arbitrary Moments During Test Run

You can take screenshots at any moment during test run. Use the t.takeScreenshot action to take a screenshot of the entire page, or the t.takeElementScreenshot action to capture a particular element.

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

test('Take a screenshot of a fieldset', async t => {
    await t
        .typeText('#developer-name', 'Peter Parker')
        .click('#tried-test-cafe')
        .typeText('#comments', 'I think TestCafe is awesome!')
        .takeElementScreenshot('#comments')
        .click('#submit-button')
        .takeScreenshot();
});

Take Screenshots When a Test Fails

You can configure TestCafe to automatically take a screenshot whenever a test fails. Use either of the following:

  • the takeOnFails parameter in the -s (--screenshots) command line flag,

    testcafe chrome tests/sample-fixture.js -s takeOnFails=true

  • the takeOnFails parameter of the runner.screenshots API method,

    runner.screenshots({
    takeOnFails: true
});

  • the screenshots.takeOnfails configuration file property.

    {
    "screenshots": {
        "takeOnFails": true
    }
}

Screenshot Options

TestCafe supports the following screenshot options:

Option Type Description Default Value
path String The base directory where screenshots are saved. ./screenshots
takeOnFails Boolean true to take a screenshot whenever a test fails. false
pathPattern String A pattern that defines how TestCafe composes the relative path to a screenshot file. See Screenshot and Video Directories. See Default Path Pattern.
fullPage String true to capture the full page, including content that is not visible due to overflow. false
thumbnails Boolean true to generate a thumbnail for the screenshot true

You can specify screenshot options in either of the following ways:

  • the -s (--screenshots) command line flag,

    testcafe chrome test.js -s path=artifacts/screenshots,fullPage=true,pathPattern=${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png

    Tip

    Enclose parameter values in quotes if they contain spaces. In Windows cmd.exe shell, use double quotes.

  • the options parameter of the runner.screenshots API method,

    runner.screenshots({
    path: 'artifacts/screenshots',
    fullPage: true,
    pathPattern: '${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png'
});

  • the screenshots configuration file property.

    {
    "screenshots": {
        "path": "artifacts/screenshots",
        "fullPage": true,
        "pathPattern": "${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png"
    }
}

Disable Screenshots

You can prevent TestCafe from taking screenshots whenever a test fails or a screenshot action is executed. Use one of the following options:

  • the --disable-screenshots command line flag,

    testcafe chrome tests/sample-fixture.js --disable-screenshots

  • the disableScreenshots option of the runner.run API method,

    runner.run({
    disableScreenshots: true
});

  • the disableScreenshots configuration file property.

    {
    "disableScreenshots": true
}

Record Videos

TestCafe allows you to record videos of test runs.

Important

Video recording is supported in Google Chrome, Mozilla Firefox, and Microsoft Edge (Chromium-based). TestCafe cannot record videos when you run tests in remote browsers.

Prerequisites for Video Recording

You should install the FFmpeg library to record videos.

Do one of the following if TestCafe cannot find the FFmpeg library:

  • Add the FFmpeg installation directory to the system’s PATH environment variable;
  • Specify the path to the FFmpeg executable in the FFMPEG_PATH environment variable or the ffmpegPath parameter in video options;
  • Install the @ffmpeg-installer/ffmpeg package from npm.

Videos are saved in the .mp4 format.

Enable Video Recording

Use either of the following to enable video recording:

  • the --video command line flag,

    testcafe chrome test.js --video artifacts/videos

  • the runner.video API method,

    runner.video('artifacts/videos');

  • the videoPath configuration file property.

    {
    "videoPath": "artifacts/videos"
}

You should provide the base path where TestCafe stores videos to this flag, method or property. See Screenshot and Video Directories for more information.

TestCafe records all the tests and saves the recording of each test in a separate file. To change this behavior, use the failedOnly and singleFile video options.

Note

When you specify the :userProfile or --user-data-dir flag to override the user directory in Chrome and Chromium-based browsers, set the cdpPort property to 9222 to record videos:

testcafe "chrome:emulation:cdpPort=9222 --user-data-dir=/my/user/data" test.js --video artifacts/videos

Basic Video Options

TestCafe supports the following video options:

Option Type Description Default Value
failedOnly Boolean true to record only failed tests; false to record all tests. false
singleFile Boolean true to save the entire recording as a single file; false to create a separate file for each test. false
ffmpegPath String The path to the FFmpeg codec executable. Auto-detected
pathPattern String A pattern that defines how TestCafe composes the relative path to a video file. See Screenshot and Video Directories. See Default Path Pattern.

You can specify video options in either of the following ways:

  • the --video-options command line flag,

    testcafe chrome test.js --video artifacts/videos --video-options singleFile=true,failedOnly=true,pathPattern=${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.mp4

    Tip

    Enclose parameter values in quotes if they contain spaces. In Windows cmd.exe shell, use double quotes.

  • the options parameter of the runner.video API method,

    runner.video('artifacts/videos', {
    singleFile: true,
    failedOnly: true,
    pathPattern: '${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.mp4'
});

  • the videoOptions configuration file property.

    {
    "videoOptions": {
        "singleFile": true,
        "failedOnly": true,
        "pathPattern": "${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.mp4"
    }
}

Video Encoding Options

These encoding options are passed to FFmpeg. Refer to the FFmpeg documentation for information about all the available options.

To provide video encoding options, use either of the following options:

  • the --video-encoding-options command line flag,

    testcafe chrome test.js --video artifacts/videos --video-encoding-options r=20,aspect=4:3

  • the encodingOptions parameter of the runner.video API method,

    runner.video('artifacts/videos', { }, {
    r: 20,
    aspect: '4:3'
});

  • the videoEncodingOptions configuration file property.

    {
    "videoEncodingOptions": {
        "r": 20,
        "aspect": "4:3"
    }
}

Screenshot and Video Directories

Base Directory

Screenshots

The default base directory for screenshots is <project>/screenshots.

You can use the path option to specify a different base directory:

CLI

testcafe chrome test.js -s path=artifacts/screenshots

API

runner.screenshots({
    path: 'artifacts/screenshots'
});

Configuration file

{
    "screenshots": {
        "path": "artifacts/screenshots"
    }
}

Videos

The base directory for video files must be specified in order to enable video recording:

CLI

testcafe chrome test.js --video artifacts/videos

API

runner.video('artifacts/videos');

Configuration file

{
    "videoPath": "artifacts/videos"
}

Subdirectories and File Names

Inside the base directory, screenshots and videos are organized into subdirectories and named according to the path patterns.

Path Patterns

A path pattern is a template for relative paths to individual screenshot or video files. The pattern uses placeholders to define positions where TestCafe should insert values like date, time or browser name.

The following example shows a path pattern for screenshot files:

${DATE}_${TIME}/${BROWSER}/screenshot-${FILE_INDEX}.png

When TestCafe saves a screenshot or video file, it substitutes each placeholder with an actual value. For instance, the pattern shown above forms the following paths:

2019-10-02_11-35-40/Chrome/screenshot-1.png
2019-10-02_11-35-40/Chrome/screenshot-2.png
2019-10-02_11-35-40/Firefox/screenshot-1.png
2019-10-02_11-35-40/Firefox/screenshot-2.png

You can use the default or custom path pattern.

Note

When you take a screenshot with the t.takeScreenshot or t.takeElementScreenshot action, you can specify the exact file path. In this instance, TestCafe saves this screenshot to the specified location and does not use patterns.

Default Path Pattern

TestCafe composes paths to screenshots and videos according to the following pattern:

${DATE}_${TIME}/${TEST_ID}/${RUN_ID}/${USERAGENT}/${FILE_INDEX}.<ext>

where <ext> is .png for screenshots and .mp4 for videos.

When TestCafe takes a screenshot because a test fails, it adds the errors subfolder to the pattern.

${DATE}_${TIME}/${TEST_ID}/${RUN_ID}/${USERAGENT}/errors/${FILE_INDEX}.png

Custom Path Patterns

You can create a custom path pattern for screenshots and videos. Use placeholders to define which values should be used in relative paths.

To specify a custom pattern, use the pathPattern parameter in screenshot or video options.

testcafe chrome test.js -s pathPattern=${DATE}_${TIME}/test-${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png

runner.video('artifacts/videos', {
    pathPattern: '${DATE}_${TIME}/test-${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.mp4'
});

Path Pattern Placeholders

You can use the following placeholders in screenshot and video path patterns:

Placeholder Description
${DATE} The test run’s start date (YYYY-MM-DD).
${TIME} The test run’s start time (HH-mm-ss).
${TEST_INDEX} The test’s index.
${FILE_INDEX} The screenshot file’s index.
${QUARANTINE_ATTEMPT} The ordinal number of the test attempt (defaults to 1 if quarantine mode is disabled)
${FIXTURE} The fixture’s name.
${TEST} The test’s name.
${USERAGENT} The combination of ${BROWSER}, ${BROWSER_VERSION}, ${OS}, and ${OS_VERSION} (separated by underscores).
${BROWSER} The browser’s name.
${BROWSER_VERSION} The browser’s version.
${OS} The operation system’s name.
${OS_VERSION} The operation system’s version.
${TEST_ID} Resolves to test-${TEST_INDEX} if TestCafe can associate this screenshot or video with a specific test; resolves to an empty string otherwise (for instance, when a single video is recorded for the entire test run).
${RUN_ID} Resolves to run-${QUARANTINE_ATTEMPT} for screenshots taken when quarantine mode is enabled; resolves to an empty string for videos and for screenshots taken when quarantine mode is disabled.