👍

Covered in this doc

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

percy-testcafe on GitHub

Installation

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

Usage

This is an example test using the percySnapshot function.

import percySnapshot from '@percy/testcafe';

fixture('MyFixture')
  .page('http://devexpress.github.io/testcafe/example');

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 ...

 MyFixture
[percy] Snapshot taken "TestCafe Example"
 ✓ Test1

 1 passed (1s)

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

Configuration

percySnapshot(t, name[, options])

• t(required) - The test controller instance passed from test
• name (required) - The snapshot name; must be unique to each snapshot
• options - Additional snapshot options (overrides any project options)
  • options.widths - An array of widths to take screenshots at
  • options.minHeight - The minimum viewport height to take screenshots at
  • options.percyCSS - Percy specific CSS only applied in Percy's rendering environment
  • options.requestHeaders - Headers that should be used during asset discovery
  • options.enableJavaScript - Enable JavaScript in Percy's rendering environment

Upgrading

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.

Manually

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

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.

Troubleshooting

---

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 192.100.68.3  -- 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!