Integrate functional and visual tests

This guide explains how to integrate functional and visual tests.

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.

Browser selection management

Browser selection management enables you to select from a single place all the browsers you want to run your visual tests on. The more the browsers, the higher your visual test coverage.

Users can create a Web Percy project and decide how the browsers should be handled. Percy offers two options listed below:

To select the browsers to test on, first, create a Web project in Percy. You have two ways to select browsers:

• Percy(Default) - This is Percy’s native cross-browser testing functionality and is selected by default. To know about how this works, see Cross-browser visual testing.
  • If you want to run visual tests only on the latest browsers, select Percy. Your tests run at a high processing speed. If you want twice the speed, purchase the enterprise plan for Percy.
• Automate - You manage browsers with Automate capabilities. When the functional tests run, Percy directly captures the required screenshots.

  • If you want to run visual tests on a variety of desktop OS, Mobile OS, Mobile devices, and browser combinations, select Automate. If you want to boost the test processing speed, consider purchasing parallels in Automate.

    

Percy on 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:

Prerequisite

Before you begin, ensure your Automate script’s capabilities are using Selenium version 3.11.0 and above.

Integration steps

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

npm install --save @percy/cli

Step 2 - Install the relevant SDK

For Javascript-based frameworks like WebdriverIO, or Mocha

npm install @percy/playwright

npm install @percy/selenium-webdriver@2.0.1

npm install @percy/appium-app@2.0.2

For Python

pip install percy-playwright

pip install percy-selenium==2.0.1

pip install percy-appium-app==2.0.2

For Java

Update the pom.xml file as shown below:

<groupId>io.percy</groupId>
<artifactId>percy-playwright-java</artifactId>
<version>1.0.0</version>

<groupId>io.percy</groupId>
<artifactId>percy-java-selenium</artifactId>
<version>2.0.2</version>

<groupId>io.percy</groupId>
<artifactId>percy-appium-app</artifactId>
<version>2.0.3</version>

For C#

Update the .csproj file as shown below:

<PackageReference Include="PercyIO.Playwright" Version="1.0.0" />

<PackageReference Include="PercyIO.Selenium" Version="2.0.1"/>

<PackageReference Include="PercyIO.Appium" Version="3.0.1"/>

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.

export PERCY_TOKEN="<your token here>"

set PERCY_TOKEN="<your token here>"

$Env:PERCY_TOKEN="<your token here>"

Step 5 - Update your Automate test script.

(1) Import percy_screenshot from Percy library using the below code:

For Selenium

from percy import percy_screenshot

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

import io.percy.selenium.Percy;

using PercyIO.Selenium;

For Appium

from percy import percy_screenshot

const percyScreenshot = require('@percy/appium-app');

import io.percy.appium.PercyOnAutomate;

using PercyIO.Appium;

For Playwright

from percy import percy_screenshot

const { percyScreenshot } = require("@percy/playwright");

import io.percy.playwright.Percy;

using PercyIO.Playwright;

