Percy visual testing Appium (wd) and WebdriverIO
$ npm install --save-dev @percy/cli @percy/appium-app
Notes:
Minimum required version for
@percy/cli
is1.25.0
for this package to work correctly.This is tested on node 14+ and should be compatible with all newer node versions
This is an example test using the percyScreenshot
function.
const percyScreenshot = require('@percy/appium-app');
describe('Appium webdriverio test example', function() {
it('takes a screenshot', async () => {
await percyScreenshot('Appium JS example');
});
});
describe('Appium wd test example', function() {
it('takes a screenshot', async () => {
driver = // use your existing way to create appium driver with wd
await percyScreenshot(driver, 'Appium JS example');
});
});
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 app:exec -- [appium test command]
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Screenshot taken "Appium JS example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!
percyScreenshot(driver, name[, {
fullscreen,
deviceName,
orientation,
statusBarHeight,
navigationBarHeight
}])
driver
(required) - A appium driver instance [ can be skipped in case of webdriverio runner]name
(required) - The screenshot name; must be unique to each screenshotoptions object
(optional)fullscreen
: if the app is currently in fullscreendeviceName
: custom device name to override SDK fetched nameorientation
: "portrait"/"landscape" tell SDK which orientation app is in [ Note: This is only for tagging purpose, does not change the orientation of the device ]statusBarHeight
: In px if you want to override SDKnavigationBarHeight
: In px if you want to override SDKfullPage
: true/false. [Experimental] only supported on App Automate driver sessionsscreenLengths
: int [Experimental] max screen lengths for fullPagescrollableXpath
(optional) - [Experimental] scrollable element xpath for fullpage; stringscrollableId
(optional) - [Experimental] scrollable element accessibility id for fullpage; stringignoreRegionXpaths
(optional) - elements xpaths that user want to ignore in visual diff; list of stringignoreRegionAccessibilityIds
(optional) - elements accessibility_ids that user want to ignore in visual diff; list of stringignoreRegionAppiumElements
(optional) - appium elements that user want to ignore in visual diff; list of appium element objectcustomIgnoreRegions
(optional) - custom locations that user want to ignore in visual diff; list of ignore_region object- IgnoreRegion:-
-
Description: This class represents a rectangular area on a screen that needs to be ignored for visual diff.
-
Constructor:
constructor(top, bottom, left, 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:Error: 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.
-
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:
async function percyScreenshotFlutter(driver, name, options) {
// switch to native context
await driver.switchContext('NATIVE_APP');
await percyScreenshot(driver, name, options);
// switch back to flutter context
await driver.switchContext('FLUTTER');
}
- Call percyScreenshotFlutter helper function when you want to take screenshot.
await percyScreenshotFlutter(driver, name[, {
fullscreen,
deviceName,
orientation,
statusBarHeight,
navigationBarHeight
}])
Note:
For other hybrid apps the
await driver.switchContext('FLUTTER');
would change to context that it uses like say WEBVIEW etc.
percyScreenshot(driver, name, options)
[ needs @percy/cli 1.27.0-beta.0+ ];
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.freezeAnimation
- Boolean value by default it falls back tofalse
, you can passtrue
and percy will freeze image based animations.percyCSS
- Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.ignoreRegionXpaths
- elements in the DOM can be ignored using xpathignoreRegionSelectors
- elements in the DOM can be ignored using selectors.ignoreRegionAppiumElements
- elements can be ignored using appium_elements.customIgnoreRegions
- elements can be ignored using custom boundaries- IgnoreRegion:-
-
Description: This class represents a rectangular area on a screen that needs to be ignored for visual diff.
-
Constructor:
init(self, top, bottom, left, 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:ValueError: 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.
-
- IgnoreRegion:-
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