Integrate your Playwright tests with Percy
A guide to integrating your Playwright 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
To establish this integration, choose the appropriate variant and refer to the following section accordingly:
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.
The following example uses the percySnapshot function:
For other Playwright examples, see the Playwright docs.
The snapshot method arguments are:
-
page(required) - A playwright page instance -
name(required) - The snapshot name; must be unique to each snapshot -
options- See per-snapshot configuration options
To learn more, see Percy snapshot.
Run Percy
Run your tests using the 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.
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
Integrating functional and visual testing can greatly enhance your ability to catch UI regressions and ensure the visual consistency of your application. By integrating Percy with your functional testing pipeline, you can seamlessly capture screenshots during your functional test runs and compare them to baseline images.
Percy with Automate
If you choose the “Automate” option when creating a Percy project, the “browsers selection” option will not appear in the project settings. Instead, the selection of browsers will be based on the capabilities specified in the Automate session.
You can use the Percy Screenshot command to capture a screenshot when a page is rendered during an Automate session. This screenshot is directly sent to the Percy build for comparison.
Check out the video below to get an overview of Percy on Automate:
- Supported languages and frameworks.
- Set the browser height and width to get consistent screenshots.
- For Apple devices, close the tag for smart app banners before taking screenshots.
- Playwright for Android is currently supported only for NodeJS.
Integration steps
Integrate Percy on Automate with your test suite to run visual tests. To do that, follow these steps:
Capture a full-page screenshot using the full-page parameter. By default, Percy On Automate captures a single tile, for the full page, refer to the instructions below.
Step 1 - Install the latest Percy CLI
Step 2 - Install the relevant SDK
For Javascript-based frameworks
For Python
For Java
Update the pom.xml file as shown below:
For CSharp
Update the .csproj file as shown below:
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 will be 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 Python code, the percy_screenshot("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”.
| Arguments | Description |
|---|---|
| name(String) |
(Required) The screenshot name must be unique for each screenshot captured. For example: name = Screenshot 1. |
| options() | 1. (Optional) freezeAnimatedImage(Boolean) - To determine whether Percy will perform stabilization on the DOM. By default set to false, set to true if stabilization needs to be performed by Percy. 2. (Optional) freezeAnimatedImageOptions(Boolean) - In the case of specific animated images that do not appear to freeze, we can select and submit them for freezing.There are two ways to select it. i. freezeImageBySelectors. ii. freezeImageByXpaths. 3. (Optional) percyCSS - Apply Percy-specific CSS to stabilize screenshots. 4. (Optional) ignoreRegions - To ignore a particular set of elements or sections in DOM. There are four ways to pass it. i. ignoreRegionXpaths. ii. ignoreRegionSelectors. iii. customIgnoreRegions. 5. (Optional) considerRegions - To counteract the effects of IntelliIgnore. There are two ways to consider it. i. considerRegionXpaths. ii. considerRegionSelectors. iii. customConsiderRegions. |
| full-page(Boolean) | Set to true if we want to take fullpage screenshots, default is false. |
Step 6 - Run the build
Results
You can view the visual comparison results on the generated Percy builds.
Percy on Automate Features
- If there are more than five screen widths, a dropdown menu will show up with different width options. The dropdown will display a maximum of ten entries.
- The build generation panel now includes a new device selection filter on the left pane.
- You can easily switch between the Percy and the Automate session.
-
You can use the Intelli Ignore feature to check the contextual differences. Read more.
Debug in Automate Session
-
The generated Percy builds have a redirect link to your builds on the Automate session.
- The generated builds on the Automate session have a redirect link to your Percy builds.
-
Once the Automate builds are generated, you can use various logging options such as Text Logs, Network Logs, Other Logs, Issues Detected, and many more to review your builds.
- To determine the timestamp of a screenshot taken, you can search for the Percy Screenshot command within your Automate session.
-
The Percy screenshot command displays the screenshot name besides it, as shown:
Handle dynamic elements
If you have dynamic JavaScript elements or carousels in your test, stabilize the DOM first and then invoke percyScreenshot. This allows for capturing consistent and accurate screenshots.
For example, if you are using bootstrap carousel, handle it as shown below:
Another example is how to handle sticky elements. Suppose the website you’re testing has the cookie banner. You can either accept or reject it. In the following snippet, we’re accepting the cookie:
Full page screenshots
Your webpage may require multiple scrolls to get to the end of a page. You can test these long pages using Percy’s full-page screenshot feature. It offers a comprehensive snapshot of a web page, capturing its entire length and content in a single image.
Things to keep in mind
- Call
percyScreenshotafter ensuring the page has loaded. - Although we attempt to handle lazy loading, if any issues arise, ensure you scroll to the bottom before calling
percyScreenshot. - Dynamic elements such as JS based animation, video, carousel need to be paused before full page screenshot.
- The maximum limit for the length of a full-page screenshot on desktop is 10000px or 10 tiles, whichever is minimum, and for mobile, it is 10 tiles.
- A website with different layouts based on geolocation can be managed by the user using IP Geolocation, as explained in the BrowserStack Documentation.
- The user needs to handle any popups that might appear while taking a screenshot.
- Remove meta tags that may hinder the webpage by adding native elements.
- The
customIgnoreRegionsfrom theignoreRegionsoption andcustomConsiderRegionsfrom theconsiderRegionsoption do not function with full-page screenshots.
Benefits of Percy on Automate
- Using Percy on Automate is cost-effective and performant.
- It supports a single pipeline for functional and visual testing.
- It saves lot of network traffic as we are directly uploading screenshots from BrowserStack terminal to Percy cloud.
- Tell us the capture movement and Percy will take screenshot of that movement as it supports css pseudo classes.
- It supports third party automated testing platforms including in-house setups.
- Exposure to highest browser and devices coverage while using BrowserStack Automate.
Limitations
- Internet Explorer is not supported.
- For Mozilla Firefox, Google Chrome, and Microsoft Edge, browser versions less than 91 are not supported.
- Mojave and older versions of macOS are not supported.
- The FreezeAnimatedImage option does not have support for macOS Catalina and earlier versions.
- Chromium on iPhone is not supported.
Compatibility Matrix
Refer the below matrix to check what frameworks are supported by Percy on Automate.
Note: Contact us to raise a feature request.
| Testing framework | Languages | Language specific |
| Playwright | Java | |
| NodeJS | ||
| Python | ||
| .Net |
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!