appium-uiautomator2-driver 2.26.1 → 2.26.3

package/lib/css-converter.js

@@ -1,12 +1,28 @@
-import { CssSelectorParser } from 'css-selector-parser';
-import { escapeRegExp } from 'lodash';
+import { createParser } from 'css-selector-parser';
+import _ from 'lodash';
 import { errors } from 'appium/driver';
-
-const parser = new CssSelectorParser();
-parser.registerSelectorPseudos('has');
-parser.registerNestingOperators('>', '+', '~');
-parser.registerAttrEqualityMods('^', '$', '*', '~');
-parser.enableSubstitutes();
+import log from './logger';
+
+const parseCssSelector = createParser({
+  syntax: {
+    pseudoClasses: {
+      unknown: 'accept',
+      definitions: {
+        Selector: ['has'],
+      }
+    },
+    combinators: ['>', '+', '~'],
+    attributes: {
+      operators: ['^=', '$=', '*=', '~=', '=']
+    },
+    ids: true,
+    classNames: true,
+    tag: {
+      wildcard: true
+    },
+  },
+  substitutes: true
+});
 
 const RESOURCE_ID = 'resource-id';
 const ID_LOCATOR_PATTERN = /^[a-zA-Z_][a-zA-Z0-9._]*:id\/[\S]+$/;
