percy-testcafe on GitHub

Setup

---

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

Install @percy/testcafe using npm:

npm install --save-dev @percy/testcafe

Or using yarn:

yarn add --dev @percy/testcafe

Step 1: In order to start creating snapshots from your TestCafe tests, you'll need to import the @percy/testcafe package into your test.

// At the top of your test file
import percySnapshot from '@percy/testcafe';

Step 2: You can now incorporate visual tests in your existing suite:

import percySnapshot from "@percy/testcafe";

test("Create todo", async test => {
  await test
    .typeText(todoPage.input, "Integrate with Percy")
    .pressKey("enter");

  await percySnapshot(test, "Created a todo");
});

Step 3: Finally, wrap your test runner command in the percy exec command. This will start a Percy agent to receive snapshots from your TestCafe tests and upload them to your Percy dashboard. If you are running your tests with testcafe & Chrome, your new test command becomes percy exec -- testcafe chrome tests/.

Before you can successfully run Percy, the PERCY_TOKEN environment variable must be set:

# Windows
set PERCY_TOKEN=[your-projects-token]

# Unix 
export PERCY_TOKEN=[your-projects-token]

Now you can run percy exec:

percy exec -- testcafe chrome tests/

Note the double dash, --, between percy exec and your test run command.

That's it! Now, whenever you run your tests with Percy, a snapshot of the app in that state will be uploaded to Percy for visual regression testing!

Configuration

---

await percySnapshot(test, snapshotName);
await percySnapshot(test, snapshotName, options);

test is the TestCafe test instance
snapshotName is a required string that will be used as the snapshot name.
options is an optional hash that can include:

• widths: An array of integers representing the browser widths at which you want to take snapshots.
• minHeight: An integer specifying the minimum height of the resulting snapshot, in pixels. Defaults to 1024px.
• percyCSS: A string containing Percy specific CSS that will be applied to this snapshot.
• requestHeaders: An object containing HTTP headers to be sent for each request made during asset discovery for this snapshot.
• enableJavaScript: A boolean to enable JavaScript execution in our rendering environment. Defaults to false.

For example:

await percySnapshot(test, 'Home page');
await percySnapshot(test, 'Homepage responsive test', { widths: [768, 992, 1200] });

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!