feat: add "screenshot" wrapper to correctly screen web elements

Author: DudaGod

README.md

@@ -38,6 +38,8 @@ module.exports = {
                     safari13: {
                         commands: [
                             'url',
+                            'screenshot',
+                            'orientation',
                             'swipe',
                             'touch',
                             'dragAndDrop'
@@ -55,6 +57,8 @@ module.exports = {
 
 Wrappers over existing commands:
 * **url** - wrapper over wdio "url" in order to wait until the page is completely open (used timeout from [`hermione.pageLoadTimeout`](https://github.com/gemini-testing/hermione#pageloadtimeout) or `30000` ms). In [appium-xcuitest-driver](https://github.com/appium/appium-xcuitest-driver) page is open with using the `xcrun` utility - `xcrun simctl openurl` which just tells the simulator to open the page and does not wait anything;
+* **screenshot** - wrapper of wdio "screenshot" in order to cut the native elements from the final image ([calibration](https://github.com/gemini-testing/hermione#calibrate) must be turned off);
+* **orientation** - wrapper of wdio "orientation" in order to recalculate size of native elements for "screenshot" command (turns on automatically when you specify a screenshot command);
 * **swipe** - replaces wdio "swipe" in order to perform swipe by coordinates in native context;
 * **touch** - replaces wdio "touch" in order to perform touch click by coordinates in native context;
 * **dragAndDrop** - replaces wdio "dragAndDrop" in order to perform drag and drop elements by coordinates in native context.

lib/command-helpers/context-switcher.js

@@ -1,16 +1,29 @@
 'use strict';
 
+const {getTestContext, IS_NATIVE_CTX, WEB_VIEW_CTX} = require('./test-context');
 const {NATIVE_CONTEXT} = require('../constants');
 
 exports.runInNativeContext = async function(browser, action, testCtx) {
-    if (!testCtx.webViewContext) {
+    if (!testCtx) {
+        testCtx = getTestContext(browser.executionContext);
+    }
+
+    if (testCtx[IS_NATIVE_CTX]) {
+        return action.fn.call(browser, ...[].concat(action.args));
+    }
+
+    if (!testCtx[WEB_VIEW_CTX]) {
         const {value: contexts} = await browser.contexts();
-        testCtx.webViewContext = contexts[1];
+        testCtx[WEB_VIEW_CTX] = contexts[1];
     }
 
     await browser.context(NATIVE_CONTEXT);
+    testCtx[IS_NATIVE_CTX] = true;
+
     const result = await action.fn.call(browser, ...[].concat(action.args));
-    await browser.context(testCtx.webViewContext);
+
+    await browser.context(testCtx[WEB_VIEW_CTX]);
+    testCtx[IS_NATIVE_CTX] = false;
 
     return result;
 };

lib/command-helpers/element-utils.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const _ = require('lodash');
+const {getTestContext} = require('../test-context');
+const {runInNativeContext} = require('../context-switcher');
+
+/**
+ * Decorator which checks that locator is existing on the page before perform action.
+ * @param {Object} action - action which should be done after check that element exists.
+ * @param {Function} action.fn - async/sync function.
+ * @param {(*|*[])} action.args - arguments that passed to `action.fn`.
+ * @param {*} action.default - default value that returned if locator does not exist.
+ *
+ * @returns {Promise}
+ */
+exports.withExisting = async function(action) {
+    const locator = _.isArray(action.args) ? action.args[0] : action.args;
+    const isExisting = await this.isExisting(locator);
+
+    if (!isExisting) {
+        return action.default;
+    }
+
+    return action.fn.call(this, ...[].concat(action.args));
+};
+
+/**
+ * Decorator which run action in native context.
+ * @param {Object} action - action which should be done in native context.
+ * @param {Function} action.fn - async/sync function.
+ * @param {(*|*[])} action.args - arguments that passed to `action.fn`.
+ *
+ * @returns {Promise}
+ */
+exports.withNativeCtx = async function(action) {
+    return runInNativeContext(this, action);
+};
+
+/**
+ * Decorator which memoize result of calling action and use it on subsequent calls.
+ * @param {Object} action - action which should be done if result is not yet memoized.
+ * @param {Function} action.fn - async/sync function.
+ * @param {(*|*[])} action.args - arguments that passed to `action.fn`.
+ * @param {string} key - key name by which the result is memoized.
+ *
+ * @returns {Promise}
+ */
+exports.withTestCtxMemo = async function(action, key) {
+    const testCtx = getTestContext(this.executionContext);
+
+    if (!testCtx[key]) {
+        testCtx[key] = await action.fn.call(this, ...[].concat(action.args));
+    }
+
+    return testCtx[key];
+};

lib/command-helpers/element-utils/decorators.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const {withExisting, withNativeCtx, withTestCtxMemo} = require('./decorators');
+const {TOP_TOOLBAR_SIZE, BOTTOM_TOOLBAR_LOCATION, WEB_VIEW_SIZE, PIXEL_RATIO} = require('../test-context');
+const {TOP_TOOLBAR, BOTTOM_TOOLBAR, WEB_VIEW} = require('../../native-locators');
+
+exports.getTopToolbarHeight = async (browser) => {
+    const action = {fn: browser.getElementSize, args: TOP_TOOLBAR, default: {width: 0, height: 0}};
+    const existingWrapper = {fn: withExisting, args: action};
+    const inNativeCtxWrapper = {fn: withNativeCtx, args: existingWrapper};
+
+    return (await withTestCtxMemo.call(browser, inNativeCtxWrapper, TOP_TOOLBAR_SIZE)).height;
+};
+
+exports.getBottomToolbarY = async (browser) => {
+    const action = {fn: browser.getLocation, args: BOTTOM_TOOLBAR, default: {x: 0, y: 0}};
+    const existingWrapper = {fn: withExisting, args: action};
+    const inNativeCtxWrapper = {fn: withNativeCtx, args: existingWrapper};
+
+    return (await withTestCtxMemo.call(browser, inNativeCtxWrapper, BOTTOM_TOOLBAR_LOCATION)).y;
+};
+
+exports.getWebViewSize = async (browser) => {
+    const action = {fn: browser.getElementSize, args: WEB_VIEW};
+    const inNativeCtxWrapper = {fn: withNativeCtx, args: action};
+
+    return await withTestCtxMemo.call(browser, inNativeCtxWrapper, WEB_VIEW_SIZE);
+};
+
+exports.getElemCoords = async (browser, selector) => {
+    const [{width, height}, {x, y}] = await Promise.all([browser.getElementSize(selector), browser.getLocation(selector)]);
+    const topToolbarHeight = await exports.getTopToolbarHeight(browser);
+
+    return {width, height, x, y: y + topToolbarHeight};
+};
+
+exports.getElemCenterLocation = async (browser, selector) => {
+    const {width, height, x, y} = await exports.getElemCoords(browser, selector);
+
+    return {
+        x: Math.round(x + width / 2),
+        y: Math.round(y + height / 2)
+    };
+};
+
+exports.getPixelRatio = async (browser) => {
+    const action = {fn: async () => (await browser.execute(() => window.devicePixelRatio)).value};
+
+    return await withTestCtxMemo.call(browser, action, PIXEL_RATIO);
+};
+
+exports.calcWebViewCoords = async (browser, {bodyWidth, pixelRatio = 1} = {}) => {
+    const [topToolbarHeight, bottomToolbarY, webViewSize] = await Promise.all([
+        exports.getTopToolbarHeight(browser),
+        exports.getBottomToolbarY(browser),
+        exports.getWebViewSize(browser)
+    ]);
+    const bottomToolbarHeight = bottomToolbarY > 0 ? webViewSize.height - bottomToolbarY : 0;
+
+    return {
+        width: Math.ceil(bodyWidth * pixelRatio),
+        height: Math.ceil((webViewSize.height - topToolbarHeight - bottomToolbarHeight) * pixelRatio),
+        left: Math.floor((webViewSize.width - bodyWidth) / 2 * pixelRatio),
+        top: Math.floor(topToolbarHeight * pixelRatio)
+    };
+};

lib/command-helpers/element-utils/index.js

@@ -1,7 +1,27 @@
 'use strict';
 
-exports.getTestContext = (context) => {
+const getTestContext = (context) => {
     return context.type === 'hook' && /^"before each"/.test(context.title)
         ? context.ctx.currentTest
         : context;
 };
+
+const resetTestContextValues = (context, keys = []) => {
+    const testCtx = getTestContext(context);
+
+    [].concat(keys).forEach((key) => {
+        delete testCtx[key];
+    });
+};
+
+module.exports = {
+    getTestContext,
+    resetTestContextValues,
+
+    TOP_TOOLBAR_SIZE: 'topToolbarSize',
+    BOTTOM_TOOLBAR_LOCATION: 'bottomToolbarLocation',
+    WEB_VIEW_SIZE: 'webViewSize',
+    IS_NATIVE_CTX: 'isNativeCtx',
+    WEB_VIEW_CTX: 'webViewContext',
+    PIXEL_RATIO: 'pixelRatio'
+};

lib/command-helpers/test-context.js

@@ -4,5 +4,7 @@ module.exports = {
     url: require('./url'),
     swipe: require('./swipe'),
     touch: require('./touch'),
-    dragAndDrop: require('./dragAndDrop')
+    dragAndDrop: require('./dragAndDrop'),
+    screenshot: require('./screenshot'),
+    orientation: require('./orientation')
 };

lib/commands/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const {resetTestContextValues, TOP_TOOLBAR_SIZE, BOTTOM_TOOLBAR_LOCATION, WEB_VIEW_SIZE} = require('../command-helpers/test-context');
+
+module.exports = (browser) => {
+    const baseOrientationFn = browser.orientation;
+
+    browser.addCommand('orientation', async (orientation) => {
+        if (orientation) {
+            resetTestContextValues(browser.executionContext, [TOP_TOOLBAR_SIZE, BOTTOM_TOOLBAR_LOCATION, WEB_VIEW_SIZE]);
+        }
+
+        return baseOrientationFn.call(browser, orientation);
+    }, true);
+};

lib/commands/orientation.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const {PNG} = require('pngjs');
+const concat = require('concat-stream');
+const streamifier = require('streamifier');
+const {calcWebViewCoords, getPixelRatio} = require('../command-helpers/element-utils');
+const {runInNativeContext} = require('../command-helpers/context-switcher');
+
+module.exports = (browser) => {
+    const baseScreenshotFn = browser.screenshot;
+
+    browser.addCommand('screenshot', async () => {
+        const {width: bodyWidth} = await browser.getElementSize('body');
+        const pixelRatio = await getPixelRatio(browser);
+        const cropCoords = await runInNativeContext(browser, {fn: calcWebViewCoords, args: [browser, {bodyWidth, pixelRatio}]});
+
+        const {value: base64} = await baseScreenshotFn.call(this);
+
+        return new Promise((resolve, reject) => {
+            const handleError = (msg) => (err) => reject(`Error occured while ${msg}: ${err.message}`);
+
+            streamifier.createReadStream(Buffer.from(base64, 'base64'))
+                .on('error', handleError('converting buffer to readable stream'))
+                .pipe(new PNG())
+                .on('error', handleError('writing buffer to png data'))
+                .on('parsed', function() {
+                    const destination = new PNG({width: cropCoords.width, height: cropCoords.height});
+
+                    try {
+                        this.bitblt(destination, cropCoords.left, cropCoords.top, cropCoords.width, cropCoords.height);
+                    } catch (err) {
+                        reject(`Error occured while copying pixels from source to destination png: ${err.message}`);
+                    }
+
+                    destination.pack()
+                        .on('error', handleError('packing png data to buffer'))
+                        .pipe(concat((buffer) => resolve({value: buffer.toString('base64')})))
+                        .on('error', handleError('concatenating png data to a single buffer'));
+                });
+        });
+    }, true);
+};

lib/commands/screenshot.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const _ = require('lodash');
-const {getTestContext} = require('../command-helpers/test-context');
+const {resetTestContextValues, TOP_TOOLBAR_SIZE, BOTTOM_TOOLBAR_LOCATION} = require('../command-helpers/test-context');
 const {getElemCenterLocation} = require('../command-helpers/element-utils');
 const {WAIT_BETWEEN_ACTIONS_IN_MS} = require('../constants');
 
@@ -29,7 +29,8 @@ module.exports = (browser) => {
             'release'
         ]);
 
-        const testCtx = getTestContext(browser.executionContext);
-        testCtx.isVerticalSwipePerformed = Boolean(yOffset);
+        if (yOffset) {
+            resetTestContextValues(browser.executionContext, [TOP_TOOLBAR_SIZE, BOTTOM_TOOLBAR_LOCATION]);
+        }
     }, true);
 };