Percy visual testing for Java Appium.
npm install @percy/cli
:
$ npm install --save-dev @percy/cli
Note: Minimum required version for @percy/cli is 1.15.0 for this package to work correctly.
Add percy-appium-app to your project dependencies. If you're using Maven:
<dependency>
<groupId>io.percy</groupId>
<artifactId>percy-appium-app</artifactId>
<version>2.1.6</version>
</dependency>
If you're using a different build system, see https://search.maven.org/artifact/io.percy/percy-appium-app for details for your specific system.
Note: This package is tested on Java versions 8, 11, 12, 13, 17 as part of unit tests. It should ideally work on all Java 8+ versions.
This is an example test using the percy.screenshot
function.
// import ...
import io.percy.appium.AppPercy;
public class Example {
public static void main(String[] args) throws MalformedURLException, InterruptedException {
DesiredCapabilities caps = new DesiredCapabilities();
// Add caps here
AndroidDriver<AndroidElement> driver = new AndroidDriver<AndroidElement>(
new URL("http://hub.browserstack.com/wd/hub"), caps);
AppPercy percy = new AppPercy(driver);
percy.screenshot("First Screenshot");
driver.quit();
}
}
Running the test above normally will result in the following log:
[percy] Percy is not running, disabling screenshots
When running with percy app:exec
, and your project's
PERCY_TOKEN
, a new Percy build will be created and screenshots will be uploaded to your project.
$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- [java test command]
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Screenshot taken "Java example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!
The screenshot method arguments:
ScreenshotOptions options = new ScreenshotOptions();
// Set options here
percy.screenshot(name, fullScreen, options)
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 screenoptions
- (optional) configure screenshot using below setter:
Setter Method | Description |
---|---|
setDeviceName(String deviceNameParam) | Device name on which screenshot is taken |
setStatusBarHeight(Integer statusBarHeightParam) | Height of status bar for the device |
setNavBarHeight(Integer navBarHeightParam) | Height of navigation bar for the device |
setOrientation(String orientationParam) | Orientation of the application |
setFullPage(Boolean fullPageParam) | [Alpha] Only supported on App Automate driver sessions [ needs @percy/cli 1.20.2+ ] |
setScreenLengths(Integer screenLengthsParam) | [Alpha] Max screen lengths for fullPage [ needs @percy/cli 1.20.2+ ] |
setTopScrollviewOffset(Integer topScrollviewOffsetParam) | [Alpha] Offset from top of scrollview [ needs @percy/cli 1.20.2+ ] |
setBottomScrollviewOffset(Integer bottomScrollviewOffsetParam) | [Alpha] Offset from bottom of scrollview [ needs @percy/cli 1.20.2+ ] |
setFullScreen(Boolean fullScreenParam) | Indicate whether app is full screen; boolean |
setScrollableXpath(String scrollableXpath) | [Alpha] Scrollable element xpath for fullpage [ needs @percy/cli 1.20.2+ ] |
setScrollableId(String scrollableId) | [Alpha] Scrollable element accessibility id for fullpage [ needs @percy/cli 1.20.2+ ] |
setIgnoreRegionXpaths(List ignoreRegionXpaths) | Elements xpaths that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ] |
setIgnoreRegionAccessibilityIds(List ignoreRegionAccessibilityIds) | Elements accessibility_ids that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ] |
setIgnoreRegionAppiumElements(List ignoreRegionAppiumElements) | Appium elements that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ] |
setCustomIgnoreRegions(List customIgnoreRegions) | Custom locations that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ] - Description: IgnoreRegion class represents a rectangular area on a screen that needs to be ignored for visual diff. var ignoreRegion = new IgnoreRegion(); ignoreRegion.setTop() = top; ignoreRegion.setBottom = bottom; ignoreRegion.setLeft = left; ignoreRegion.setRight = right; |
setAndroidScrollAreaPercentage | This is percentage area of the screen that we are scrolling. It will be in between 0 and 80; |
setScrollSpeed | This is the pixel per second that we are going to scroll. It will be between 0 and 2000 |
For a hybrid app, we need to switch to native context before taking screenshot.
- Add a helper method similar to following for say flutter based hybrid app:
public void percyScreenshotFlutter(AppPercy appPercy, AppiumDriver driver, String name, ScreenshotOptions options) {
// switch to native context
driver.context("NATIVE_APP");
appPercy.screenshot(name, options);
// switch back to flutter context
driver.context("FLUTTER");
}
- Call percyScreenshotFlutter helper function when you want to take screenshot.
percyScreenshotFlutter(appPercy, driver, name, options);
Note:
For other hybrid apps the
driver.context("FLUTTER");
would change to context that it uses like say WEBVIEW etc.
If you have a previous Percy configuration file, migrate it to the newest version with the
config:migrate
command:
$ percy config:migrate
percyScreenshot(driver, name, options)
[ needs @percy/cli 1.27.0-beta.0+ ];
This is an example test using the percy.Screenshot
method.
// import ...
import io.percy.appium.PercyOnAutomate;
public class Example {
public static void main(String[] args) throws MalformedURLException, InterruptedException {
DesiredCapabilities caps = new DesiredCapabilities();
// Add caps here
WebDriver driver = new RemoteWebDriver(new URL(URL), caps);
PercyOnAutomate percy = new PercyOnAutomate(driver);
percy.screenshot("First Screenshot");
driver.quit();
}
}
driver
(required) - A appium driver instancename
(required) - The screenshot name; must be unique to each screenshotoptions
(optional) - There are various options supported by percy_screenshot to server further functionality.sync
- Boolean value by default it falls back to false, Gives the processed result around screenshot [From CLI v1.28.0-beta.0+]freezeAnimatedImage
- Boolean value by default it falls back tofalse
, you can passtrue
and percy will freeze image based animations.freezeImageBySelectors
- List of selectors. Images will be freezed which are passed using selectors. For this to workfreezeAnimatedImage
must be set to true.freezeImageByXpaths
- List of xpaths. Images will be freezed which are passed using xpaths. For this to workfreezeAnimatedImage
must be set to true.percyCSS
- Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.ignoreRegionXpaths
- List of xpaths. elements in the DOM can be ignored using xpathignoreRegionSelectors
- List of selectors. elements in the DOM can be ignored using selectors.ignoreRegionSeleniumElements
- List of selenium web-element. elements can be ignored using selenium_elements.customIgnoreRegions
- List of custom objects. elements can be ignored using custom boundaries- Refer to example -
-
List<HashMap> customRegion = new ArrayList<>(); HashMap<String, Integer> region1 = new HashMap<>(); region1.put("top", 10); region1.put("bottom", 110); region1.put("right", 10); region1.put("left", 120); customRegion.add(region1); options.put("custom_ignore_regions", customRegion);
-
- 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.
- Refer to example -
considerRegionXpaths
- List of xpaths. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using xpaths.considerRegionSelectors
- List of selectors. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using selectors.considerRegionSeleniumElements
- List of selenium web-element. elements can be considered for diffing and will be ignored by Intelli Ignore using selenium_elements.customConsiderRegions
- List of custom objects. elements can be considered for diffing and will be ignored by Intelli Ignore using custom boundaries- Refer to example -
-
List<HashMap> customRegion = new ArrayList<>(); HashMap<String, Integer> region2 = new HashMap<>(); region2.put("top", 10); region2.put("bottom", 110); region2.put("right", 10); region2.put("left", 120); customRegion.add(region2); options.put("custom_consider_regions", customRegion);
- Parameters:
top
(int): Top coordinate of the consider region.bottom
(int): Bottom coordinate of the consider region.left
(int): Left coordinate of the consider region.right
(int): Right coordinate of the consider region.
-
- Refer to example -
Note: Automate Percy Token starts with auto
keyword. The command can be triggered using exec
keyword.
$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- [python test command]
[percy] Percy has started!
[percy] [Python example] : Starting automate screenshot ...
[percy] Screenshot taken "Python example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!
Refer to docs here: Percy on Automate