How to use makeImageElementCache method in Appium Base Driver

...75    this._eventHistory = {76      commands: [] // commands get a special place77    };78    // cache the image elements79    this._imgElCache = makeImageElementCache();80    // used to handle driver events81    this.eventEmitter = new EventEmitter();82    this.protocol = null;83  }84  /**85   * Set a callback handler if needed to execute a custom piece of code86   * when the driver is shut down unexpectedly. Multiple calls to this method87   * will cause the handler to be executed mutiple times88   *89   * @param {Function} handler The code to be executed on unexpected shutdown.90   * The function may accept one argument, which is the actual error instance, which91   * caused the driver to shut down.92   */93  onUnexpectedShutdown (handler) {...

...214describe('image element LRU cache', function () {215  it('should accept and cache image elements', function () {216    const el1 = new ImageElement(defTemplate, defRect);217    const el2 = new ImageElement(defTemplate, defRect);218    const cache = makeImageElementCache();219    cache.set(el1.id, el1);220    el1.equals(cache.get(el1.id)).should.be.true;221    _.isUndefined(cache.get(el2.id)).should.be.true;222    cache.has(el1.id).should.be.true;223    cache.has(el2.id).should.be.false;224  });225  it('once cache reaches max size, should eject image elements', function () {226    const el1 = new ImageElement(defTemplate, defRect);227    const el2 = new ImageElement(defTemplate, defRect);228    const cache = makeImageElementCache(defTemplate.length + 1);229    cache.set(el1.id, el1);230    cache.has(el1.id).should.be.true;231    cache.set(el2.id, el2);232    cache.has(el2.id).should.be.true;233    cache.has(el1.id).should.be.false;234  });235});236describe('getImgElFromArgs', function () {237  it('should return the image element id from json obj in args', function () {238    const imgEl = `${IMAGE_ELEMENT_PREFIX}foo`;239    const args = [1, 'foo', imgEl];240    getImgElFromArgs(args).should.eql(imgEl);241  });242  it('should not return anything if image element id not in args', function () {...

1import _ from 'lodash';2import { errors } from '../..';3import LRU from 'lru-cache';4import { IMAGE_ELEMENT_PREFIX } from '../constants';5import log from './logger';6import { util } from 'appium-support';7const MAX_CACHE_SIZE = 1024 * 1024 * 40; // 40mb8const TAP_DURATION_MS = 125;9const IMAGE_EL_TAP_STRATEGY_W3C = 'w3cActions';10const IMAGE_EL_TAP_STRATEGY_MJSONWP = 'touchActions';11const IMAGE_TAP_STRATEGIES = [12  IMAGE_EL_TAP_STRATEGY_MJSONWP,13  IMAGE_EL_TAP_STRATEGY_W3C14];15const DEFAULT_TEMPLATE_IMAGE_SCALE = 1.0;16/**17 * @typedef {Object} Rect18 * @property {int} x - x-coordinate of top-left corner19 * @property {int} y - y-coordinate of top-left corner20 * @property {int} width - width of rect21 * @property {int} height - height of rect22 */23/**24 * @typedef {Object} Dimension25 * @property {int} width - width of rect26 * @property {int} height - height of rect27 */28/**29 * @typedef {Object} Position30 * @property {int} x - x coordinate31 * @property {int} y - y coordinate32 */33/**34 * Representation of an "image element", which is simply a set of coordinates35 * and methods that can be used on that set of coordinates via the driver36 */37class ImageElement {38  /**39   * @param {string} b64Template - the base64-encoded image which was used to40   *                               find this ImageElement41   * @param {Rect} rect - bounds of matched image element42   * @param {number} score The similarity score as a float number in range [0.0, 1.0].43   * 1.0 is the highest score (means both images are totally equal).44   * @param {?string} b64Result - the base64-encoded image which has matched marks.45   *                              Defaults to null.46   *47   * @returns {ImageElement}48   */49  constructor (b64Template, rect, score, b64Result = null) {50    this.template = b64Template;51    this.rect = rect;52    this.id = `${IMAGE_ELEMENT_PREFIX}${util.uuidV4()}`;53    this.b64MatchedImage = b64Result;54    this.score = score;55  }56  /**57   * @returns {Dimension} - dimension of element58   */59  get size () {60    return {width: this.rect.width, height: this.rect.height};61  }62  /**63   * @returns {Position} - coordinates of top-left corner of element64   */65  get location () {66    return {x: this.rect.x, y: this.rect.y};67  }68  /**69   * @returns {Position} - coordinates of center of element70   */71  get center () {72    return {73      x: this.rect.x + this.rect.width / 2,74      y: this.rect.y + this.rect.height / 2,75    };76  }77  /**78   * @returns {?string} - the base64-encoded image which has matched marks79   */80  get matchedImage () {81    return this.b64MatchedImage;82  }83  /**84   * @param {string} protocolKey - the protocol-specific JSON key for85   * a WebElement86   *87   * @returns {WebElement} - this image element as a WebElement88   */89  asElement (protocolKey) {90    return {[protocolKey]: this.id};91  }92  /**93   * @param {ImageElement} other - an ImageElement to compare with this one94   *95   * @returns {boolean} - whether the other element and this one have the same96   * properties97   */98  equals (other) {99    return this.rect.x === other.rect.x &&100           this.rect.y === other.rect.y &&101           this.rect.width === other.rect.width &&102           this.rect.height === other.rect.height;103  }104  /**105   * Use a driver to tap the screen at the center of this ImageElement's106   * position107   *108   * @param {BaseDriver} driver - driver for calling actions with109   */110  async click (driver) {111    // before we click we need to make sure the element is actually still there112    // where we expect it to be113    let newImgEl;114    const {115      autoUpdateImageElementPosition: updatePos,116      checkForImageElementStaleness,117      imageElementTapStrategy,118    } = driver.settings.getSettings();119    // validate tap strategy120    if (!IMAGE_TAP_STRATEGIES.includes(imageElementTapStrategy)) {121      throw new Error(`Incorrect imageElementTapStrategy setting ` +122                      `'${imageElementTapStrategy}'. Must be one of ` +123                      JSON.stringify(IMAGE_TAP_STRATEGIES));124    }125    if (checkForImageElementStaleness || updatePos) {126      log.info('Checking image element for staleness before clicking');127      try {128        newImgEl = await driver.findByImage(this.template, {129          shouldCheckStaleness: true,130          // Set ignoreDefaultImageTemplateScale because this.template is device screenshot based image131          // managed inside Appium after finidng image by template which managed by a user132          ignoreDefaultImageTemplateScale: true133        });134      } catch (err) {135        throw new errors.StaleElementReferenceError();136      }137      if (!this.equals(newImgEl)) {138        log.warn(`When trying to click on an image element, the image changed ` +139                 `position from where it was originally found. It is now at ` +140                 `${JSON.stringify(newImgEl.rect)} and was originally at ` +141                 `${JSON.stringify(this.rect)}.`);142        if (updatePos) {143          log.warn('Click will proceed at new coordinates');144          this.rect = _.clone(newImgEl.rect);145        } else {146          log.warn('Click will take place at original coordinates. If you ' +147                   'would like Appium to automatically click the new ' +148                   "coordinates, set the 'autoUpdateImageElementPosition' " +149                   'setting to true');150        }151      }152    }153    const {x, y} = this.center;154    log.info(`Will tap on image element at coordinate [${x}, ${y}]`);155    if (imageElementTapStrategy === IMAGE_EL_TAP_STRATEGY_W3C) {156      // set up a W3C action to click on the image by position157      log.info('Will tap using W3C actions');158      const action = {159        type: 'pointer',160        id: 'mouse',161        parameters: {pointerType: 'touch'},162        actions: [163          {type: 'pointerMove', x, y, duration: 0},164          {type: 'pointerDown', button: 0},165          {type: 'pause', duration: TAP_DURATION_MS},166          {type: 'pointerUp', button: 0},167        ]168      };169      // check if the driver has the appropriate performActions method170      if (driver.performActions) {171        return await driver.performActions([action]);172      }173      // if not, warn and fall back to the other method174      log.warn('Driver does not seem to implement W3C actions, falling back ' +175               'to TouchActions');176    }177    // if the w3c strategy was not requested, do the only other option (mjsonwp178    // touch actions)179    log.info('Will tap using MJSONWP TouchActions');180    const action = {181      action: 'tap',182      options: {x, y}183    };184    if (driver.performTouch) {185      return await driver.performTouch([action]);186    }187    throw new Error("Driver did not implement the 'performTouch' command. " +188                    'For drivers to support finding image elements, they ' +189                    "should support 'performTouch' and 'performActions'");190  }191  /**192   * Handle various Appium commands that involve an image element193   *194   * @param {BaseDriver} driver - the driver to use for commands195   * @param {string} cmd - the name of the driver command196   * @param {string} imgElId - the id of the ImageElement to work with197   * @param {Array} args - Rest of arguments for executeScripts198   *199   * @returns {Object} - the result of running a command200   */201  static async execute (driver, cmd, imgElId, ...args) {202    if (!driver._imgElCache.has(imgElId)) {203      throw new errors.NoSuchElementError();204    }205    const imgEl = driver._imgElCache.get(imgElId);206    switch (cmd) {207      case 'click':208        return await imgEl.click(driver);209      case 'elementDisplayed':210        return true;211      case 'getSize':212        return imgEl.size;213      case 'getLocation':214      case 'getLocationInView':215        return imgEl.location;216      case 'getElementRect':217        return imgEl.rect;218      case 'getAttribute':219        // /session/:sessionId/element/:elementId/attribute/:name220        // /session/:sessionId/element/:elementId/attribute/visual should retun the visual data221        // e.g. ["content-desc","appium-image-element-xxxxx","xxxxx"], ["visual","appium-image-element-xxxxx","xxxxx"]222        switch (args[0]) {223          case 'visual':224            return imgEl.matchedImage;225          case 'score':226            return imgEl.score;227          default:228            throw new errors.NotYetImplementedError();229        }230      default: throw new errors.NotYetImplementedError();231    }232  }233}234function makeImageElementCache (max = MAX_CACHE_SIZE) {235  return new LRU({236    max,237    length: (el) => el.template.length,238  });239}240function getImgElFromArgs (args) {241  for (let arg of args) {242    if (_.isString(arg) && arg.startsWith(IMAGE_ELEMENT_PREFIX)) {243      return arg;244    }245  }246}247export {248  ImageElement, getImgElFromArgs, makeImageElementCache,249  IMAGE_EL_TAP_STRATEGY_MJSONWP, IMAGE_EL_TAP_STRATEGY_W3C,250  DEFAULT_TEMPLATE_IMAGE_SCALE...