@@ -42,7 +58,7 @@ const ATTRIBUTE_ALIASES = [
 /**
  * Convert hyphen separated word to snake case
  *
- * @param {string} str
+ * @param {string?} str
  * @returns {string} The hyphen separated word translated to snake case
  */
 function toSnakeCase (str) {
@@ -54,20 +70,15 @@ function toSnakeCase (str) {
   return out.charAt(0).toLowerCase() + out.slice(1);
 }
 
-/**
- * @typedef {Object} CssNameValueObject
- * @property {?name} name The name of the CSS object
- * @property {?string} value The value of the CSS object
- */
-
 /**
  * Get the boolean from a CSS object. If empty, return true. If not true/false/empty, throw exception
  *
- * @param {CssNameValueObject} css A CSS object that has 'name' and 'value'
+ * @param {import('css-selector-parser').AstAttribute|import('css-selector-parser').AstPseudoClass} css A
+ * CSS object that has 'name' and 'value'
  * @returns {string} Either 'true' or 'false'. If value is empty, return 'true'
  */
-function assertGetBool (css) {
-  const val = css.value?.toLowerCase() || 'true'; // an omitted boolean attribute means 'true' (e.g.: input[checked] means checked is true)
+function requireBoolean (css) {
+  const val = _.toLower((css.value ?? css.argument)?.value) || 'true'; // an omitted boolean attribute means 'true' (e.g.: input[checked] means checked is true)
   if (['true', 'false'].includes(val)) {
     return val;
   }
@@ -80,11 +91,11 @@ function assertGetBool (css) {
  * Converts to lowercase and if an attribute name is an alias for something else, return
  * what it is an alias for
  *
- * @param {Object} css CSS object
+ * @param {import('css-selector-parser').AstAttribute|import('css-selector-parser').AstPseudoClass} cssEntity CSS object
  * @returns {string} The canonical attribute name
  */
-function assertGetAttrName (css) {
-  const attrName = css.name.toLowerCase();
+function requireEntityName (cssEntity) {
+  const attrName = cssEntity.name.toLowerCase();
 
   // Check if it's supported and if it is, return it
   if (ALL_ATTRS.includes(attrName)) {
@@ -108,38 +119,9 @@ function assertGetAttrName (css) {
  * @returns {string} A regex "word" matcher
  */
 function getWordMatcherRegex (word) {
-  return `\\b(\\w*${escapeRegExp(word)}\\w*)\\b`;
+  return `\\b(\\w*${_.escapeRegExp(word)}\\w*)\\b`;
 }
 
-/**
- * @typedef {Object} CssAttr
- * @property {?string} valueType Type of attribute (must be string or empty)
- * @property {?string} value Value of the attribute
- * @property {?string} operator The operator between value and value type (=, *=, , ^=, $=)
- */
-
-/**
- * @typedef {Object} CssRule
- * @property {?string} nestingOperator The nesting operator (aka: combinator https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors)
- * @property {?string} tagName The tag name (aka: type selector https://developer.mozilla.org/en-US/docs/Web/CSS/Type_selectors)
- * @property {?string[]} classNames An array of CSS class names
- * @property {?CssAttr[]} attrs An array of CSS attributes
- * @property {?CssPseudo[]} attrs An array of CSS pseudos
- * @property {?string} id CSS identifier
- * @property {?CssRule} rule A descendant of this CSS rule
- */
-
-/**
- * @typedef {Object} CssObject
- * @property {?string} type Type of CSS object. 'rule', 'ruleset' or 'selectors'
- */
-
-/**
- * @typedef {Object} CssPseudo
- * @property {?string} valueType The type of CSS pseudo selector (https://www.npmjs.com/package/css-selector-parser for reference)
- * @property {?string} name The name of the pseudo selector
- * @property {?string} value The value of the pseudo selector
- */
 
 class CssConverter {
 
@@ -163,15 +145,16 @@ class CssConverter {
   /**
    * Convert a CSS attribute into a UiSelector method call
    *
-   * @param {CssAttr} cssAttr CSS attribute object
+   * @param {import('css-selector-parser').AstAttribute} cssAttr CSS attribute object
    * @returns {string} CSS attribute parsed as UiSelector
    */
   parseAttr (cssAttr) {
-    if (cssAttr.valueType && cssAttr.valueType !== 'string') {
-      throw new Error(`'${cssAttr.name}=${cssAttr.value}' is an invalid attribute. ` +
-        `Only 'string' and empty attribute types are supported. Found '${cssAttr.valueType}'`);
+    const attrValue = cssAttr.value?.value;
+    if (!_.isString(attrValue) && !_.isEmpty(attrValue)) {
+      throw new Error(`'${cssAttr.name}=${attrValue}' is an invalid attribute. ` +
+        `Only 'string' and empty attribute types are supported. Found '${attrValue}'`);
     }
-    const attrName = assertGetAttrName(cssAttr);
+    const attrName = requireEntityName(cssAttr);
     const methodName = toSnakeCase(attrName);
 
     // Validate that it's a supported attribute
@@ -182,11 +165,11 @@ class CssConverter {
 
     // Parse boolean, if it's a boolean attribute
     if (BOOLEAN_ATTRS.includes(attrName)) {
-      return `.${methodName}(${assertGetBool(cssAttr)})`;
+      return `.${methodName}(${requireBoolean(cssAttr)})`;
     }
 
     // Otherwise parse as string
-    let value = cssAttr.value || '';
+    let value = attrValue || '';
     if (attrName === RESOURCE_ID) {
       value = this.formatIdLocator(value);
     }
@@ -201,14 +184,14 @@ class CssConverter {
         if (['description', 'text'].includes(attrName)) {
           return `.${methodName}Contains("${value}")`;
         }
-        return `.${methodName}Matches("${escapeRegExp(value)}")`;
+        return `.${methodName}Matches("${_.escapeRegExp(value)}")`;
       case '^=':
         if (['description', 'text'].includes(attrName)) {
           return `.${methodName}StartsWith("${value}")`;
         }
-        return `.${methodName}Matches("^${escapeRegExp(value)}")`;
+        return `.${methodName}Matches("^${_.escapeRegExp(value)}")`;
       case '$=':
-        return `.${methodName}Matches("${escapeRegExp(value)}$")`;
+        return `.${methodName}Matches("${_.escapeRegExp(value)}$")`;
       case '~=':
         return `.${methodName}Matches("${getWordMatcherRegex(value)}")`;
       default:
@@ -221,88 +204,85 @@ class CssConverter {
   /**
    * Convert a CSS pseudo class to a UiSelector
    *
-   * @param {CssPseudo} cssPseudo CSS Pseudo class
-   * @returns {string} Pseudo selector parsed as UiSelector
+   * @param {import('css-selector-parser').AstPseudoClass} cssPseudo CSS Pseudo class
+   * @returns {string?} Pseudo selector parsed as UiSelector
    */
   parsePseudo (cssPseudo) {
-    if (cssPseudo.valueType && cssPseudo.valueType !== 'string') {
-      throw new Error(`'${cssPseudo.name}=${cssPseudo.value}'. ` +
-        `Unsupported css pseudo class value type: '${cssPseudo.valueType}'. Only 'string' type or empty is supported.`);
+    const argValue = cssPseudo.argument?.value;
+    if (!_.isString(argValue) && !_.isEmpty(argValue)) {
+      throw new Error(`'${cssPseudo.name}=${argValue}'. ` +
+        `Unsupported css pseudo class value: '${argValue}'. Only 'string' type or empty is supported.`);
     }
 
-    const pseudoName = assertGetAttrName(cssPseudo);
+    const pseudoName = requireEntityName(cssPseudo);
 
     if (BOOLEAN_ATTRS.includes(pseudoName)) {
-      return `.${toSnakeCase(pseudoName)}(${assertGetBool(cssPseudo)})`;
+      return `.${toSnakeCase(pseudoName)}(${requireBoolean(cssPseudo)})`;
     }
 
     if (NUMERIC_ATTRS.includes(pseudoName)) {
-      return `.${pseudoName}(${cssPseudo.value})`;
+      return `.${pseudoName}(${argValue})`;
     }
   }
 
   /**
    * Convert a CSS rule to a UiSelector
-   * @param {CssRule} cssRule CSS rule definition
+   * @param {import('css-selector-parser').AstRule} cssRule CSS rule definition
    */
   parseCssRule (cssRule) {
-    const { nestingOperator } = cssRule;
-    if (nestingOperator && nestingOperator !== ' ') {
-      throw new Error(`'${nestingOperator}' is not a supported combinator. ` +
+    if (cssRule.combinator && ![' ', '>'].includes(cssRule.combinator)) {
+      throw new Error(`'${cssRule.combinator}' is not a supported combinator. ` +
         `Only child combinator (>) and descendant combinator are supported.`);
     }
 
     let uiAutomatorSelector = 'new UiSelector()';
-    if (cssRule.tagName && cssRule.tagName !== '*') {
-      let androidClass = [cssRule.tagName];
+    const tagName = cssRule.tag?.name;
+    if (tagName && tagName !== '*') {
+      let androidClass = [tagName];
       if (cssRule.classNames) {
         for (const cssClassNames of cssRule.classNames) {
           androidClass.push(cssClassNames);
         }
         uiAutomatorSelector += `.className("${androidClass.join('.')}")`;
       } else {
-        uiAutomatorSelector += `.classNameMatches("${cssRule.tagName}")`;
+        uiAutomatorSelector += `.classNameMatches("${tagName}")`;
       }
-    } else if (cssRule.classNames) {
+    } else if (!_.isEmpty(cssRule.classNames)) {
       uiAutomatorSelector += `.classNameMatches("${cssRule.classNames.join('\\.')}")`;
     }
-    if (cssRule.id) {
-      uiAutomatorSelector += `.resourceId("${this.formatIdLocator(cssRule.id)}")`;
+    if (!_.isEmpty(cssRule.ids)) {
+      uiAutomatorSelector += `.resourceId("${this.formatIdLocator(cssRule.ids[0])}")`;
     }
-    if (cssRule.attrs) {
-      for (const attr of cssRule.attrs) {
+    if (cssRule.attributes) {
+      for (const attr of cssRule.attributes) {
         uiAutomatorSelector += this.parseAttr(attr);
       }
     }
-    if (cssRule.pseudos) {
-      for (const pseudo of cssRule.pseudos) {
-        uiAutomatorSelector += this.parsePseudo(pseudo);
+    if (cssRule.pseudoClasses) {
+      for (const pseudo of cssRule.pseudoClasses) {
+        const sel = this.parsePseudo(pseudo);
+        if (sel) {
+          uiAutomatorSelector += sel;
+        }
       }
     }
-    if (cssRule.rule) {
-      uiAutomatorSelector += `.childSelector(${this.parseCssRule(cssRule.rule)})`;
+    if (cssRule.nestedRule) {
+      uiAutomatorSelector += `.childSelector(${this.parseCssRule(cssRule.nestedRule)})`;
     }
     return uiAutomatorSelector;
   }
 
   /**
    * Convert CSS object to UiAutomator2 selector
-   * @param {CssObject} css CSS object
+   * @param {import('css-selector-parser').AstSelector} css CSS object
    * @returns {string} The CSS object parsed as a UiSelector
    */
   parseCssObject (css) {
-    switch (css.type) {
-      case 'rule':
-        return this.parseCssRule(css);
-      case 'ruleSet':
-        return this.parseCssObject(css.rule);
-      case 'selectors':
-        return css.selectors.map((selector) => this.parseCssObject(selector)).join('; ');
-
-      default:
-        // This is never reachable, but if it ever is do this.
-        throw new Error(`UiAutomator does not support '${css.type}' css. Only supports 'rule', 'ruleSet', 'selectors' `);
+    if (!_.isEmpty(css.rules)) {
+      return this.parseCssRule(css.rules[0]);
     }
+
+    throw new Error('No rules could be parsed out of the current selector');
   }
 
   /**
@@ -313,16 +293,18 @@ class CssConverter {
   toUiAutomatorSelector () {
     let cssObj;
     try {
-      cssObj = parser.parse(this.selector);
+      cssObj = parseCssSelector(this.selector);
     } catch (e) {
-      throw new errors.InvalidSelectorError(`Invalid CSS selector '${this.selector}'. Reason: '${e}'`);
+      log.debug(e.stack);
+      throw new errors.InvalidSelectorError(`Invalid CSS selector '${this.selector}'. Reason: '${e.message}'`);
     }
     try {
       return this.parseCssObject(cssObj);
     } catch (e) {
-      throw new errors.InvalidSelectorError(`Unsupported CSS selector '${this.selector}'. Reason: '${e}'`);
+      log.debug(e.stack);
+      throw new errors.InvalidSelectorError(`Unsupported CSS selector '${this.selector}'. Reason: '${e.message}'`);
     }
   }
 }
 
-export default CssConverter;
+export default CssConverter;