Merge branch 'master' into PPLT-2089/poa-cache-js

README.md

@@ -72,36 +72,33 @@ percyScreenshot(driver, name[, {
 - `driver` (**required**) - A appium driver instance [ can be skipped in case of webdriverio runner]
 - `name` (**required**) - The screenshot name; must be unique to each screenshot
 - `options object` (**optional**) 
-  - `fullscreen`: if the app is currently in fullscreen
-  - `deviceName`: custom device name to override SDK fetched name
-  - `orientation`: "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 SDK
-  - `navigationBarHeight`: In px if you want to override SDK
-  - `fullPage`: true/false. [Experimental] only supported on App Automate driver sessions
-  - `screenLengths`: int [Experimental] max screen lengths for fullPage
-  - `scrollableXpath` (**optional**) - [Experimental] scrollable element xpath for fullpage; string
-  - `scrollableId` (**optional**) - [Experimental] scrollable element accessibility id for fullpage; string
-  - `ignoreRegionXpaths` (**optional**) - elements xpaths that user want to ignore in visual diff; list of string
-  - `ignoreRegionAccessibilityIds` (**optional**) - elements accessibility_ids that user want to ignore in visual diff; list of string
-  - `ignoreRegionAppiumElements` (**optional**) - appium elements that user want to ignore in visual diff; list of appium element object
-  - `customIgnoreRegions` (**optional**) - custom locations that user want to ignore in visual diff; list of ignore_region object
+  - `fullscreen`: If the app is currently in fullscreen; boolean
+  - `deviceName`: Custom device name to override SDK fetched name
+  - `orientation`: ["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 SDK; int
+  - `navigationBarHeight`: In px if you want to override SDK; int
+  - `fullPage`: [Alpha] Only supported on App Automate driver sessions [ needs @percy/cli 1.20.2+ ]; boolean
+    - `screenLengths`: [Alpha] Max screen lengths for fullPage; int
+    - 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`: [Alpha] Offset from top of scrollview; int
+      - `bottomScrollviewOffset`: [Alpha] Offset from bottom of scrollview; int
+  - `scrollableXpath` [Alpha] Scrollable element xpath for fullpage; string
+  - `scrollableId`: [Alpha] Scrollable element accessibility id for fullpage; string
+  - `ignoreRegionXpaths`: Elements xpaths that user want to ignore in visual diff; list of string
+  - `ignoreRegionAccessibilityIds`: Elements accessibility_ids that user want to ignore in visual diff; list of string
+  - `ignoreRegionAppiumElements`: Appium elements that user want to ignore in visual diff; list of appium element object
+  - `customIgnoreRegions`: 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.
-
+      - `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.
 ## Running with Hybrid Apps
 
 For a hybrid app, we need to switch to native context before taking screenshot.
@@ -140,25 +137,21 @@ await percyScreenshotFlutter(driver, name[, {
 - `options` (**optional**) - There are various options supported by percy_screenshot to server further functionality.
     - `freezeAnimation` - Boolean value by default it falls back to `false`, you can pass `true` 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 xpath
-    - `ignoreRegionSelectors` - 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
+    - `ignoreRegionXpaths` - Elements in the DOM can be ignored using xpath
+    - `ignoreRegionSelectors` - 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.
-
+          - `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.
 ### Creating Percy on automate build
 Note: Automate Percy Token starts with `auto` keyword. The command can be triggered using `exec` keyword.
 ```sh-session

index.js

@@ -24,6 +24,8 @@ module.exports = async function percyScreenshot(driver, name, options = {}) {
     considerRegionAppiumElements,
     customConsiderRegions,
     scrollableXpath,
+    topScrollviewOffset,
+    bottomScrollviewOffset,
     scrollableId
   } = options;
   // allow working with or without standalone mode for wdio
@@ -48,6 +50,8 @@ module.exports = async function percyScreenshot(driver, name, options = {}) {
       considerRegionAppiumElements = name.considerRegionAppiumElements;
       customConsiderRegions = name.customConsiderRegions;
       scrollableXpath = name.scrollableXpath;
+      topScrollviewOffset = name.topScrollviewOffset;
+      bottomScrollviewOffset = name.bottomScrollviewOffset;
       scrollableId = name.scrollableId;
       options = name;
     }
@@ -92,6 +96,8 @@ module.exports = async function percyScreenshot(driver, name, options = {}) {
         considerRegionAppiumElements,
         customConsiderRegions,
         scrollableXpath,
+        topScrollviewOffset,
+        bottomScrollviewOffset,
         scrollableId
       });
       log.debug(`[${name}] -> end`);

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@percy/appium-app",
   "description": "Appium client library for visual testing with Percy",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.1",
   "license": "MIT",
   "author": "Perceptual Inc.",
   "repository": {
@@ -25,7 +25,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   },
   "scripts": {
     "lint": "eslint --ignore-path .gitignore .",

percy/providers/appAutomateProvider.js

@@ -31,6 +31,8 @@ class AppAutomateProvider extends GenericProvider {
     considerRegionAppiumElements,
     customConsiderRegions,
     scrollableXpath,
+    topScrollviewOffset,
+    bottomScrollviewOffset,
     scrollableId
   } = {}) {
     let response = null;
@@ -56,6 +58,8 @@ class AppAutomateProvider extends GenericProvider {
         considerRegionAppiumElements,
         customConsiderRegions,
         scrollableXpath,
+        topScrollviewOffset,
+        bottomScrollviewOffset,
         scrollableId
       });
     } catch (e) {
@@ -102,7 +106,7 @@ class AppAutomateProvider extends GenericProvider {
   }
 
   // Override this for AA specific optimizations
-  async getTiles(fullscreen, fullPage, screenLengths, scrollableXpath, scrollableId) {
+  async getTiles(fullscreen, fullPage, screenLengths, scrollableXpath, topScrollviewOffset, bottomScrollviewOffset, scrollableId) {
     // Override AA optimizations
     if (this.isDisableRemoteUpload()) {
       if (fullPage === true) {
@@ -131,6 +135,8 @@ class AppAutomateProvider extends GenericProvider {
           numOfTiles: screenLengths || 4,
           deviceHeight: (await this.metadata.screenSize()).height,
           scollableXpath: scrollableXpath || null,
+          topScrollviewOffset: topScrollviewOffset || 0,
+          bottomScrollviewOffset: bottomScrollviewOffset || 0,
           scrollableId: scrollableId || null,
           FORCE_FULL_PAGE: process.env.FORCE_FULL_PAGE === 'true'
         }
@@ -148,9 +154,9 @@ class AppAutomateProvider extends GenericProvider {
 
     JSON.parse(response.result).forEach(tileData => {
       tiles.push(new Tile({
-        statBarHeight,
-        navBarHeight,
-        fullscreen,
+        statusBarHeight: statBarHeight,
+        navBarHeight: navBarHeight,
+        fullscreen: fullscreen,
         headerHeight: tileData.header_height,
         footerHeight: tileData.footer_height,
         sha: tileData.sha.split('-')[0] // drop build id

test/percy/providers/appAutomateProvider.test.mjs

@@ -151,9 +151,13 @@ describe('AppAutomateProvider', () => {
             height: 2000,
           };
           args['options']['deviceHeight'] = screenSize['height'];
+          args['options']['topScrollviewOffset'] = 0;
+          args['options']['bottomScrollviewOffset'] = 0;
           appAutomate.metadata = { statusBarHeight: () => 100, navigationBarHeight: () => 200, scaleFactor: () => 1, screenSize: () => screenSize };
 
-          await appAutomate.getTiles(true, false, null, null, null);
+          let tiles = await appAutomate.getTiles(true, false, null, null, null);
+          expect(tiles[0].statusBarHeight).toEqual(100);
+          expect(tiles[0].navBarHeight).toEqual(200);
           expect(browserstack_executorSpy).toHaveBeenCalledWith('percyScreenshot', args);
         });
       });
@@ -214,6 +218,8 @@ describe('AppAutomateProvider', () => {
           };
           args['projectId'] = 'percy-dev';
           args['options']['deviceHeight'] = screenSize['height'];
+          args['options']['topScrollviewOffset'] = 0;
+          args['options']['bottomScrollviewOffset'] = 0;
           args['screenshotType'] = 'fullpage';
           appAutomate.metadata = { statusBarHeight: () => 100, navigationBarHeight: () => 200, scaleFactor: () => 1, screenSize: () => screenSize };