Screenshots and Videos

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

• Take screenshots
• Record videos
• Screenshot and video storage configuration

Take screenshots

TestCafe allows you to take screenshots of the application at any moment during the test run, or whenever a test fails. Screenshots can help you debug your application, and pinpoint the reason for test failure.

• Take screenshots during the test run
  • t.takeScreenshot options
  • t.takeElementScreenshot options
• Take screenshots when a test fails
• Global screenshot settings
• Disable screenshots

Prerequisites for screenshots

Screenshot functionality requires .NET v4.0 or higher on Windows machines and an ICCCM/EWMH-compliant window manager on Linux.

Take screenshots during the test run

You can take screenshots at any moment during the test run. Use the t.takeScreenshot action to take a screenshot of the entire window, or the t.takeElementScreenshot action to capture a specific 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();
});

t.takeScreenshot options

The t.takeScreenshot method allows you to configure the screenshot file location and the size of the capture area:

t.takeScreenshot({
    path: 'screenshots/checkout-screenshot.png',
    fullPage: true
})

• The pathPattern option determines the custom naming pattern for the screenshot file. This option overrides the global pathPattern setting.
• The path option determines the relative location of the screenshot file. Set the root directory with the runner.screenshots method or the -s (--screenshots) CLI option. This option overrides the pathPattern parameter.
• The fullPage option enables you to capture the entire page, including the area outside the viewport.

t.takeElementScreenshot options

The t.takeElementScreenshot method allows you to configure the screenshot’s capture settings and file location. Read the API Reference article for more information.

fixture`TestController.takeElementScreenshot`
    .page`https://testcafe.io/`;

test('Take a screenshot of image piece', async t => {
    await t
        .takeElementScreenshot('.checkout-cart', 'screenshots/checkout-screenshot.png', {
            includeMargins: true,
            crop:           {
                top:    -100,
                left:   10,
                bottom: 30,
                right:  200,
            },
        });
});

Take screenshots when a test fails

TestCafe can take a screenshot whenever a test fails. Use one of the following interfaces to enable this capability:

• CLI (--screenshots takeOnFails=true)

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

• Test Runner API (runner.screenshots ({ takeonfails }))

  runner.screenshots({
      takeOnFails: true
  });
  

• Configuration file (screenshots.takeOnfails)

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

Global screenshot settings

Use one of the following interfaces to specify screenshot settings:

• CLI (-s (--screenshots))

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

  Important

  Enclose parameter values in single quotes when you use a *NIX shell or PowerShell, and double quotes for cmd.exe.

• Test Runner API (runner.screenshots())

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

• Configuration file (screenshots)

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

Disable screenshots

Use the disableScreenshots option to turn off the framework’s capability to take screenshots, even if you configured the framework to take screenshots on test failure, or your test code includes screenshot actions.

• CLI (--disable-screenshots)

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

• Test Runner API (runner.run({ disableScreenshots }))

  runner.run({
      disableScreenshots: true
  });
  

• Configuration File (disableScreenshots)

  {
      "disableScreenshots": true
  }
  

Record videos

TestCafe allows you to record videos of test runs.

• Prerequisites for video recording
• Enable video recording
• Basic video options
• Video encoding options

Prerequisites for video recording

Install the FFmpeg library to record videos.

If TestCafe cannot find the FFmpeg library, try one of the following fixes:

• 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.
• Specify the path to the FFmpeg executable in the ffmpegPath option.
• Install the @ffmpeg-installer/ffmpeg npm package.

TestCafe saves videos in .mp4 format.

Enable video recording

Use one of the following interfaces to enable video recording:

• CLI (--video)

  testcafe chrome test.js --video artifacts/videos
  

• Test Runner API (runner.video())

  runner.video('artifacts/videos');
  

• Configuration file (videoPath)

  {
      "videoPath": "artifacts/videos"
  }
  

Always specify the video storage directory. See Screenshot and Video Storage Configuration for more information.

When you enable video recording, TestCafe records each test individually, and saves each recording as a separate file. You can change this behavior with the failedOnly and singleFile video options.

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:

Use one of the following interfaces to configure your video recordings:

• CLI (--video-options)

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

  Important

  Enclose parameter values in single quotes if you use a *NIX shell or PowerShell, and double quotes for cmd.exe.

• Test Runner API (runner.video())

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

• Configuration file (videoOptions)

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

Video encoding options

Specify video encoding options to configure FFmpeg. Refer to the FFmpeg documentation for the full list of available options.

Use one of the following interfaces to configure FFmpeg:

• CLI (--video-encoding-options)

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

• Test Runner API (runner.video())

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

• Configuration file (videoEncodingOptions)

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

Screenshot and video storage configuration

• Base directory
  • Screenshots
  • Videos
• Path patterns
  • Default path patterns
  • Custom path patterns
    • Specify a path pattern for screenshots taken on test failure
  • Path Pattern Placeholders

Base directory

Screenshots

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

Use the path setting 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

Include the path to the video storage directory when you enable video recording.

CLI

testcafe chrome test.js --video artifacts/videos

API

runner.video('artifacts/videos');

Configuration file

{
    "videoPath": "artifacts/videos"
}

Path patterns

TestCafe uses path patterns to place your test artifacts in appropriate subfolders, and give each file a meaningful name. Placeholder variables allow TestCafe to create file paths with dynamic content, such as the name of the browser or the current date.

TestCafe resolves path patterns against the base directory.

For example, if you use the following path pattern:

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

TestCafe organizes your screenshots as follows:

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 path pattern or create a custom path pattern.

Default path pattern

TestCafe uses the following path pattern out of the box:

${DATE}_${TIME}/${TEST_ID}/${RUN_ID}/${USERAGENT}/${FILE_INDEX}.<ext>
# <ext> indicates the file's extension ('.png' for screenshots and '.mp4' for videos).

When TestCafe takes a screenshot on test failure, it adds the errors subfolder to the pattern.

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

Custom path patterns

Use the pathPattern parameter to specify a custom path pattern:

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

t.takeScreenshot({
    pathPattern: '${DATE}_${TIME}/${TEST_ID}/${RUN_ID}/${USERAGENT}/errors/${FILE_INDEX}.png',
    fullPage: true
})

Specify a path pattern for screenshots taken on test failure

Set the pathPatternOnFails option to define a separate naming pattern for screenshots taken on test failure. You can use this option on its own, or in conjunction with the pathPattern option.

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

Path pattern placeholders

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