@appium/images-plugin 2.0.10 → 2.1.0

package/lib/image-element.js

@@ -2,14 +2,12 @@ import _ from 'lodash';
 import {errors} from 'appium/driver';
 import {util} from 'appium/support';
 import log from './logger';
-import {DEFAULT_SETTINGS} from './finder';
+import {
+  IMAGE_STRATEGY, DEFAULT_SETTINGS, IMAGE_TAP_STRATEGIES,
+  IMAGE_ELEMENT_PREFIX, IMAGE_EL_TAP_STRATEGY_W3C,
+} from './constants';
 
-const IMAGE_ELEMENT_PREFIX = 'appium-image-element-';
 const TAP_DURATION_MS = 125;
-const IMAGE_EL_TAP_STRATEGY_W3C = 'w3cActions';
-const IMAGE_EL_TAP_STRATEGY_MJSONWP = 'touchActions';
-const IMAGE_TAP_STRATEGIES = [IMAGE_EL_TAP_STRATEGY_MJSONWP, IMAGE_EL_TAP_STRATEGY_W3C];
-const DEFAULT_TEMPLATE_IMAGE_SCALE = 1.0;
 
 /**
  * @typedef Dimension
@@ -23,28 +21,41 @@ const DEFAULT_TEMPLATE_IMAGE_SCALE = 1.0;
  * @property {number} y - y coordinate
  */
 
