Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Set TestCafe’s screenshot root with screenshots.path. Use the CLI setting -s path=artifacts/screenshots, put "path": "artifacts/screenshots" in the configuration file’s screenshots object, or pass { path: 'artifacts/screenshots' } to the Runner API. Use pathPattern separately if you also need to control filenames or subdirectories.
Choose where to set the screenshot directory
TestCafe provides three configuration surfaces for the screenshot root: the command line, a configuration file, and the Runner API. Choose the one your test run already uses. The same setting is called screenshots.path in configuration and path in the CLI settings and Runner options.
In the examples below, artifacts/screenshots is the destination path. Replace it with the directory you want to use. A relative path is convenient for a project-local output folder; use an absolute path when you want to specify the destination without relying on a relative location.
Set the directory on the command line
Pass the official --screenshots option, or its short form -s, followed by comma-separated settings:
testcafe chrome tests -s path=artifacts/screenshotsThis changes the screenshot base directory for that invocation. To also capture screenshots when a test fails, include takeOnFails=true:
testcafe chrome tests -s path=artifacts/screenshots,takeOnFails=trueIf you need a custom directory structure and filename pattern, add pathPattern. Quote the setting so the shell passes the pattern as one argument:
testcafe chrome tests -s 'path=artifacts/screenshots,pathPattern=${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png'Shell quoting conventions differ, so adjust the quotes if your shell requires a different form. The important distinction is that path selects the root and pathPattern selects the relative layout beneath it.
Free tools Windows power users keep installed
One-click scans. No signup required.
Set the directory in a configuration file
Use the nested screenshots object in your TestCafe configuration:
{
"screenshots": {
"path": "artifacts/screenshots",
"takeOnFails": true,
"pathPattern": "${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png"
}
}The relevant documented options include screenshots.path, screenshots.takeOnFails, screenshots.pathPattern, screenshots.pathPatternOnFails, screenshots.fullPage, and screenshots.thumbnails. You do not need to specify all of them to change the directory; path alone is sufficient.
Older top-level properties such as screenshotPath and screenshotPathPattern are deprecated. For new or updated configuration, use the nested screenshots properties instead.
Set the directory with the Runner API
If your code creates a TestCafe Runner, pass the screenshot settings to its screenshots() method:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsrunner
.screenshots({
path: 'artifacts/screenshots',
takeOnFails: true,
pathPattern: '${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png'
});The Runner API documents ./screenshots as the default base path. Set path to replace that default, and add pathPattern only when the default relative naming layout is not suitable.
Separate the screenshot root from the filename pattern
A common source of confusion is treating the destination directory and the screenshot path pattern as the same setting. They control different parts of the output path:
Rank #4
path(orscreenshots.path) sets the base directory.pathPatternsets the relative path and filename pattern used within that base.pathPatternOnFailslets failure screenshots use a separate pattern.
For example, path: 'artifacts/screenshots' chooses the root. A pattern such as ${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png then specifies a nested layout and a PNG filename. If the default layout already works for your project, set only the root rather than adding a pattern without a need.
When both pathPattern and pathPatternOnFails are set, the failure-specific pattern takes precedence for failure screenshots. This is useful when you want failed-test images separated from the regular screenshot layout.
Recommended Free Tools
Capture an individual screenshot during a test
Runner-level screenshot settings configure the root and screenshot behavior for the run. To take a screenshot at a particular point in a test, use the TestController action t.takeScreenshot(). Give its path a path relative to the configured screenshot root:
Best Value
await t.takeScreenshot({
path: 'checkout.png',
fullPage: true
});Here, checkout.png is the individual screenshot’s path beneath the configured root. To capture a particular element instead of the page, use t.takeElementScreenshot. Configure the root through the CLI or Runner screenshot settings, and use the test action’s path to name or place that individual capture.
Configure screenshots on test failure
To capture screenshots when tests fail, set takeOnFails to true in the CLI settings or configuration file. For example, in the CLI:
testcafe chrome tests -s path=artifacts/screenshots,takeOnFails=trueFor a configuration file, put "takeOnFails": true alongside "path" inside "screenshots". If you want a different output layout for those images, specify pathPatternOnFails. When that failure-specific pattern is present along with pathPattern, TestCafe uses the failure-specific one for failure screenshots.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Understand which setting takes precedence
The CLI and Runner options take precedence over values from a configuration file. If a configured path appears to have no effect, check whether the command that launches TestCafe or the Runner code sets its own screenshot options. To keep the result predictable, choose one place to own the setting where practical, or deliberately set the more specific CLI or Runner value when it should override the file.
The syntax varies by interface: use -s path=... on the CLI, screenshots.path in configuration, and path in the Runner options object. These are equivalent ways of setting the root, not separate output directories that need to be combined.
Troubleshoot a screenshot path that is not what you expect
- The screenshot still uses the old location: Check for a CLI
-soption or Runnerscreenshots()call overriding the configuration file. CLI and Runner values take precedence over configuration-file values. - The directory is right but the filename or folders are wrong: Set or revise
pathPattern. The root and the relative path pattern are separate controls. - Failure images use a different layout: Check whether
pathPatternOnFailsis configured. When both patterns are set, the failure-specific one takes precedence for failure screenshots. - Failure screenshots are missing: Confirm
takeOnFailsis enabled in the active CLI settings or configuration. Also check that a higher-precedence Runner or CLI setting has not changed the effective options. - An older configuration property is in use: Replace top-level
screenshotPathorscreenshotPathPatternwith the corresponding property inside thescreenshotsobject. - An individual test capture is misplaced: Check the path supplied to
t.takeScreenshot()and remember that it is relative to the configured screenshot root. Uset.takeElementScreenshotif the intended capture is an element rather than the page. - The CLI command fails after adding a pattern: Check the quoting for your shell. The example quotes the complete settings string so the pattern is passed together with the root setting.
Or skip the browser setup
TestCafe’s settings are the right choice when the screenshots need to be part of a TestCafe run and saved under that run’s configured screenshot root. If you instead need to capture a page by URL without setting up a browser automation run, ScreenshotNeo offers a website screenshot API and MCP server. It returns a PNG, JPEG, WebP, or PDF from a GET request; it does not configure TestCafe’s local screenshot directory.
Quick Recap
For example, save a WebP response with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for API parameters. Cookie and consent banners are accepted before capture, and more than 60 known consent platforms, newsletter popups, and chat widgets are removed; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server exposes screenshot and PDF capture tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