(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”.

For Selenium:

percy_screenshot(driver, name = 'Screenshot 1')
options =  { 'freezeAnimatedImages': True, 'percyCSS': 'h1{color:red;} a{color: red;font-size: 1rem;}', 'ignore_region_xpaths':['/html/body/div/p[2]/a']}
percy_screenshot(driver, name = 'Screenshot 2', options = options)
# Full page screenshot
options =  { 'fullPage': True, 'percyCSS': 'h1{color:red;} a{color: red;font-size: 1rem;}' }
percy_screenshot(driver, name = 'Screenshot 3', options = options)

await percyScreenshot(driver, 'Screenshot 1');
options = { percyCSS: 'h1{color:red;} a{color: red;font-size: 1rem;}', ignore_region_xpaths: ['/html/body/div/p[2]/a']}
await percyScreenshot(driver, 'Screenshot 2', options);
// Full page screenshot 
options = { fullPage: true, percyCSS: 'h1{color:red;} a{color: red;font-size: 1rem;}' }
await percyScreenshot(driver, 'Screenshot 3', options);

Percy percy = new Percy(driver);
percy.screenshot("Screenshot 1");
HashMap<String, Object> options = new HashMap<String, Object>();
options.put("percyCSS", "h1{color:red;} a{color: red;font-size: 1rem;}");
options.put("ignore_region_xpaths", Arrays.asList("/html/body/div/p[2]/a"));
percy.screenshot("Screenshot 2", options);
// Full page screenshot
options.put("fullPage", true);
percy.screenshot("Screenshot 3", options);

Percy.Screenshot(driver, "Screenshot 1");
Dictionary<string, object> options = new Dictionary<string, object>();
options.Add("percyCSS", "h1{color:red} a{color: red;font-size: 1rem;}");
List<string> xpaths = new List<string>();
xpaths.Add("/html/body/div/p[2]/a");
options.Add("ignore_region_xpaths", xpaths);
Percy.Screenshot(driver, "Screenshot 2", options);
// Full page screenshot
options.Add("fullPage", true);
Percy.Screenshot(driver, "Screenshot 3", options);

For Appium:

percy_screenshot(driver, name = 'Screenshot 1')
options =  { 'freezeAnimatedImages': True, 'percyCSS': 'h1{color:red;} a{color: red;font-size: 1rem;}', 'ignore_region_xpaths':['/html/body/div/p[2]/a']}
percy_screenshot(driver, name = 'Screenshot 2', options = options)
# Full page screenshot
options =  { 'fullPage': True, 'percyCSS': 'h1{color:red;} a{color: red;font-size: 1rem;}' }
percy_screenshot(driver, name = 'Screenshot 3', options = options)

await percyScreenshot(driver, 'Screenshot 1');
options = { percyCSS: 'h1{color:red;} a{color: red;font-size: 1rem;}', ignore_region_xpaths: ['/html/body/div/p[2]/a']}
await percyScreenshot(driver, 'Screenshot 2', options);
// Full page screenshot 
options = { fullPage: true, percyCSS: 'h1{color:red;} a{color: red;font-size: 1rem;}' }
await percyScreenshot(driver, 'Screenshot 3', options);

PercyOnAutomate percy = new PercyOnAutomate(driver);
percy.screenshot("Screenshot 1");
HashMap<String, Object> options = new HashMap<String, Object>();
options.put("percyCSS", "h1{color:red;} a{color: red;font-size: 1rem;}");
options.put("ignore_region_xpaths", Arrays.asList("/html/body/div/p[2]/a"));
percy.screenshot("Screenshot 2", options);
// Full page screenshot
options.put("fullPage", true);
percy.screenshot("Screenshot 3", options);

PercyOnAutomate Percy = new PercyOnAutomate(driver);
Percy.Screenshot("Screenshot 1");
Dictionary<string, object> options = new Dictionary<string, object>();
options.Add("percyCSS", "h1{color:red} a{color: red;font-size: 1rem;}");
List<string> xpaths = new List<string>();
xpaths.Add("/html/body/div/p[2]/a");
options.Add("ignore_region_xpaths", xpaths);
Percy.Screenshot("Screenshot 2", options);
// Full page screenshot
options.Add("fullPage", true);
Percy.Screenshot("Screenshot 3", options);

For Playwright:

# In your desired location add the command
percy_screenshot(page, name = 'Screenshot 1')
# You can pass `options`
percy_screenshot(page, name = 'Screenshot 1', options = { 'freezeAnimation': False, 'percyCSS': 'h1{color:green;} a{color: green;font-size: 1rem;}', 'ignore_region_xpaths':['/html/body/div/p[2]/a']})

// In your desired location add the command
await percyScreenshot(page, "Screenshot 1");
// You can pass `options`
await percyScreenshot(page, 'Screenshot 1', { 'freezeAnimation': False, 'percyCSS': 'h1{color:green;} a{color: green;font-size: 1rem;}', 'ignoreRegionXpaths':['/html/body/div/p[2]/a']})

// Initialize the percy object using page instance 
Percy percy = new Percy(page);
// In your desired location add the command
percy.screenshot("screenshot_1");
// You can pass `options`
HashMap<String, Object> options = new HashMap<String, Object>();
options.put("percyCSS", "h1{color:green;}");
percy.screenshot("screenshot_1", options);

Percy.Screenshot(page, "example_screenshot_1");
// You can pass `options`
Dictionary<string, object> options = new Dictionary<string, object>();
options.Add("percyCSS", "h1{color:green}");
Percy.Screenshot(driver, "example_screenshot_1", options);

Step 6 - Run the build

npx percy exec -- <command to run the automate script file>

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. For more information, see Intelli ignore.

  

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. For more information, see Debugging options 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:

# before taking screenshot we force the carousel to be at 1st tile
driver.execute_script(`var carousel = $('.carousel');
  carousel.carousel(0);
  carousel.carousel('pause');`)
percy_screenshot(driver, name = 'Screenshot 1')

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:

# before taking screenshot please close the sticky elements
cookie_banner = wait.until(EC.presence_of_element_located((By.ID, 'cookie-banner')))
# Find the accept button and click it
accept_button = cookie_banner.find_element(By.XPATH, '//button[text()="Accept"]')
accept_button.click()
percy_screenshot(driver, name = 'Screenshot 1')

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.

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.