appium-uiautomator2-driver 6.7.3 → 6.7.5

package/lib/commands/find.js

@@ -1,4 +1,4 @@
-import CssConverter from '../css-converter';
+import {CssConverter} from '../css-converter';
 
 // we override the xpath search for this first-visible-child selector, which
 // looks like /*[@firstVisible="true"]

package/lib/css-converter.ts

@@ -0,0 +1,283 @@
+import {createParser} from 'css-selector-parser';
+import type {
+  AstAttribute,
+  AstClassName,
+  AstId,
+  AstPseudoClass,
+  AstRule,
+  AstSelector,
+  AstTagName,
+} from 'css-selector-parser';
+import _ from 'lodash';
+import {errors} from 'appium/driver';
+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]+$/;
+
+const BOOLEAN_ATTRS = [
+  'checkable',
+  'checked',
+  'clickable',
+  'enabled',
+  'focusable',
+  'focused',
+  'long-clickable',
+  'scrollable',
+  'selected',
+] as const;
+
+const NUMERIC_ATTRS = ['index', 'instance'] as const;
+
+const STR_ATTRS = ['description', RESOURCE_ID, 'text', 'class-name', 'package-name'] as const;
+
+const ALL_ATTRS = [...BOOLEAN_ATTRS, ...NUMERIC_ATTRS, ...STR_ATTRS] as readonly string[];
+
+const ATTRIBUTE_ALIASES: Array<[string, string[]]> = [
+  [RESOURCE_ID, ['id']],
+  [
+    'description',
+    ['content-description', 'content-desc', 'desc', 'accessibility-id'],
+  ],
+  ['index', ['nth-child']],
+];
+
+const isAstAttribute = (item: {type?: string}): item is AstAttribute =>
+  item.type === 'Attribute';
+const isAstPseudoClass = (item: {type?: string}): item is AstPseudoClass =>
+  item.type === 'PseudoClass';
+const isAstClassName = (item: {type?: string}): item is AstClassName =>
+  item.type === 'ClassName';
+const isAstTagName = (item: {type?: string}): item is AstTagName => item.type === 'TagName';
+const isAstId = (item: {type?: string}): item is AstId => item.type === 'Id';
+
+function toSnakeCase(str?: string | null): string {
+  if (!str) {
+    return '';
+  }
+  const tokens = str
+    .split('-')
+    .map((token) => token.charAt(0).toUpperCase() + token.slice(1).toLowerCase());
+  const out = tokens.join('');
+  return out.charAt(0).toLowerCase() + out.slice(1);
+}
+
+function requireBoolean(css: AstAttribute | AstPseudoClass): 'true' | 'false' {
+  const rawValue = (css as any).value?.value ?? (css as any).argument?.value;
+  const value = _.toLower(rawValue ?? 'true');
+  if (value === 'true') {
+    return 'true';
+  }
+  if (value === 'false') {
+    return 'false';
+  }
+  throw new Error(
+    `'${css.name}' must be true, false or empty. Found '${(css as any).value}'`,
+  );
+}
+
+function requireEntityName(cssEntity: AstAttribute | AstPseudoClass): string {
+  const attrName = cssEntity.name.toLowerCase();
+
+  if (ALL_ATTRS.includes(attrName)) {
+    return attrName;
+  }
+
+  for (const [officialAttr, aliasAttrs] of ATTRIBUTE_ALIASES) {
+    if (aliasAttrs.includes(attrName)) {
+      return officialAttr;
+    }
+  }
+  throw new Error(
+    `'${attrName}' is not a valid attribute. Supported attributes are '${ALL_ATTRS.join(', ')}'`,
+  );
+}
+
+function getWordMatcherRegex(word: string): string {
+  return `\\b(\\w*${_.escapeRegExp(word)}\\w*)\\b`;
+}
+
+export class CssConverter {
+  constructor(
+    private readonly selector: string,
+    private readonly pkg?: string | null,
+  ) {}
+
+  toUiAutomatorSelector(): string {
+    let cssObj: AstSelector;
+    try {
+      cssObj = parseCssSelector(this.selector) as AstSelector;
+    } catch (e: any) {
+      log.debug(e.stack);
+      throw new errors.InvalidSelectorError(
+        `Invalid CSS selector '${this.selector}'. Reason: '${e.message}'`,
+      );
+    }
+    try {
+      return this.parseCssObject(cssObj);
+    } catch (e: any) {
+      log.debug(e.stack);
+      throw new errors.InvalidSelectorError(
+        `Unsupported CSS selector '${this.selector}'. Reason: '${e.message}'`,
+      );
+    }
+  }
+
+  private formatIdLocator(locator: string): string {
+    return ID_LOCATOR_PATTERN.test(locator) ? locator : `${this.pkg || 'android'}:id/${locator}`;
+  }
+
+  private parseAttr(cssAttr: AstAttribute): string {
+    const attrValueNode = cssAttr.value as {value?: string} | undefined;
+    const attrValue = attrValueNode?.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 = requireEntityName(cssAttr);
+    const methodName = toSnakeCase(attrName);
+
+    if (!STR_ATTRS.includes(attrName as (typeof STR_ATTRS)[number]) && !BOOLEAN_ATTRS.includes(attrName as (typeof BOOLEAN_ATTRS)[number])) {
+      throw new Error(
+        `'${attrName}' is not supported. Supported attributes are '${[...STR_ATTRS, ...BOOLEAN_ATTRS].join(', ')}'`,
+      );
+    }
+
+    if (BOOLEAN_ATTRS.includes(attrName as (typeof BOOLEAN_ATTRS)[number])) {
+      return `.${methodName}(${requireBoolean(cssAttr)})`;
+    }
+
+    let value = attrValue || '';
+    if (attrName === RESOURCE_ID) {
+      value = this.formatIdLocator(value);
+    }
+    if (value === '') {
+      return `.${methodName}Matches("")`;
+    }
+
+    switch (cssAttr.operator) {
+      case '=':
+        return `.${methodName}("${value}")`;
+      case '*=':
+        if (['description', 'text'].includes(attrName)) {
+          return `.${methodName}Contains("${value}")`;
+        }
+        return `.${methodName}Matches("${_.escapeRegExp(value)}")`;
+      case '^=':
+        if (['description', 'text'].includes(attrName)) {
+          return `.${methodName}StartsWith("${value}")`;
+        }
+        return `.${methodName}Matches("^${_.escapeRegExp(value)}")`;
+      case '$=':
+        return `.${methodName}Matches("${_.escapeRegExp(value)}$")`;
+      case '~=':
+        return `.${methodName}Matches("${getWordMatcherRegex(value)}")`;
+      default:
+        throw new Error(
+          `Unsupported CSS attribute operator '${cssAttr.operator}'.  '=', '*=', '^=', '$=' and '~=' are supported.`,
+        );
+    }
+  }
+
+  private parsePseudo(cssPseudo: AstPseudoClass): string | undefined {
+    const argValue = (cssPseudo.argument as {value?: string} | undefined)?.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 = requireEntityName(cssPseudo);
+
+    if (BOOLEAN_ATTRS.includes(pseudoName as (typeof BOOLEAN_ATTRS)[number])) {
+      return `.${toSnakeCase(pseudoName)}(${requireBoolean(cssPseudo)})`;
+    }
+
+    if (NUMERIC_ATTRS.includes(pseudoName as (typeof NUMERIC_ATTRS)[number])) {
+      return `.${pseudoName}(${argValue})`;
+    }
+  }
+
+  private parseCssRule(cssRule: AstRule): string {
+    if (cssRule.combinator && ![' ', '>'].includes(cssRule.combinator)) {
+      throw new Error(
+        `'${cssRule.combinator}' is not a supported combinator. Only child combinator (>) and descendant combinator are supported.`,
+      );
+    }
+
+    const uiAutomatorSelector: string[] = ['new UiSelector()'];
+    const items = cssRule.items ?? [];
+
+    const astClassNames = items.filter(isAstClassName);
+    const classNames = astClassNames.map(({name}) => name);
+
+    const astTag = items.find(isAstTagName);
+    const tagName = astTag?.name;
+    if (tagName && tagName !== '*') {
+      const androidClass = [tagName];
+      if (classNames.length) {
+        for (const cssClassNames of classNames) {
+          androidClass.push(cssClassNames);
+        }
+        uiAutomatorSelector.push(`.className("${androidClass.join('.')}")`);
+      } else {
+        uiAutomatorSelector.push(`.classNameMatches("${tagName}")`);
+      }
+    } else if (classNames.length) {
+      uiAutomatorSelector.push(`.classNameMatches("${classNames.join('\\.')}")`);
+    }
+
+    const astIds = items.filter(isAstId);
+    const ids = astIds.map(({name}) => name);
+    if (ids.length) {
+      uiAutomatorSelector.push(`.resourceId("${this.formatIdLocator(ids[0])}")`);
+    }
+
+    const attributes = items.filter(isAstAttribute);
+    for (const attr of attributes) {
+      uiAutomatorSelector.push(this.parseAttr(attr));
+    }
+
+    const pseudoClasses = items.filter(isAstPseudoClass);
+    for (const pseudo of pseudoClasses) {
+      const sel = this.parsePseudo(pseudo);
+      if (sel) {
+        uiAutomatorSelector.push(sel);
+      }
+    }
+    if (cssRule.nestedRule) {
+      uiAutomatorSelector.push(`.childSelector(${this.parseCssRule(cssRule.nestedRule)})`);
+    }
+    return uiAutomatorSelector.join('');
+  }
+
+  private parseCssObject(css: AstSelector): string {
+    if (!_.isEmpty(css.rules)) {
+      return this.parseCssRule(css.rules[0] as AstRule);
+    }
+
+    throw new Error('No rules could be parsed out of the current selector');
+  }
+}

