@percy/selenium-webdriver

What is @percy/selenium-webdriver?

@percy/selenium-webdriver is an npm package that integrates Percy visual testing with Selenium WebDriver. It allows you to capture screenshots of your web application during Selenium tests and compare them against baseline images to detect visual changes.

What are @percy/selenium-webdriver's main functionalities?

Initialize Percy

This feature allows you to initialize Percy within a Selenium WebDriver test. The code sample demonstrates how to set up a Selenium WebDriver instance, navigate to a webpage, and capture a Percy snapshot.

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://example.com');
    await percySnapshot(driver, 'Example Snapshot');
  } finally {
    await driver.quit();
  }
})();

Capture Multiple Snapshots

This feature allows you to capture multiple snapshots within a single test session. The code sample demonstrates navigating to different pages and capturing snapshots for each page.

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://example.com/page1');
    await percySnapshot(driver, 'Page 1 Snapshot');

    await driver.get('http://example.com/page2');
    await percySnapshot(driver, 'Page 2 Snapshot');
  } finally {
    await driver.quit();
  }
})();

Custom Snapshot Options

This feature allows you to customize snapshot options such as widths and minimum height. The code sample demonstrates capturing a snapshot with specific widths and minimum height settings.

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://example.com');
    await percySnapshot(driver, 'Custom Snapshot', { widths: [375, 768, 1280], minHeight: 1024 });
  } finally {
    await driver.quit();
  }
})();

Other packages similar to @percy/selenium-webdriver

webdriverio

WebdriverIO is a popular WebDriver binding for Node.js. It provides a high-level API to control a browser or mobile application with Selenium WebDriver. Unlike @percy/selenium-webdriver, WebdriverIO has built-in support for visual regression testing through plugins like wdio-visual-regression-service.

cypress

Cypress is a JavaScript end-to-end testing framework that does not rely on Selenium. It offers a rich set of features for writing and running tests, including visual testing capabilities through plugins like cypress-image-snapshot. Cypress provides a more integrated and developer-friendly experience compared to @percy/selenium-webdriver.

puppeteer

Puppeteer is a Node library that provides a high-level API to control Chrome or Chromium over the DevTools Protocol. It is often used for web scraping, automated testing, and generating screenshots. Puppeteer can be combined with visual testing tools like Percy or jest-image-snapshot for visual regression testing, similar to @percy/selenium-webdriver.

README

@percy/selenium-webdriver

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])

• driver (required) - A selenium-webdriver driver instance
• name (required) - The snapshot name; must be unique to each snapshot
• options - See per-snapshot configuration 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.
  • freezeAnimatedImage - Boolean value by default it falls back to false, you can pass true and percy will freeze image based animations.
  • freezeImageBySelectors - List of selectors. Images will be freezed which are passed using selectors. For this to work freezeAnimatedImage must be set to true.
  • freezeImageByXpaths - List of xpaths. Images will be freezed which are passed using xpaths. For this to work freezeAnimatedImage must be set to true.
  • percyCSS - Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.
  • ignoreRegionXpaths - List of xpaths. elements in the DOM can be ignored using xpath
  • ignoreRegionSelectors - List of selectors. elements in the DOM can be ignored using selectors.
  • ignoreRegionSeleniumElements - List of selenium web-element. elements can be ignored using selenium_elements.
  • customIgnoreRegions - List of custom objects. elements can be ignored using custom boundaries. Just passing a simple object for it like below.
    • example: {top: 10, right: 10, bottom: 120, left: 10}
    • In above example it will draw rectangle of ignore region as per given coordinates.
      • 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.
  • considerRegionXpaths - List of xpaths. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using xpaths.
  • considerRegionSelectors - List of selectors. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using selectors.
  • considerRegionSeleniumElements - List of selenium web-element. elements can be considered for diffing and will be ignored by Intelli Ignore using selenium_elements.
  • customConsiderRegions - List of custom objects. elements can be considered for diffing and will be ignored by Intelli Ignore using custom boundaries
    • example: {top: 10, right: 10, bottom: 120, left: 10}
    • In above example it will draw rectangle of consider region will be drawn.
    • Parameters:
      • top (int): Top coordinate of the consider region.
      • bottom (int): Bottom coordinate of the consider region.
      • left (int): Left coordinate of the consider region.
      • right (int): Right coordinate of the consider region.

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