Covered in this doc
Integrating Percy with your TestCafe tests
Installing and importing@percy/testcafe
Calling and configuringawait percySnapshot()
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 tofalse
.
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!
Updated about a month ago