package/lib/extensions.ts

@@ -0,0 +1,3 @@
+export const APK_EXTENSION = '.apk' as const;
+export const APKS_EXTENSION = '.apks' as const;
+

package/lib/helpers.ts

@@ -0,0 +1,31 @@
+import path from 'path';
+import type {ADB} from 'appium-adb';
+import {fs, system} from 'appium/support';
+
+export async function isWriteable(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath, fs.constants.W_OK);
+    if (system.isWindows()) {
+      // On operating systems, where access-control policies may
+      // limit access to the file system, `fs.access` does not work
+      // as expected. See https://groups.google.com/forum/#!topic/nodejs/qmZtIwDRSYo
+      // for more details
+      await fs.close(await fs.open(filePath, 'r+'));
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function signApp(adb: ADB, appPath: string): Promise<void> {
+  if (!(await isWriteable(appPath))) {
+    throw new Error(
+      `The application at '${appPath}' is not writeable. ` +
+        `Please grant write permissions to this file or to its parent folder '${path.dirname(appPath)}' ` +
+        `for the Appium process, so it could sign the application`,
+    );
+  }
+  await adb.sign(appPath);
+}
+

package/lib/logger.ts

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

package/lib/uiautomator2.ts

@@ -469,7 +469,6 @@ export class UiAutomator2Server {
   }
 }
 
