@appium/universal-xml-plugin 2.0.3 → 2.1.0

package/build/lib/logger.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const support_1 = require("appium/support");
-const log = support_1.logger.getLogger('UniversalXMLPlugin');
-exports.default = log;
-//# sourceMappingURL=logger.js.map

package/build/lib/logger.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../lib/logger.js"],"names":[],"mappings":";;AAAA,4CAAsC;AACtC,MAAM,GAAG,GAAG,gBAAM,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;AACnD,kBAAe,GAAG,CAAC"}

package/index.js

@@ -1,7 +0,0 @@
-const {main, UniversalXMLPlugin} = require('./build/lib');
-
-if (require.main === module) {
-  (async () => await main())();
-}
-
-module.exports = {UniversalXMLPlugin};

package/lib/logger.js

@@ -1,3 +0,0 @@
-import {logger} from 'appium/support';
-const log = logger.getLogger('UniversalXMLPlugin');
-export default log;

package/lib/plugin.js

@@ -1,81 +0,0 @@
-import {BasePlugin} from 'appium/plugin';
-import {errors} from 'appium/driver';
-import {transformSourceXml} from './source';
-import {transformQuery} from './xpath';
-import log from './logger';
-
-export default class UniversalXMLPlugin extends BasePlugin {
-  async getPageSource(next, driver, sessId, addIndexPath = false) {
-    const source = next ? await next() : await driver.getPageSource();
-    const metadata = {};
-    const {platformName} = driver.caps;
-    if (platformName.toLowerCase() === 'android') {
-      metadata.appPackage = driver.opts.appPackage;
-    }
-    const {xml, unknowns} = await transformSourceXml(source, platformName.toLowerCase(), {
-      metadata,
-      addIndexPath,
-    });
-    if (unknowns.nodes.length) {
-      log.warn(
-        `The XML mapper found ${unknowns.nodes.length} node(s) / ` +
-          `tag name(s) that it didn't know about. These should be ` +
-          `reported to improve the quality of the plugin: ` +
-          unknowns.nodes.join(', '),
-      );
-    }
-    if (unknowns.attrs.length) {
-      log.warn(
-        `The XML mapper found ${unknowns.attrs.length} attributes ` +
-          `that it didn't know about. These should be reported to ` +
-          `improve the quality of the plugin: ` +
-          unknowns.attrs.join(', '),
-      );
-    }
-    return xml;
-  }
-
-  async findElement(...args) {
-    return await this._find(false, ...args);
-  }
-
-  async findElements(...args) {
-    return await this._find(true, ...args);
-  }
-
-  async _find(multiple, next, driver, strategy, selector) {
-    const {platformName} = driver.caps;
-    if (strategy.toLowerCase() !== 'xpath' || (await driver.getCurrentContext()) !== 'NATIVE_APP') {
-      return await next();
-    }
-    const xml = await this.getPageSource(null, driver, null, true);
-    let newSelector = transformQuery(selector, xml, multiple);
-
-    // if the selector was not able to be transformed, that means no elements were found that
-    // matched, so do the appropriate thing based on element vs elements
-    if (newSelector === null) {
-      log.warn(
-        `Selector was not able to be translated to underlying XML. Either the requested ` +
-          `element does not exist or there was an error in translation`,
-      );
-      if (multiple) {
-        return [];
-      }
-      throw new errors.NoSuchElementError();
-    }
-
-    if (platformName.toLowerCase() === 'ios') {
-      // with the XCUITest driver, the <AppiumAUT> wrapper element is present in the source but is
-      // not present in the source considered by WDA, so our index path based xpath queries will
-      // not work with WDA as-is. We need to remove the first path segment.
-      newSelector = newSelector.replace(/^\/\*\[1\]/, '');
-    }
-    log.info(`Selector was translated to: ${newSelector}`);
-
-    // otherwise just run the transformed query!
-    const finder = multiple ? 'findElements' : 'findElement';
-    return await driver[finder](strategy, newSelector);
-  }
-}
-
-export {UniversalXMLPlugin};

package/lib/source.js

