@appium/images-plugin 1.2.3 → 1.3.2

package/lib/finder.js

@@ -1,10 +1,13 @@
 import _ from 'lodash';
 import LRU from 'lru-cache';
-import { imageUtil, util } from '@appium/support';
-import { errors } from '@appium/base-driver';
-import { ImageElement, DEFAULT_TEMPLATE_IMAGE_SCALE,
-         IMAGE_EL_TAP_STRATEGY_W3C } from './image-element';
-import { MATCH_TEMPLATE_MODE, compareImages, DEFAULT_MATCH_THRESHOLD } from './compare';
+import {errors} from 'appium/driver';
+import {util, imageUtil} from 'appium/support';
+import {
+  ImageElement,
+  DEFAULT_TEMPLATE_IMAGE_SCALE,
+  IMAGE_EL_TAP_STRATEGY_W3C,
+} from './image-element';
+import {MATCH_TEMPLATE_MODE, compareImages, DEFAULT_MATCH_THRESHOLD} from './compare';
 import log from './logger';
 
 const MJSONWP_ELEMENT_KEY = 'ELEMENT';
@@ -13,7 +16,8 @@ const DEFAULT_FIX_IMAGE_TEMPLATE_SCALE = 1;
 // Used to compare ratio and screen width
 // Pixel is basically under 1080 for example. 100K is probably enough fo a while.
 const FLOAT_PRECISION = 100000;
