Integrate App Percy with Appium and Java

Set BrowserStack credentials

Save your BrowserStack credentials as environment variables. It simplifies running your test suite from your local or CI environment. You can export the environment variables for the Username and Access Key of your BrowserStack account or you can set it in the config file.

Install BrowserStack SDK using Maven Archetype

Maven Archetype provides a template to quickly configure your project. Copy & run the following command on your terminal/command prompt to add browserstack-java-sdk dependency in your pom.xml and browserstack.yml file in your project.

Update your BrowserStack config file

In the browserstack.yml file:

1. Set percy: true.

2. Set a projectName.
   After you run a test, an App Automate project and an App Percy project are created with the project name you set here.
   If a App Percy project by the name you set in the browserstack.yml file already exists, your screenshots are added to the same project. However, if the name matches a Percy project, your visual tests will continue to run, but an error message will appear in your logs. Your functional tests still run as expected.

3. Set percyCaptureMode: manual.
   

Below sample browserstack.yml file shows how to set the percy, the projectName, and the percyCaptureMode parameters.

Manually add Percy screenshot method to update test script

To manually capture screenshots, implement the following steps in your test script:

1. Import the BrowserStack Percy SDK in your test script.
2. Add the AppPercySDK.screenshot(driver, name) method at required points in your test script to get the screenshots you want.

Here’s an example:

Run your test script

Create new app project on percy dashboard

Sign in to Percy and create a new app type project. After you’ve created the project, you’ll be shown a PERCY_TOKEN environment variable. Percy will use the PERCY_TOKEN to know which organisation and project to upload the screenshots to. You will need this PERCY_TOKEN in next steps.

Set the project token as an environment variable

Run the given command to set PERCY_TOKEN as an environment variable:

Install Percy packages

Install Percy CLI by running the following command:

Install dependencies

Add percy-appium-app to your project dependencies. If you’re using Maven:

Update test script

Make sure to import AppPercy in your code.

Below is an example test using the percy.screenshot function. Use this function wherever you have to take a screenshot.

We are passing the required arguments.percy.screenshot method.

The screenshot method arguments are:

• name (required) - The screenshot name; must be unique to each screenshot
• Additional screenshot options (overrides any project options):
• fullScreen - (optional) It indicates if the app is a full screen
• options - (optional) screenshot params: Use ScreenshotOptions to set following params to override
• deviceName - Device name on which screenshot is taken
• statusBarHeight - int; Height of status bar for the device
• navBarHeight - int; Height of navigation bar for the device
• orientation - Orientation of the application
• FullPage: boolean; [alpha] only supported on App Automate driver sessions [ needs @percy/cli 1.20.2+ ]
• In case scrollview is overlapping with other app elements. Offsets can be provided to reduce the area which needs to be considered for scrolling:
  • topScrollviewOffset :(optional) [alpha] offset from top of scrollview [ needs @percy/cli 1.20.2+ ]; int
  • bottomScrollviewOffset: (optional) - [alpha] offset from bottom of scrollview [ needs @percy/cli 1.20.2+ ]; int
• ScreenLengths: int; [alpha] max screen lengths for fullPage [ needs @percy/cli 1.20.2+ ]
• ScrollableXpath (optional) - [alpha] scrollable element xpath for fullpage [ needs @percy/cli 1.20.2+ ]; string
• ScrollableId (optional) - [alpha] scrollable element accessibility id for fullpage [ needs @percy/cli 1.20.2+ ]; string
• IgnoreRegionXpaths (optional) - elements xpaths that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ]; list of string
• IgnoreRegionAccessibilityIds (optional) - elements accessibility_ids that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ]; list of string
• IgnoreRegionAppiumElements (optional) - appium elements that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ]; list of appium element object
• CustomIgnoreRegions (optional) - Custom locations that users want to ignore in visual diffs, with (0, 0) starting at the top left (requires @percy/cli 1.23.0+); list of ignore_region objects.
• IgnoreRegion:-
  • Description: This class represents a rectangular area on a screen that needs to be ignored for visual diff.
  • constructor:-

• Parameters:
  • 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.
• Raises IllegalArgumentException:If top, bottom, left, or right is less than 0, or top is greater than or equal to bottom, or left is greater than or equal to right.
• valid: Ignore region should be within the boundaries of the screen.

Run your test script

Run your tests using percy app:exec.

This command starts Percy, create a new Percy build, takes snapshots and uploads them to your project, and stops Percy: