Integrate your Selenium JavaScript tests with Percy
A guide to integrating your Selenium JavaScript automated tests with BrowserStack Percy. Catch visual differences in your web application on time.
Percy SDK offers the following integrations for your Playwright tests:
- Percy Web
- Percy with Automate
Choose Percy if you want to perform visual tests solely on the newest browsers. Choose Automate if you want to run visual tests on a range of desktop, mobile, and browser combinations.
To establish this integration, choose the appropriate variant and refer to the following section accordingly:
We recommend using our BrowserStack SDK for Percy integration.
Integrate Percy with your test suite to run visual tests. To do that, follow these steps:
Create a Percy project
Sign in to Percy. In Percy, create a project of the type, Web, and then name the project. After the project is created, Percy generates a token. Make a note of it. You have to use it set your environment variable in the next step.
For details on creating a project, see Create a Percy project.
Set the project token as an environment variable
Run the given command to set PERCY_TOKEN as an environment variable:
To learn about environment variables in Percy, see Percy environment variables.
Update your test script
Import the Percy library to use the method and attributes required to take screenshots.
In the following code, the percySnapshot method is used:
We are passing the required argument which is name, and are using an <https://example.com> web application. JavaScript example as the name of the snapshot within the percySnapshot method.
The snapshot method arguments are:
-
driver(required) - A selenium-webdriver driver instance -
name(required) - The snapshot name; must be unique to each snapshot -
options- An object containing various snapshot options. See per-snapshot configuration options
To learn more, visit Percy snapshot.
Run Percy
Run your tests using percy exec command as shown below:
If you are unable to use the percy:exec command or prefer to run your tests using IDE run options, you can use the percy exec:start and percy exec:stop commands. To learn more, visit Run Percy.
This command starts Percy, create a new Percy build, takes snapshots and uploads them to your project, and stops Percy:
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
Before you begin, ensure your Automate script’s capabilities are using Selenium version 3.11.0 and above.
- We recommend using Selenium 4 with Percy on Automate to boost performance and ensure increased stability while capturing screenshots.
- Capture a full-page screenshot using the full-page parameter. By default, Percy On Automate captures a single tile, for the full-page screenshot, refer to full page screenshot on Percy with Automate.
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
Step 2 - Install the SDK
For Javascript-based frameworks like WebdriverIO, or Mocha
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.
Step 5 - Update your Automate test script.
(1) Import percy_screenshot from Percy library using the below code:
(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”.
(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
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!