-const MAX_CACHE_SIZE = 1024 * 1024 * 40; // 40mb
+const MAX_CACHE_ITEMS = 100;
+const MAX_CACHE_SIZE_BYTES = 1024 * 1024 * 40; // 40mb
 
 const DEFAULT_SETTINGS = {
   // value between 0 and 1 representing match strength, below which an image
@@ -69,26 +73,42 @@ const DEFAULT_SETTINGS = {
 };
 
 export default class ImageElementFinder {
-  constructor (driver, max = MAX_CACHE_SIZE) {
+  /** @type {ExternalDriver} */
+  driver;
+
+  /** @type {LRU<string,ImageElement>} */
+  imgElCache;
+
+  /**
+   *
+   * @param {ExternalDriver} driver
+   * @param {number} [maxSize]
+   */
+  constructor(driver, maxSize = MAX_CACHE_SIZE_BYTES) {
     this.driver = driver;
     this.imgElCache = new LRU({
-      max,
-      length: (el) => el.template.length,
+      max: MAX_CACHE_ITEMS,
+      maxSize,
+      sizeCalculation: (el) => el.template.length,
     });
   }
 
-  setDriver (driver) {
+  setDriver(driver) {
     this.driver = driver;
   }
 
-  registerImageElement (imgEl) {
+  /**
+   * @param {ImageElement} imgEl
+   * @returns {Element}
+   */
+  registerImageElement(imgEl) {
     this.imgElCache.set(imgEl.id, imgEl);
     const protoKey = this.driver.isW3CProtocol() ? W3C_ELEMENT_KEY : MJSONWP_ELEMENT_KEY;
     return imgEl.asElement(protoKey);
   }
 
   /**
-   * @typedef {Object} FindByImageOptions
+   * @typedef FindByImageOptions
    * @property {boolean} [shouldCheckStaleness=false] - whether this call to find an
    * image is merely to check staleness. If so we can bypass a lot of logic
    * @property {boolean} [multiple=false] - Whether we are finding one element or
@@ -104,26 +124,25 @@ export default class ImageElementFinder {
    *
    * @param {string} b64Template - base64-encoded image used as a template to be
    * matched in the screenshot
-   * @param {FindByImageOptions} - additional options
+   * @param {FindByImageOptions} opts - additional options
    *
-   * @returns {WebElement} - WebDriver element with a special id prefix
+   * @returns {Promise<Element|Element[]|ImageElement>} - WebDriver element with a special id prefix
    */
-  async findByImage (b64Template, {
-    shouldCheckStaleness = false,
-    multiple = false,
-    ignoreDefaultImageTemplateScale = false,
-  }) {
+  async findByImage(
+    b64Template,
+    {shouldCheckStaleness = false, multiple = false, ignoreDefaultImageTemplateScale = false}
+  ) {
     if (!this.driver) {
       throw new Error(`Can't find without a driver!`);
     }
-    const settings = Object.assign({}, DEFAULT_SETTINGS, this.driver.settings.getSettings());
+    const settings = {...DEFAULT_SETTINGS, ...this.driver.settings.getSettings()};
     const {
       imageMatchThreshold: threshold,
       imageMatchMethod,
       fixImageTemplateSize,
       fixImageTemplateScale,
       defaultImageTemplateScale,
-      getMatchedImageResult: visualize
+      getMatchedImageResult: visualize,
     } = settings;
 
     log.info(`Finding image element with match threshold ${threshold}`);
@@ -137,18 +156,22 @@ export default class ImageElementFinder {
     // will not work unless we do. But because it requires some potentially
     // expensive commands, only do this if the user has requested it in settings.
     if (fixImageTemplateSize) {
-      b64Template = await this.ensureTemplateSize(b64Template, screenWidth,
-        screenHeight);
+      b64Template = await this.ensureTemplateSize(b64Template, screenWidth, screenHeight);
     }
 
     const results = [];
     const condition = async () => {
       try {
-        const {b64Screenshot, scale} = await this.getScreenshotForImageFind(screenWidth, screenHeight);
+        const {b64Screenshot, scale} = await this.getScreenshotForImageFind(
+          screenWidth,
+          screenHeight
+        );
 
         b64Template = await this.fixImageTemplateScale(b64Template, {
-          defaultImageTemplateScale, ignoreDefaultImageTemplateScale,
-          fixImageTemplateScale, ...scale
+          defaultImageTemplateScale,
+          ignoreDefaultImageTemplateScale,
+          fixImageTemplateScale,
+          ...scale,
         });
 
         const comparisonOpts = {
@@ -160,18 +183,20 @@ export default class ImageElementFinder {
           comparisonOpts.method = imageMatchMethod;
         }
         if (multiple) {
-          results.push(...(await compareImages(MATCH_TEMPLATE_MODE,
-                                               b64Screenshot,
-                                               b64Template,
-                                               comparisonOpts)));
+          results.push(
+            ...(await compareImages(
+              MATCH_TEMPLATE_MODE,
+              b64Screenshot,
+              b64Template,
+              comparisonOpts
+            ))
+          );
         } else {
-          results.push(await compareImages(MATCH_TEMPLATE_MODE,
-                                           b64Screenshot,
-                                           b64Template,
-                                           comparisonOpts));
+          results.push(
+            await compareImages(MATCH_TEMPLATE_MODE, b64Screenshot, b64Template, comparisonOpts)
+          );
         }
         return true;
-
       } catch (err) {
         // if compareImages fails, we'll get a specific error, but we should
         // retry, so trap that and just return false to trigger the next round of
@@ -226,47 +251,42 @@ export default class ImageElementFinder {
    * Ensure that the image template sent in for a find is of a suitable size
    *
    * @param {string} b64Template - base64-encoded image
-   * @param {int} screenWidth - width of screen
-   * @param {int} screenHeight - height of screen
+   * @param {number} screenWidth - width of screen
+   * @param {number} screenHeight - height of screen
    *
-   * @returns {string} base64-encoded image, potentially resized
+   * @returns {Promise<string>} base64-encoded image, potentially resized
    */
-  async ensureTemplateSize (b64Template, screenWidth, screenHeight) {
+  async ensureTemplateSize(b64Template, screenWidth, screenHeight) {
     let imgObj = await imageUtil.getJimpImage(b64Template);
     let {width: tplWidth, height: tplHeight} = imgObj.bitmap;
 
-    log.info(`Template image is ${tplWidth}x${tplHeight}. Screen size is ${screenWidth}x${screenHeight}`);
+    log.info(
+      `Template image is ${tplWidth}x${tplHeight}. Screen size is ${screenWidth}x${screenHeight}`
+    );
     // if the template fits inside the screen dimensions, we're good
     if (tplWidth <= screenWidth && tplHeight <= screenHeight) {
       return b64Template;
     }
 
-    log.info(`Scaling template image from ${tplWidth}x${tplHeight} to match ` +
-             `screen at ${screenWidth}x${screenHeight}`);
+    log.info(
+      `Scaling template image from ${tplWidth}x${tplHeight} to match ` +
+        `screen at ${screenWidth}x${screenHeight}`
+    );
     // otherwise, scale it to fit inside the screen dimensions
     imgObj = imgObj.scaleToFit(screenWidth, screenHeight);
     return (await imgObj.getBuffer(imageUtil.MIME_PNG)).toString('base64');
   }
 
-  /**
-   * @typedef {Object} Screenshot
-   * @property {string} b64Screenshot - base64 based screenshot string
-   */
-  /**
-   * @typedef {Object} ScreenshotScale
-   * @property {float} xScale - Scale ratio for width
-   * @property {float} yScale - Scale ratio for height
-   */
   /**
    * Get the screenshot image that will be used for find by element, potentially
    * altering it in various ways based on user-requested settings
    *
-   * @param {int} screenWidth - width of screen
-   * @param {int} screenHeight - height of screen
+   * @param {number} screenWidth - width of screen
+   * @param {number} screenHeight - height of screen
    *
-   * @returns {Screenshot, ?ScreenshotScale} base64-encoded screenshot and ScreenshotScale
+   * @returns {Promise<Screenshot & {scale?: ScreenshotScale}>} base64-encoded screenshot and ScreenshotScale
    */
-  async getScreenshotForImageFind (screenWidth, screenHeight) {
+  async getScreenshotForImageFind(screenWidth, screenHeight) {
     if (!this.driver.getScreenshot) {
       throw new Error("This driver does not support the required 'getScreenshot' command");
     }
@@ -283,8 +303,10 @@ export default class ImageElementFinder {
     }
 
     if (screenWidth < 1 || screenHeight < 1) {
-      log.warn(`The retrieved screen size ${screenWidth}x${screenHeight} does ` +
-        `not seem to be valid. No changes will be applied to the screenshot`);
+      log.warn(
+        `The retrieved screen size ${screenWidth}x${screenHeight} does ` +
+          `not seem to be valid. No changes will be applied to the screenshot`
+      );
       return {b64Screenshot};
     }
 
@@ -296,8 +318,10 @@ export default class ImageElementFinder {
     let {width: shotWidth, height: shotHeight} = imgObj.bitmap;
 
     if (shotWidth < 1 || shotHeight < 1) {
-      log.warn(`The retrieved screenshot size ${shotWidth}x${shotHeight} does ` +
-        `not seem to be valid. No changes will be applied to the screenshot`);
+      log.warn(
+        `The retrieved screenshot size ${shotWidth}x${shotHeight} does ` +
+          `not seem to be valid. No changes will be applied to the screenshot`
+      );
       return {b64Screenshot};
     }
 
@@ -319,13 +343,17 @@ export default class ImageElementFinder {
     const screenAR = screenWidth / screenHeight;
     const shotAR = shotWidth / shotHeight;
     if (Math.round(screenAR * FLOAT_PRECISION) === Math.round(shotAR * FLOAT_PRECISION)) {
-      log.info(`Screenshot aspect ratio '${shotAR}' (${shotWidth}x${shotHeight}) matched ` +
-        `screen aspect ratio '${screenAR}' (${screenWidth}x${screenHeight})`);
+      log.info(
+        `Screenshot aspect ratio '${shotAR}' (${shotWidth}x${shotHeight}) matched ` +
+          `screen aspect ratio '${screenAR}' (${screenWidth}x${screenHeight})`
+      );
     } else {
-      log.warn(`When trying to find an element, determined that the screen ` +
-               `aspect ratio and screenshot aspect ratio are different. Screen ` +
-               `is ${screenWidth}x${screenHeight} whereas screenshot is ` +
-               `${shotWidth}x${shotHeight}.`);
+      log.warn(
+        `When trying to find an element, determined that the screen ` +
+          `aspect ratio and screenshot aspect ratio are different. Screen ` +
+          `is ${screenWidth}x${screenHeight} whereas screenshot is ` +
+          `${shotWidth}x${shotHeight}.`
+      );
 
       // In the case where the x-scale and y-scale are different, we need to decide
       // which one to respect, otherwise the screenshot and template will end up
@@ -342,9 +370,11 @@ export default class ImageElementFinder {
       const yScale = (1.0 * shotHeight) / screenHeight;
       const scaleFactor = xScale >= yScale ? yScale : xScale;
 
-      log.warn(`Resizing screenshot to ${shotWidth * scaleFactor}x${shotHeight * scaleFactor} to match ` +
-               `screen aspect ratio so that image element coordinates have a ` +
-               `greater chance of being correct.`);
+      log.warn(
+        `Resizing screenshot to ${shotWidth * scaleFactor}x${shotHeight * scaleFactor} to match ` +
+          `screen aspect ratio so that image element coordinates have a ` +
+          `greater chance of being correct.`
+      );
       imgObj = imgObj.resize(shotWidth * scaleFactor, shotHeight * scaleFactor);
 
       scale.xScale *= scaleFactor;
@@ -359,8 +389,10 @@ export default class ImageElementFinder {
     // screenshot size like `@driver.window_rect #=>x=0, y=0, width=1080, height=1794` and
     // `"deviceScreenSize"=>"1080x1920"`
     if (screenWidth !== shotWidth && screenHeight !== shotHeight) {
-      log.info(`Scaling screenshot from ${shotWidth}x${shotHeight} to match ` +
-               `screen at ${screenWidth}x${screenHeight}`);
+      log.info(
+        `Scaling screenshot from ${shotWidth}x${shotHeight} to match ` +
+          `screen at ${screenWidth}x${screenHeight}`
+      );
       imgObj = imgObj.resize(screenWidth, screenHeight);
 
       scale.xScale *= (1.0 * screenWidth) / shotWidth;
@@ -372,14 +404,14 @@ export default class ImageElementFinder {
   }
 
   /**
-   * @typedef {Object} ImageTemplateSettings
+   * @typedef ImageTemplateSettings
    * @property {boolean} fixImageTemplateScale - fixImageTemplateScale in device-settings
-   * @property {float} defaultImageTemplateScale - defaultImageTemplateScale in device-settings
+   * @property {number} defaultImageTemplateScale - defaultImageTemplateScale in device-settings
    * @property {boolean} ignoreDefaultImageTemplateScale - Ignore defaultImageTemplateScale if it has true.
    * If b64Template has been scaled to defaultImageTemplateScale or should ignore the scale,
    * this parameter should be true. e.g. click in image-element module
-   * @property {float} xScale - Scale ratio for width
-   * @property {float} yScale - Scale ratio for height
+   * @property {number} xScale - Scale ratio for width
+   * @property {number} yScale - Scale ratio for height
 
    */
   /**
@@ -391,9 +423,9 @@ export default class ImageElementFinder {
    * matched in the screenshot
    * @param {ImageTemplateSettings} opts - Image template scale related options
    *
-   * @returns {string} base64-encoded scaled template screenshot
+   * @returns {Promise<string>} base64-encoded scaled template screenshot
    */
-  async fixImageTemplateScale (b64Template, opts = {}) {
+  async fixImageTemplateScale(b64Template, opts) {
     if (!opts) {
       return b64Template;
     }
@@ -403,7 +435,7 @@ export default class ImageElementFinder {
       defaultImageTemplateScale = DEFAULT_TEMPLATE_IMAGE_SCALE,
       ignoreDefaultImageTemplateScale = false,
       xScale = DEFAULT_FIX_IMAGE_TEMPLATE_SCALE,
-      yScale = DEFAULT_FIX_IMAGE_TEMPLATE_SCALE
+      yScale = DEFAULT_FIX_IMAGE_TEMPLATE_SCALE,
     } = opts;
 
     if (ignoreDefaultImageTemplateScale) {
@@ -424,13 +456,21 @@ export default class ImageElementFinder {
     }
 
     // xScale and yScale can be NaN if defaultImageTemplateScale is string, for example
-    if (!parseFloat(xScale) || !parseFloat(yScale)) {
+    if (!parseFloat(String(xScale)) || !parseFloat(String(yScale))) {
       return b64Template;
     }
 
     // Return if the scale is default, 1, value
-    if (Math.round(xScale * FLOAT_PRECISION) === Math.round(DEFAULT_FIX_IMAGE_TEMPLATE_SCALE * FLOAT_PRECISION)
-        && Math.round(yScale * FLOAT_PRECISION === Math.round(DEFAULT_FIX_IMAGE_TEMPLATE_SCALE * FLOAT_PRECISION))) {
+    if (
+      Math.round(xScale * FLOAT_PRECISION) ===
+        Math.round(DEFAULT_FIX_IMAGE_TEMPLATE_SCALE * FLOAT_PRECISION) &&
+      Math.round(
+        Number(
+          yScale * FLOAT_PRECISION ===
+            Math.round(DEFAULT_FIX_IMAGE_TEMPLATE_SCALE * FLOAT_PRECISION)
+        )
+      )
+    ) {
       return b64Template;
     }
 
@@ -439,12 +479,30 @@ export default class ImageElementFinder {
 
     const scaledWidth = baseTempWidth * xScale;
     const scaledHeight = baseTempHeigh * yScale;
-    log.info(`Scaling template image from ${baseTempWidth}x${baseTempHeigh}` +
-              ` to ${scaledWidth}x${scaledHeight}`);
+    log.info(
+      `Scaling template image from ${baseTempWidth}x${baseTempHeigh}` +
+        ` to ${scaledWidth}x${scaledHeight}`
+    );
     log.info(`The ratio is ${xScale} and ${yScale}`);
     imgTempObj = await imgTempObj.resize(scaledWidth, scaledHeight);
     return (await imgTempObj.getBuffer(imageUtil.MIME_PNG)).toString('base64');
   }
 }
 
-export { W3C_ELEMENT_KEY, MJSONWP_ELEMENT_KEY, DEFAULT_SETTINGS, DEFAULT_FIX_IMAGE_TEMPLATE_SCALE };
+export {W3C_ELEMENT_KEY, MJSONWP_ELEMENT_KEY, DEFAULT_SETTINGS, DEFAULT_FIX_IMAGE_TEMPLATE_SCALE};
+
+/**
+ * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
+ * @typedef {import('@appium/types').Element} Element
+ */
+
+/**
+ * @typedef Screenshot
+ * @property {string} b64Screenshot - base64 based screenshot string
+ */
+
+/**
+ * @typedef ScreenshotScale
+ * @property {number} xScale - Scale ratio for width
+ * @property {number} yScale - Scale ratio for height
+ */