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
TestCafe supports video recording 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 theffmpegPath
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. |