@appium/universal-xml-plugin 2.0.4 → 2.1.0

package/lib/{xpath.js → xpath.ts}

@@ -2,22 +2,23 @@ import {select as xpathQuery} from 'xpath';
 import {DOMParser, MIME_TYPE} from '@xmldom/xmldom';
 import _ from 'lodash';
 
-export function runQuery(query, xmlStr) {
+export function runQuery(query: string, xmlStr: string): any[] {
   const dom = new DOMParser().parseFromString(xmlStr, MIME_TYPE.XML_TEXT);
   // @ts-expect-error Missing Node properties are not needed.
   // https://github.com/xmldom/xmldom/issues/724
   const nodes = xpathQuery(query, dom);
-  return nodes;
+  return nodes as any[];
 }
 
 /**
+ * Transforms an XPath query to work with the original platform-specific XML
  *
- * @param {string} query
- * @param {string} xmlStr
- * @param {boolean} multiple
- * @returns {string|null}
+ * @param query - The XPath query to transform
+ * @param xmlStr - The transformed XML string
+ * @param multiple - Whether to return multiple matches
+ * @returns The transformed query string or null if no matches found
  */
-export function transformQuery(query, xmlStr, multiple) {
+export function transformQuery(query: string, xmlStr: string, multiple: boolean): string | null {
   const nodes = runQuery(query, xmlStr);
   if (!_.isArray(nodes)) {
     return null;
@@ -26,9 +27,9 @@ export function transformQuery(query, xmlStr, multiple) {
   const newQueries = nodes.map((node) => {
     const indexPath = getNodeAttrVal(node, 'indexPath');
     // at this point indexPath will look like /0/0/1/1/0/1/0/2
-    let newQuery = indexPath
+    const newQuery = indexPath
       .substring(1) // remove leading / so we can split
-      .split('/') // split into idnexes
+      .split('/') // split into indexes
       .map((indexStr) => {
         // map to xpath node indexes (1-based)
         const xpathIndex = parseInt(indexStr, 10) + 1;
@@ -40,21 +41,24 @@ export function transformQuery(query, xmlStr, multiple) {
     return `/${newQuery}`;
   });
 
-  let newSelector = null;
-  if (newQueries.length) {
-    if (multiple) {
-      newSelector = newQueries.join(' | ');
-    } else {
-      newSelector = newQueries[0];
-    }
+  if (newQueries.length === 0) {
+    return null;
   }
-  return newSelector;
+  return multiple ? newQueries.join(' | ') : newQueries[0];
 }
 
-export function getNodeAttrVal(node, attr) {
-  const attrObjs = Object.values(node.attributes).filter((obj) => obj.name === attr);
+/**
+ * Gets the value of a node attribute
+ *
+ * @param node - The XML node
+ * @param attr - The attribute name
+ * @returns The attribute value
+ * @throws {Error} If the attribute doesn't exist
+ */
+export function getNodeAttrVal(node: any, attr: string): string {
+  const attrObjs = Object.values(node.attributes || {}).filter((obj: any) => obj.name === attr);
   if (!attrObjs.length) {
     throw new Error(`Tried to retrieve a node attribute '${attr}' but the node didn't have it`);
   }
-  return attrObjs[0].value;
+  return (attrObjs[0] as any).value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/universal-xml-plugin",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "Appium plugin for making XML source and XPath queries the same across iOS and Android",
   "keywords": [
     "automation",
@@ -23,9 +23,9 @@
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
-  "types": "./build/lib/plugin.d.ts",
+  "main": "./build/lib/index.js",
+  "types": "./build/lib/index.d.ts",
   "files": [
-    "index.js",
     "build",
     "lib",
     "tsconfig.json",
@@ -34,12 +34,12 @@
   ],
   "scripts": {
     "test": "npm run test:unit",
-    "test:smoke": "node -e 'require(\"./index.js\")'",
-    "test:unit": "mocha \"./test/unit/**/*.spec.js\""
+    "test:smoke": "node ./build/lib/index.js --smoke-test",
+    "test:unit": "mocha \"./test/unit/**/*.spec.*ts\""
   },
   "dependencies": {
     "@xmldom/xmldom": "0.9.8",
-    "fast-xml-parser": "5.3.3",
+    "fast-xml-parser": "5.4.2",
     "lodash": "4.17.23",
     "xpath": "0.0.34"
   },
@@ -57,5 +57,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "f7b20335eab4022e5cbbb627ec86866a994444f8"
+  "gitHead": "980a121804ae006db879fb6860f627ac36174c15"
 }

package/tsconfig.json

@@ -1,8 +1,9 @@
 {
   "compilerOptions": {
     "outDir": "build",
-    "checkJs": true
+    "checkJs": true,
+    "types": ["mocha", "chai", "chai-as-promised"]
   },
   "extends": "@appium/tsconfig/tsconfig.plugin.json",
-  "include": ["lib"]
+  "include": ["lib", "test"]
 }

package/build/lib/logger.d.ts

@@ -1,3 +0,0 @@
-export default log;
-declare const log: import("@appium/types").AppiumLogger;
-//# sourceMappingURL=logger.d.ts.map

package/build/lib/logger.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../lib/logger.js"],"names":[],"mappings":";AACA,wDAAmD"}

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
- */