-export default UiAutomator2Server;
 
 export interface PackageInfo {
   installState: InstallState;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-uiautomator2-driver",
-  "version": "6.7.3",
+  "version": "6.7.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-uiautomator2-driver",
-      "version": "6.7.3",
+      "version": "6.7.5",
       "license": "Apache-2.0",
       "dependencies": {
         "appium-adb": "^14.0.0",
@@ -19,7 +19,7 @@
         "io.appium.settings": "^7.0.1",
         "lodash": "^4.17.4",
         "portscanner": "^2.2.0",
-        "teen_process": "^3.0.0"
+        "teen_process": "^4.0.4"
       },
       "devDependencies": {
         "@appium/docutils": "^2.0.0-rc.1",
@@ -626,14 +626,14 @@
       }
     },
     "node_modules/appium-adb": {
-      "version": "14.1.6",
-      "resolved": "https://registry.npmjs.org/appium-adb/-/appium-adb-14.1.6.tgz",
-      "integrity": "sha512-bNLa4iCgwNbgDANP42Gq8jhunkyLncRVubo3/dLDFHfN86i39qRlsU5jnWkI+G4ziZU/cnt8uAY1lYqZo0XpCw==",
+      "version": "14.1.7",
+      "resolved": "https://registry.npmjs.org/appium-adb/-/appium-adb-14.1.7.tgz",
+      "integrity": "sha512-/06TJ7maIJ4RzKmXdnqVNBhBZqoxAwoDeYBEaRm8Dbsa803Io16CJ94R3ncpQwlD5r5bsj4YMmwdZtVZKMjsLw==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/support": "^7.0.0-rc.1",
         "async-lock": "^1.0.0",
-        "asyncbox": "^3.0.0",
+        "asyncbox": "^4.0.1",
         "bluebird": "^3.4.7",
         "ini": "^6.0.0",
         "lodash": "^4.0.0",
@@ -646,24 +646,25 @@
         "npm": ">=10"
       }
     },
