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.

export BROWSERSTACK_USERNAME="YOUR_USERNAME"
export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"

setx BROWSERSTACK_USERNAME "YOUR_USERNAME" 
setx BROWSERSTACK_ACCESS_KEY "YOUR_ACCESS_KEY" 
set BROWSERSTACK_USERNAME=YOUR_USERNAME
set BROWSERSTACK_ACCESS_KEY=YOUR_ACCESS_KEY

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.

mvn archetype:generate -B -DarchetypeGroupId="com.browserstack" \
-DarchetypeArtifactId="java-archetype-integrate" -DarchetypeVersion="1.3" \
-DgroupId="com.browserstack" -DartifactId="java-archetype-integrate" -Dversion="1.3" \
-DBROWSERSTACK_USERNAME="YOUR_USERNAME" -DBROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY" -DBROWSERSTACK_APP="/path/to/your/app"

mvn archetype:generate -B -DarchetypeGroupId="com.browserstack" -DarchetypeArtifactId="java-archetype-integrate" -DarchetypeVersion="1.3" -DgroupId="com.browserstack" -DartifactId="java-archetype-integrate" -Dversion="1.3" -DBROWSERSTACK_USERNAME="YOUR_USERNAME" -DBROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY" -DBROWSERSTACK_APP="/path/to/your/app"

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.

userName: YOUR_USERNAME
accessKey: YOUR_ACCESS_KEY
app: [Your App URL]
platforms:
  - platformName: android
    deviceName: Samsung Galaxy S22 Ultra
    platformVersion: 12.0
  - platformName: android
    deviceName: Google Pixel 7 Pro
    platformVersion: 13.0
  - platformName: android
    deviceName: OnePlus 9
    platformVersion: 11.0
parallelsPerPlatform: 1
browserstackLocal: true
buildName: browserstack-build-1
projectName: BrowserStack Sample
percy: true
percyCaptureMode: manual

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:

// ...imports
import com.browserstack.AppPercySDK;
public class TestNG extends AppiumTest {
    @Test
    public void test() throws Exception {
         // ...
         AppPercySDK.screenshot(driver, "My Screenshot");
         // ...
    }
}

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:

export PERCY_TOKEN=[your-project-token]

Install Percy packages

Install Percy CLI by running the following command:

npm install --save-dev @percy/cli

Install dependencies

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

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

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.

// import AppPercy
import io.percy.appium.AppPercy;
public class Example {
  public static void main(String[] args) throws MalformedURLException, InterruptedException {
    DesiredCapabilities caps = new DesiredCapabilities();
    AndroidDriver<AndroidElement> driver = new AndroidDriver<AndroidElement>(
      new URL("http://hub.browserstack.com/wd/hub"), caps);
    AppPercy percy = new AppPercy(driver);
    
    //Percy Screenshot function which captures and uploads screenshot to percy
    percy.screenshot("First Screenshot");
    driver.quit();
  }
}

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

The screenshot method arguments are:

percy.screenshot(name, fullScreen)

• 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:-

var ignoreRegion = new IgnoreRegion();
ignoreRegion.setTop() = top;
ignoreRegion.setBottom = bottom;
ignoreRegion.setLeft = left;
ignoreRegion.setRight = right;

• 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.

import io.percy.espresso.AppPercy;
AppPercy percy = new AppPercy();
percy.screenshot("name");
ScreenshotOptions options = new ScreenshotOptions();
options.setDeviceName("Google Pixel 3"); 
options.setStatusBarHeight(100); 
options.setNavBarHeight(100); 
options.setFullScreen(true); 
options.setOrientation("portrait"); 
percy.screenshot("Screenshot 1", options);

import io.percy.espresso.AppPercy
val percy = AppPercy()
percy.screenshot("name")
val options = ScreenshotOptions();
options.setDeviceName("Google Pixel 3"); 
options.setStatusBarHeight(100); 
options.setNavBarHeight(100); 
options.setFullScreen(true); 
options.setOrientation("portrait"); 
percy.screenshot("name", options);

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

[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Snapshot taken "Java example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!