Integrate your Selenium JavaScript tests with Percy

Integrate Percy with your test suite to run visual tests. To do that, follow these steps:

export PERCY_TOKEN="<your token here>"

$Env:PERCY_TOKEN="<your token here>"

set PERCY_TOKEN="<your token here>"

npm install --save-dev @percy/cli

npm install @percy/selenium-webdriver

const { Builder } = require('selenium-webdriver');
const percySnapshot = require('@percy/selenium-webdriver');
(async function example() {
  let driver = await new Builder().forBrowser('firefox').build();
  try {
    await driver.get('https://google.com/');
    await percySnapshot(driver, 'Google Homepage');
    await driver.get('http://example.com/');
    await percySnapshot(driver, 'Example Site');
  } finally {
    await driver.quit();
  }
})();

percySnapshot(driver, name[, options])

$ npx percy exec -- node script.js

[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Snapshot taken "JavaScript example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

Congratulations!

You have successfully created your first build on Percy. To see the build with snapshots of your application, visit your project in Percy.

When you run another build with visual changes to your application, Percy takes new snapshots. You can then see the comparisons between the two runs on the new build.

Advanced topics

Percy Snapshot command

In the preceding steps, we used the Percy Snapshot command for capturing snapshots. Percy provides various configurations to use with Percy snapshot command. To learn more visit, Percy snapshot command.

Base build selection

By default, Percy uses the previous build for comparison however, you always have the option to configure the base build for comparison as needed. To learn more, visit base build selection logic.

Related topics

• Simplify Percy CLI setup with executables
• Migrate to Percy CLI
• Snapshot vs Screenshot
• CI/CD

Before you begin, ensure your Automate script’s capabilities are using Selenium version 3.11.0 and above.

Integrate Percy on Automate with your test suite to run visual tests. To do that, follow these steps:

Step 1 - Install the latest Percy CLI

npm install --save @percy/cli

Step 2 - Install the SDK

For Javascript-based frameworks like WebdriverIO, or Mocha

npm install @percy/selenium-webdriver@2.0.1

Step 3 - In the Percy dashboard make selections as below:

• Select Web as the platform.
• Select Automate to handle browser selection.
• Click Create Project.

Step 4 - Export the Percy token.

A Percy token is generated when you create a project. Export this token environment variables.

export PERCY_TOKEN="<your token here>"

set PERCY_TOKEN="<your token here>"

$Env:PERCY_TOKEN="<your token here>"

Step 5 - Update your Automate test script.

(1) Import percy_screenshot from Percy library using the below code:

const { percyScreenshot } = require('@percy/selenium-webdriver');

(2) Use the Percy screenshot command to take required screenshots in your Automate session.

For example, in the following Javascript code, the percyScreenshot("name", "options") method is called twice. In the first instance, we are passing only the required argument which is “name”. In the second instance, we are passing both the required and optional “options”.

await percyScreenshot(driver, 'Screenshot 1');
options = { percyCSS: 'h1{color:red;} a{color: red;font-size: 1rem;}', ignore_region_xpaths: ['/html/body/div/p[2]/a']}
await percyScreenshot(driver, 'Screenshot 2', options);
// Full page screenshot 
options = { fullPage: true, percyCSS: 'h1{color:red;} a{color: red;font-size: 1rem;}' }
await percyScreenshot(driver, 'Screenshot 3', options);

(3) Add the browser capabilities to your test script

We recommend running your build using a single browser like Chrome or Firefox, to begin with. Once you have achieved stability with Chrome or Firefox, you can set up cross-browser testing.

// Add the following capabilities to your test script
const capabilities = {
  'bstack:options': {
    os: 'Windows',
    osVersion: '10'
  },
  browserName: 'Chrome',
  browserVersion: 'latest'
};

// Add these capabilities to your test script
const capabilities = {
  os: 'Windows',
  os_version: '10',
  browserName: 'Chrome',
  browser_version: 'latest'
};

Step 6 - Run the build

npx percy exec -- <command to run the automate script file>