+/**
+ * @typedef ImageElementOpts
+ * @property {Buffer} template - the image which was used to find this ImageElement
+ * @property {Rect} rect - bounds of matched image element
+ * @property {number} score The similarity score as a float number in range [0.0, 1.0].
+ * 1.0 is the highest score (means both images are totally equal).
+ * @property {Buffer?} match - the image which has matched marks. Defaults to null.
+ * @property {import('./finder').default?} finder - the finder we can use to re-check stale elements
+ * @property {import('@appium/types').Rect?} containerRect - The bounding
+ * rectangle to limit the search in
+ */
+
 /**
  * Representation of an "image element", which is simply a set of coordinates
  * and methods that can be used on that set of coordinates via the driver
  */
 export default class ImageElement {
   /**
-   * @param {string} b64Template - the base64-encoded image which was used to
-   *                               find this ImageElement
-   * @param {Rect} rect - bounds of matched image element
-   * @param {number} score The similarity score as a float number in range [0.0, 1.0].
-   * 1.0 is the highest score (means both images are totally equal).
-   * @param {string?} b64Result - the base64-encoded image which has matched marks.
-   *                              Defaults to null.
-   * @param {import('./finder').default?} finder - the finder we can use to re-check stale elements
+   * @param {ImageElementOpts}
    */
-  constructor(b64Template, rect, score, b64Result = null, finder = null) {
-    this.template = b64Template;
+  constructor({
+    template,
+    rect,
+    score,
+    match = null,
+    finder = null,
+    containerRect = null,
+  }) {
+    this.template = template;
     this.rect = rect;
     this.id = `${IMAGE_ELEMENT_PREFIX}${util.uuidV4()}`;
-    this.b64MatchedImage = b64Result;
+    this.match = match;
     this.score = score;
     this.finder = finder;
+    this.containerRect = containerRect;
   }
 
   /**
@@ -72,20 +83,25 @@ export default class ImageElement {
   }
 
   /**
-   * @returns {?string} - the base64-encoded image which has matched marks
+   * @returns {string} - the base64-encoded original image used for matching
+   */
+  get originalImage() {
+    return this.template.toString('base64');
+  }
+
+  /**
+   * @returns {string|null} - the base64-encoded image which has matched marks
    */
   get matchedImage() {
-    return this.b64MatchedImage;
+    return this.match?.toString('base64') ?? null;
   }
 
   /**
-   * @param {string} protocolKey - the protocol-specific JSON key for
-   * a WebElement
    *
    * @returns {Element} - this image element as a WebElement
    */
-  asElement(protocolKey) {
-    return {[protocolKey]: this.id};
+  asElement() {
+    return util.wrapElement(this.id);
   }
 
   /**
@@ -132,11 +148,12 @@ export default class ImageElement {
     if (checkForImageElementStaleness || updatePos) {
       log.info('Checking image element for staleness before clicking');
       try {
-        newImgEl = await this.finder.findByImage(this.template, {
+        newImgEl = await this.finder.findByImage(this.template, driver, {
           shouldCheckStaleness: true,
           // Set ignoreDefaultImageTemplateScale because this.template is device screenshot based image
           // managed inside Appium after finidng image by template which managed by a user
           ignoreDefaultImageTemplateScale: true,
+          containerRect: this.containerRect,
         });
       } catch (err) {
         throw new errors.StaleElementReferenceError();
@@ -209,6 +226,22 @@ export default class ImageElement {
     );
   }
 
+  /**
+   * Perform lookup of image element(s) inside of the current element
+   *
+   * @param {boolean} multiple - Whether to lookup multiple elements
+   * @param {import('appium/driver').BaseDriver} driver - The driver to use for commands
+   * @param  {string[]} args = Rest of arguments for executeScripts
+   * @returns {Promise<Element|Element[]|ImageElement>} - WebDriver element with a special id prefix
+   */
+  async find(multiple, driver, ...args) {
+    const [strategy, selector] = args;
+    if (strategy !== IMAGE_STRATEGY) {
+      throw new errors.InvalidSelectorError(`Lookup strategies other than '${IMAGE_STRATEGY}' are not supported`);
+    }
+    return await this.finder.findByImage(selector, driver, {multiple, containerRect: this.rect});
+  }
+
   /**
    * Handle various Appium commands that involve an image element
    *
@@ -223,6 +256,10 @@ export default class ImageElement {
     switch (cmd) {
       case 'click':
         return await imgEl.click(driver);
+      case 'findElementFromElement':
+        return await imgEl.find(false, driver, ...args);
+      case 'findElementsFromElement':
+        return await imgEl.find(true, driver, ...args);
       case 'elementDisplayed':
         return true;
       case 'getSize':
@@ -232,6 +269,8 @@ export default class ImageElement {
         return imgEl.location;
       case 'getElementRect':
         return imgEl.rect;
+      case 'getElementScreenshot':
+        return imgEl.originalImage;
       case 'getAttribute':
         // /session/:sessionId/element/:elementId/attribute/:name
         // /session/:sessionId/element/:elementId/attribute/visual should retun the visual data
@@ -250,13 +289,7 @@ export default class ImageElement {
   }
 }
 
-export {
-  ImageElement,
-  IMAGE_EL_TAP_STRATEGY_MJSONWP,
-  IMAGE_EL_TAP_STRATEGY_W3C,
-  DEFAULT_TEMPLATE_IMAGE_SCALE,
-  IMAGE_ELEMENT_PREFIX,
-};
+export {ImageElement};
 
 /**
  * @typedef {import('@appium/types').Rect} Rect

package/lib/plugin.js

@@ -5,16 +5,11 @@ import {errors} from 'appium/driver';
 import BasePlugin from 'appium/plugin';
 import {compareImages} from './compare';
 import ImageElementFinder from './finder';
-import {ImageElement, IMAGE_ELEMENT_PREFIX} from './image-element';
-
-const IMAGE_STRATEGY = '-image';
+import {ImageElement} from './image-element';
+import {IMAGE_STRATEGY, IMAGE_ELEMENT_PREFIX} from './constants';
 
 function getImgElFromArgs(args) {
-  for (let arg of args) {
-    if (_.isString(arg) && arg.startsWith(IMAGE_ELEMENT_PREFIX)) {
-      return arg;
-    }
-  }
+  return args.find((arg) => _.isString(arg) && arg.startsWith(IMAGE_ELEMENT_PREFIX));
 }
 
 export default class ImageElementPlugin extends BasePlugin {
@@ -57,8 +52,7 @@ export default class ImageElementPlugin extends BasePlugin {
       return await next();
     }
 
-    this.finder.setDriver(driver);
-    return await this.finder.findByImage(selector, {multiple});
+    return await this.finder.findByImage(selector, driver, {multiple});
   }
 
   async handle(next, driver, cmdName, ...args) {
@@ -66,13 +60,17 @@ export default class ImageElementPlugin extends BasePlugin {
     // and execute the command on it
     const imgElId = getImgElFromArgs(args);
     if (imgElId) {
-      if (!this.finder.imgElCache.has(imgElId)) {
+      const imgEl = this.finder.getImageElement(imgElId);
+      if (!imgEl) {
         throw new errors.NoSuchElementError();
       }
-      const imgEl = this.finder.imgElCache.get(imgElId);
       return await ImageElement.execute(driver, imgEl, cmdName, ...args);
     }
 
+    if (cmdName === 'deleteSession') {
+      this.finder.clearImageElements();
+    }
+
     // otherwise just do the normal thing
     return await next();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/images-plugin",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "description": "Plugin for working with images and image elements in Appium",
   "keywords": [
     "automation",
@@ -39,9 +39,10 @@
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/opencv": "^2.0.10",
+    "@appium/opencv": "^2.1.0",
     "lodash": "4.17.21",
     "lru-cache": "7.18.3",
+    "sharp": "0.32.1",
     "source-map-support": "0.5.21"
   },
   "peerDependencies": {
@@ -58,7 +59,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "591d15bc5e65383f824fc8eaa5f2814266a34df4",
+  "gitHead": "6b245534c213f3b8d6405515aee1e89133295098",
   "typedoc": {
     "entryPoint": "./lib/plugin.js"
   }