@@ -1,226 +0,0 @@
-import _ from 'lodash';
-import NODE_MAP from './node-map';
-import {ATTR_MAP, REMOVE_ATTRS} from './attr-map';
-import TRANSFORMS from './transformers';
-
-export const ATTR_PREFIX = '@_';
-export const IDX_PATH_PREFIX = `${ATTR_PREFIX}indexPath`;
-export const IDX_PREFIX = `${ATTR_PREFIX}index`;
-
-const isAttr = (/** @type {string} */ k) => k.startsWith(ATTR_PREFIX);
-const isNode = (/** @type {string} */ k) => !isAttr(k);
-
-/**
- *
- * @param {string} xmlStr
- * @param {string} platform
- * @param {{metadata?: Object, addIndexPath?: boolean}} opts
- * @returns {Promise<{xml: string, unknowns: NodesAndAttributes}>}
- */
-export async function transformSourceXml(xmlStr, platform, {metadata = {}, addIndexPath = false} = {}) {
-  // first thing we want to do is modify the ios source root node, because it doesn't include the
-  // necessary index attribute, so we add it if it's not there
-  xmlStr = xmlStr.replace('<AppiumAUT>', '<AppiumAUT index="0">');
-  const xmlObj = (await singletonXmlParser()).parse(xmlStr);
-  const unknowns = transformNode(xmlObj, platform, {
-    metadata,
-    addIndexPath,
-    parentPath: '',
-  });
-  let transformedXml = (await singletonXmlBuilder()).build(xmlObj).trim();
-  transformedXml = `<?xml version="1.0" encoding="UTF-8"?>\n${transformedXml}`;
-  return {xml: transformedXml, unknowns};
-}
-
-/**
- *
- * @param {Object} nameMap
- * @param {string} name
- * @param {string} platform
- * @returns {string | null}
- */
-function getUniversalName(nameMap, name, platform) {
-  for (const translatedName of Object.keys(nameMap)) {
-    const sourceNodes = nameMap[translatedName]?.[platform];
-    if (_.isArray(sourceNodes) && sourceNodes.includes(name)) {
-      return translatedName;
-    }
-    if (sourceNodes === name) {
-      return translatedName;
-    }
-  }
-  return null;
-}
-
-/**
- *
- * @param {any} nodeName
- * @param {string} platform
- * @returns {string?}
- */
-export function getUniversalNodeName(nodeName, platform) {
-  return getUniversalName(NODE_MAP, nodeName, platform);
-}
-
-/**
- *
- * @param {string} attrName
- * @param {string} platform
- * @returns {string?}
- */
-export function getUniversalAttrName(attrName, platform) {
-  return getUniversalName(ATTR_MAP, attrName, platform);
-}
-
-/**
- *
- * @param {any} nodeObj
- * @param {string} platform
- * @param {{metadata?: Object, addIndexPath?: boolean, parentPath?: string}} opts
- * @returns {NodesAndAttributes}
- */
-export function transformNode(nodeObj, platform, {metadata, addIndexPath, parentPath}) {
-  const unknownNodes = [];
-  const unknownAttrs = [];
-  if (_.isPlainObject(nodeObj)) {
-    const keys = Object.keys(nodeObj);
-    const childNodeNames = keys.filter(isNode);
-    const attrs = keys.filter(isAttr);
-    let thisIndexPath = parentPath;
-
-    if (attrs.length && addIndexPath) {
-      if (!attrs.includes(IDX_PREFIX)) {
-        throw new Error(`Index path is required but node found with no 'index' attribute`);
-      }
-
-      thisIndexPath = `${parentPath}/${nodeObj[IDX_PREFIX]}`;
-      nodeObj[IDX_PATH_PREFIX] = thisIndexPath;
-    }
-
-    TRANSFORMS[platform]?.(nodeObj, metadata);
-    unknownAttrs.push(...transformAttrs(nodeObj, attrs, platform));
-    const unknowns = transformChildNodes(nodeObj, childNodeNames, platform, {
-      metadata,
-      addIndexPath,
-      parentPath: thisIndexPath,
-    });
-    unknownAttrs.push(...unknowns.attrs);
-    unknownNodes.push(...unknowns.nodes);
-  } else if (_.isArray(nodeObj)) {
-    for (const childObj of nodeObj) {
-      const {nodes, attrs} = transformNode(childObj, platform, {
-        metadata,
-        addIndexPath,
-        parentPath,
-      });
-      unknownNodes.push(...nodes);
-      unknownAttrs.push(...attrs);
-    }
-  }
-  return {
-    nodes: _.uniq(unknownNodes),
-    attrs: _.uniq(unknownAttrs),
-  };
-}
-
-/**
- *
- * @param {any} nodeObj
- * @param {string[]} childNodeNames
- * @param {string} platform
- * @param {{metadata?: Object, addIndexPath?: boolean, parentPath?: string}} opts
- * @returns {NodesAndAttributes}
- */
-export function transformChildNodes(
-  nodeObj,
-  childNodeNames,
-  platform,
-  {metadata, addIndexPath, parentPath}
-) {
-  const unknownNodes = [];
-  const unknownAttrs = [];
-  for (const nodeName of childNodeNames) {
-    // before modifying the name of this child node, recurse down and modify the subtree
-    const {nodes, attrs} = transformNode(nodeObj[nodeName], platform, {
-      metadata,
-      addIndexPath,
-      parentPath,
-    });
-    unknownNodes.push(...nodes);
-    unknownAttrs.push(...attrs);
-
-    // now translate the node name and replace the subtree with this node
-    const universalName = getUniversalNodeName(nodeName, platform);
-    if (universalName === null) {
-      unknownNodes.push(nodeName);
-      continue;
-    }
-
-    // since multiple child node names could map to the same new transformed node name, we can't
-    // simply assign nodeObj[universalName] = nodeObj[nodeName]; we need to be sensitive to the
-    // situation where the end result is an array of children having the same node name
-    if (nodeObj[universalName]) {
-      // if we already have a node with the universal name, that means we are mapping a second
-      // original node name to the same universal node name, so we just push all its children into
-      // the list
-      nodeObj[universalName].push(...nodeObj[nodeName]);
-    } else {
-      nodeObj[universalName] = nodeObj[nodeName];
-    }
-    delete nodeObj[nodeName];
-  }
-  return {nodes: unknownNodes, attrs: unknownAttrs};
-}
-
-/**
- *
- * @param {any} nodeObj
- * @param {string[]} attrs
- * @param {string} platform
- * @returns {string[]}
- */
-export function transformAttrs(nodeObj, attrs, platform) {
-  const unknownAttrs = [];
-  for (const attr of attrs) {
-    const cleanAttr = attr.substring(2);
-    if (REMOVE_ATTRS.includes(cleanAttr)) {
-      delete nodeObj[attr];
-      continue;
-    }
-    const universalAttr = getUniversalAttrName(cleanAttr, platform);
-    if (universalAttr === null) {
-      unknownAttrs.push(cleanAttr);
-      continue;
-    }
-    const newAttr = `${ATTR_PREFIX}${universalAttr}`;
-    if (newAttr !== attr) {
-      nodeObj[newAttr] = nodeObj[attr];
-      delete nodeObj[attr];
-    }
-  }
-  return unknownAttrs;
-}
-
-const singletonXmlBuilder = _.memoize(async function makeXmlBuilder() {
-  const { XMLBuilder } = await import('fast-xml-parser');
-  return new XMLBuilder({
-    ignoreAttributes: false,
-    attributeNamePrefix: ATTR_PREFIX,
-    suppressBooleanAttributes: false,
-    format: true,
-  });
-});
-
-const singletonXmlParser = _.memoize(async function makeXmlParser() {
-  const { XMLParser } = await import('fast-xml-parser');
-  return new XMLParser({
-    ignoreAttributes: false,
-    ignoreDeclaration: true,
-    attributeNamePrefix: ATTR_PREFIX,
-    isArray: (name, jPath, isLeafNode, isAttribute) => !isAttribute,
-  });
-});
-
-/**
- * @typedef {{nodes: string[], attrs: string[]}} NodesAndAttributes
- */