@percy/selenium-webdriver
Advanced tools
@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.
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();
}
})();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 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 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.
Percy visual testing for Selenium.js.
$ 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('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!
percySnapshot(driver, name[, options])
driver (required) - A selenium-webdriver driver instancename (required) - The snapshot name; must be unique to each snapshotoptions - See per-snapshot configuration options@percy/migrateWe 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.
@percy/seleniumjsIf 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.
@percy/cliIf 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
If you have a previous Percy configuration file, migrate it to the newest version with the
config:migrate command:
$ percy config:migrate
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 instancename (required) - The screenshot name; must be unique to each screenshotoptions (optional) - There are various options supported by percyScreenshot to server further functionality.
sync - Boolean value by default it falls back to false, Gives the processed result around screenshot [From CLI v1.28.0-beta.0+]fullPage - Boolean value by default it falls back to false, Takes full page screenshot [From CLI v1.27.6+]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 xpathignoreRegionSelectors - 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.
{top: 10, right: 10, bottom: 120, left: 10}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
{top: 10, right: 10, bottom: 120, left: 10}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.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
FAQs
Selenium client library for visual testing with Percy
The npm package @percy/selenium-webdriver receives a total of 104,539 weekly downloads. As such, @percy/selenium-webdriver popularity was classified as popular.
We found that @percy/selenium-webdriver demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Socket Research team breaks down a malicious npm package targeting the legitimate DOMPurify library. It uses obfuscated code to hide that it is exfiltrating browser and crypto wallet data.
Security News
ENISA’s 2024 report highlights the EU’s top cybersecurity threats, including rising DDoS attacks, ransomware, supply chain vulnerabilities, and weaponized AI.
Security News
NIST's new password guidelines remove periodic changes and special character requirements, focusing on longer, more secure passwords for better authentication practices.