Integrating Percy with your TestCafe tests


Covered in this doc

  • Integrating Percy with your TestCafe tests
  • Installing and importing @percy/testcafe
  • Calling and configuring await percySnapshot()

Package Status Test


If you're not ready to integrate Percy, check out our 2-minute TestCafe tutorial and example app with Percy for TestCafe already added.

$ npm install --save-dev @percy/cli @percy/testcafe


This is an example test using the percySnapshot function.

import percySnapshot from '@percy/testcafe';


test('Test1', async t => {
  await t.typeText('#developer-name', 'John Doe');
  await percySnapshot(t, 'TestCafe Example');

Running the test above normally will result in the following log:

[percy] Percy is not running, disabling snapshots

When running with percy exec, and your project's PERCY_TOKEN, a new Percy build will be created and snapshots will be uploaded to your project.

$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- testcafe chrome:headless tests
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Running "testcafe chrome:headless tests"

 Running tests in:
 - Chrome ...

[percy] Snapshot taken "TestCafe Example"
 ✓ Test1

 1 passed (1s)

[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!


percySnapshot(t, name[, options])

Global configuration

You can also configure Percy to use the same options over all snapshots. To see supported configuration including widths read our SDK configuration docs.


Automatically with @percy/migrate

We built a tool to help automate migrating to the new CLI toolchain! Migrating can be done by running the following commands and following the prompts:

$ npx @percy/migrate
? Are you currently using @percy/testcafe? Yes
? Install @percy/cli (required to run percy)? Yes
? Migrate Percy config file? Yes
? Upgrade SDK to @percy/[email protected]? Yes

This will automatically run the changes described below for you.


Installing @percy/cli

If you're coming from a pre-2.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

$ npm install --save-dev @percy/cli

Migrating Config

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

$ percy config:migrate


Missing assets from snapshots

If your snapshots end up missing assets, it is possible your sites asset URLs are being changed by TestCafe. TestCafe will proxy remote assets by prepending your computers local IP to the URL. See this GitHub issue for more details.

To work around this, you can add your computers IP to the list of hostnames Percy will capture assets from. This is done by passing a -h flag to the exec command:

percy exec -h  -- testcafe chrome tests/

This will now properly capture the asset and render correctly in Percy. If this doesn't solve your issues, please reach out to support!