Skip to content

Selenium.js client library for visual regression testing with Percy

License

Notifications You must be signed in to change notification settings

percy/percy-selenium-js

Repository files navigation

@percy/selenium-webdriver

Version Test

Percy visual testing for Selenium.js.

Installation

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

Usage

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('http://google.com/');
    await percySnapshot(driver, 'Google Homepage');

    await driver.get('http://example.com/');
    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: https://percy.io/[your-project]
[percy] Running "node script.js"
[percy] Snapshot taken "Google Homepage"
[percy] Snapshot taken "Example Site"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

Configuration

percySnapshot(driver, name[, options])

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/selenium-webdriver (@percy/seleniumjs)? Yes
? Install @percy/cli (required to run percy)? Yes
? Migrate Percy config file? Yes
? Upgrade SDK to @percy/selenium-webdriver@1.0.0? Yes

This will automatically run the changes described below for you.

Manually

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

Running Percy on Automate

percyScreenshot(driver, name, options) [ needs @percy/cli 1.27.0-beta.0+ ];

This is an example test using the percyScreenshot method.

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

(async function example() {
const driver = new webdriver.Builder().usingServer('https://hub-cloud.browserstack.com/wd/hub').withCapabilities(capabilities).build(); // pass automate capabilities

  try {
    await driver.get('http://google.com/');
    await percyScreenshot(driver, 'Screenshot 1');

    await driver.get('http://example.com/');
    await percyScreenshot(driver, 'Screenshot 2');
  } finally {
    await driver.quit();
  }
})();
  • driver (required) - A Selenium driver instance
  • name (required) - The screenshot name; must be unique to each screenshot
  • options (optional) - There are various options supported by percyScreenshot to server further functionality.
    • freezeAnimation - Boolean value by default it falls back to false, you can pass true and percy will freeze image based animations.
    • percyCSS - Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.
    • ignoreRegionXpaths - elements in the DOM can be ignored using xpath
    • ignoreRegionSelectors - elements in the DOM can be ignored using selectors.
    • ignoreRegionSeleniumElements - elements can be ignored using selenium_elements.
    • customIgnoreRegions - elements can be ignored using custom boundaries
      • IgnoreRegion:-
        • Description: This class represents a rectangular area on a screen that needs to be ignored for visual diff.

        • Constructor:

          init(self, top, bottom, left, right)
          
        • Parameters: top (int): Top coordinate of the ignore region. bottom (int): Bottom coordinate of the ignore region. left (int): Left coordinate of the ignore region. right (int): Right coordinate of the ignore region.

        • Raises:ValueError: If top, bottom, left, or right is less than 0 or top is greater than or equal to bottom or left is greater than or equal to right.

        • valid: Ignore region should be within the boundaries of the screen.

Creating Percy on automate build

Note: Automate Percy Token starts with auto keyword. The command can be triggered using exec keyword.

$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- [js test command]
[percy] Percy has started!
[percy] [Javascript example] : Starting automate screenshot ...
[percy] Screenshot taken "Javascript example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

Refer to docs here: Percy on Automate