Selenium for JavaScript

Adding visual testing to your Selenium JavaScript tests


Covered in this doc

  • Integrating Percy with your Selenium JavaScript tests
  • Installing and importing percySnapshot()
  • Calling and configuring percySnapshot

Package Status Test


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


This is an example using the percySnapshot function. For other examples of selenium-webdriver usage, see the Selenium JS docs.

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('');
    await percySnapshot(driver, 'Google Homepage');

    await driver.get('');
    await percySnapshot(driver, 'Example Site');
  } finally {
    await driver.quit();

Running the code above directly will result in the following logs:

$ node script.js
[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 -- node script.js
[percy] Percy has started!
[percy] Created build #1:[your-project]
[percy] Running "node script.js"
[percy] Snapshot taken "Google Homepage"
[percy] Snapshot taken "Example Site"
[percy] Stopping percy...
[percy] Finalized build #1:[your-project]
[percy] Done!


percySnapshot(driver, 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/selenium-webdriver (@percy/seleniumjs)? 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.


Uninstalling @percy/seleniumjs

If you're coming from the @percy/seleniumjs package, make sure to uninstall that package first before installing this one.

$ npm uninstall @percy/seleniumjs

Now you can safely install @percy/selenium-webdriver and @percy/cli.

Installing @percy/cli

If you're coming from a pre-1.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