-    "node_modules/appium-adb/node_modules/asyncbox": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/asyncbox/-/asyncbox-3.0.0.tgz",
-      "integrity": "sha512-X7U0nedUMKV3nn9c4R0Zgvdvv6cw97tbDlHSZicq1snGPi/oX9DgGmFSURWtxDdnBWd3V0YviKhqAYAVvoWQ/A==",
+    "node_modules/appium-adb/node_modules/teen_process": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/teen_process/-/teen_process-3.0.6.tgz",
+      "integrity": "sha512-nUw1B4MogSZzzy67n37IM1vg4doj+bWOZ7VwIFZGfD7MDmO+FRlhQlA2+22xJnTELVDDlOaTAMpKuuMI2vkDtg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "bluebird": "^3.5.1",
-        "lodash": "^4.17.4",
-        "source-map-support": "^0.x"
+        "bluebird": "^3.7.2",
+        "lodash": "^4.17.21",
+        "shell-quote": "^1.8.1"
       },
       "engines": {
-        "node": ">=16"
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
+        "npm": ">=10"
       }
     },
     "node_modules/appium-android-driver": {
-      "version": "12.4.6",
-      "resolved": "https://registry.npmjs.org/appium-android-driver/-/appium-android-driver-12.4.6.tgz",
-      "integrity": "sha512-eqjddgR6IvO6csaJQVhSjMMhfC7O+qvzmbe0u0N/asanLRqRqADqXRGlIqzgaP5xj1HcA45xBmBArD5RFwf4GA==",
+      "version": "12.6.1",
+      "resolved": "https://registry.npmjs.org/appium-android-driver/-/appium-android-driver-12.6.1.tgz",
+      "integrity": "sha512-JFO6ouwGHYgC/knkPBVvKwtAqtaiCIPgUlVGmCngCtnLt2Zk4B0Sv+M1J8Elm1olFpCv/Jmb6kRxcEqHh1yRjg==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/support": "^7.0.0-rc.1",
@@ -691,23 +692,38 @@
         "appium": "^3.0.0-rc.2"
       }
     },
+    "node_modules/appium-android-driver/node_modules/teen_process": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/teen_process/-/teen_process-3.0.6.tgz",
+      "integrity": "sha512-nUw1B4MogSZzzy67n37IM1vg4doj+bWOZ7VwIFZGfD7MDmO+FRlhQlA2+22xJnTELVDDlOaTAMpKuuMI2vkDtg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "bluebird": "^3.7.2",
+        "lodash": "^4.17.21",
+        "shell-quote": "^1.8.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
+        "npm": ">=10"
+      }
+    },
     "node_modules/appium-chromedriver": {
-      "version": "8.0.28",
-      "resolved": "https://registry.npmjs.org/appium-chromedriver/-/appium-chromedriver-8.0.28.tgz",
-      "integrity": "sha512-EzPDYXE/kp/5EuzPI2Q3bNY32vupfYLwpUhmL6sRlbm2homBHNvU45/S+W4PpCeA2aqsuihXuTaPiolSCGd4Dg==",
+      "version": "8.0.31",
+      "resolved": "https://registry.npmjs.org/appium-chromedriver/-/appium-chromedriver-8.0.31.tgz",
+      "integrity": "sha512-hmamyXXsRwzhYoMbNzfdL1t/lCb0o0vLf63WpK/SgLwlcO2ut6MunT729KQSlFzOlLpndtE1H+LCX5KFyPDuMw==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/base-driver": "^10.0.0-rc.2",
         "@appium/support": "^7.0.0-rc.1",
         "@xmldom/xmldom": "^0.x",
         "appium-adb": "^14.0.0",
-        "asyncbox": "^3.0.0",
+        "asyncbox": "^4.0.1",
         "axios": "^1.6.5",
         "bluebird": "^3.5.1",
         "compare-versions": "^6.0.0",
         "lodash": "^4.17.4",
         "semver": "^7.0.0",
-        "teen_process": "^3.0.0",
+        "teen_process": "^4.0.4",
         "xpath": "^0.x"
       },
       "engines": {
@@ -715,20 +731,6 @@
         "npm": ">=10"
       }
     },
-    "node_modules/appium-chromedriver/node_modules/asyncbox": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/asyncbox/-/asyncbox-3.0.0.tgz",
-      "integrity": "sha512-X7U0nedUMKV3nn9c4R0Zgvdvv6cw97tbDlHSZicq1snGPi/oX9DgGmFSURWtxDdnBWd3V0YviKhqAYAVvoWQ/A==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "bluebird": "^3.5.1",
-        "lodash": "^4.17.4",
-        "source-map-support": "^0.x"
-      },
-      "engines": {
-        "node": ">=16"
-      }
-    },
     "node_modules/appium-uiautomator2-server": {
       "version": "9.9.0",
       "resolved": "https://registry.npmjs.org/appium-uiautomator2-server/-/appium-uiautomator2-server-9.9.0.tgz",
@@ -2370,37 +2372,23 @@
       }
     },
     "node_modules/io.appium.settings": {
-      "version": "7.0.6",
-      "resolved": "https://registry.npmjs.org/io.appium.settings/-/io.appium.settings-7.0.6.tgz",
-      "integrity": "sha512-OJF8IgZNZLt7ClWlMOUUhH9q5J5DFL0yDko1jIeMU/Np9wMIf06Y5RmiJosFOKc64Xe51zFB+a4LQ67VJaEuGg==",
+      "version": "7.0.8",
+      "resolved": "https://registry.npmjs.org/io.appium.settings/-/io.appium.settings-7.0.8.tgz",
+      "integrity": "sha512-KScrHILMWgEGbKvN37OHqTyROaez6yLdndK5ceF/BXS8eEnhBjrSk9xd9yZiUv+22u2ZbYcYMUJglp0aGUhXPA==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/logger": "^2.0.0-rc.1",
-        "asyncbox": "^3.0.0",
+        "asyncbox": "^4.0.1",
         "bluebird": "^3.5.1",
         "lodash": "^4.2.1",
         "semver": "^7.5.4",
-        "teen_process": "^3.0.0"
+        "teen_process": "^4.0.4"
       },
       "engines": {
         "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
         "npm": ">=10"
       }
     },
-    "node_modules/io.appium.settings/node_modules/asyncbox": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/asyncbox/-/asyncbox-3.0.0.tgz",
-      "integrity": "sha512-X7U0nedUMKV3nn9c4R0Zgvdvv6cw97tbDlHSZicq1snGPi/oX9DgGmFSURWtxDdnBWd3V0YviKhqAYAVvoWQ/A==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "bluebird": "^3.5.1",
-        "lodash": "^4.17.4",
-        "source-map-support": "^0.x"
-      },
-      "engines": {
-        "node": ">=16"
-      }
-    },
     "node_modules/ipaddr.js": {
       "version": "1.9.1",
       "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
@@ -4101,9 +4089,9 @@
       }
     },
     "node_modules/teen_process": {
-      "version": "3.0.6",
-      "resolved": "https://registry.npmjs.org/teen_process/-/teen_process-3.0.6.tgz",
-      "integrity": "sha512-nUw1B4MogSZzzy67n37IM1vg4doj+bWOZ7VwIFZGfD7MDmO+FRlhQlA2+22xJnTELVDDlOaTAMpKuuMI2vkDtg==",
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/teen_process/-/teen_process-4.0.5.tgz",
+      "integrity": "sha512-ZQQ2Vjs1/maFzpzfsZRAlQVSZrUBsKzAItaxSLImsHRTdI8hVt9Jm0JHyWFbrvvAf78V55BM3ZgNeQpXcXsWpw==",
       "license": "Apache-2.0",
       "dependencies": {
         "bluebird": "^3.7.2",

package/package.json

@@ -7,7 +7,7 @@
     "automated testing",
     "android"
   ],
-  "version": "6.7.3",
+  "version": "6.7.5",
   "bugs": {
     "url": "https://github.com/appium/appium-uiautomator2-driver/issues"
   },
@@ -66,7 +66,7 @@
     "io.appium.settings": "^7.0.1",
     "lodash": "^4.17.4",
     "portscanner": "^2.2.0",
-    "teen_process": "^3.0.0"
+    "teen_process": "^4.0.4"
   },
   "devDependencies": {
     "@appium/docutils": "^2.0.0-rc.1",