appium-uiautomator2-driver 7.5.2 → 7.6.1

package/build/lib/session-claim-handler.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionClaimHandler = exports.SessionClaimHandler = void 0;
+exports.setSharedIpcForTesting = setSharedIpcForTesting;
+exports.resetDriverInstanceIpcForTesting = resetDriverInstanceIpcForTesting;
+const support_1 = require("appium/support");
+const asyncbox_1 = require("asyncbox");
+const promises_1 = require("node:timers/promises");
+const utils_1 = require("./utils");
+class SessionClaimHandler {
+    getIpc;
+    static CLAIMED_TOPIC = 'uiautomator2:sessionUdidClaimed';
+    static CONTENDED_TOPIC = 'uiautomator2:sessionUdidContended';
+    static RELEASED_TOPIC = 'uiautomator2:sessionUdidReleased';
+    static CONTENTION_PROBE_MS = 10;
+    static RELEASE_WAIT_MS = 15000;
+    subscriptionsBySessionId = new Map();
+    constructor(getIpc) {
+        this.getIpc = getIpc;
+    }
+    /** Subscribe the current session to udid claim messages from other sessions. */
+    async registerActiveSession(driver) {
+        const ipc = await this.getIpc();
+        const udid = driver.opts.udid;
+        const sessionId = driver.sessionId;
+        if (!ipc || !udid || !sessionId) {
+            return;
+        }
+        this.unregisterActiveSession(driver);
+        const subscription = ipc.subscribe(SessionClaimHandler.CLAIMED_TOPIC, this.getPublisherId(driver));
+        subscription.on('message', (message) => {
+            void this.dispatchSessionUdidMessage(driver, udid, sessionId, message);
+        });
+        this.subscriptionsBySessionId.set(sessionId, subscription);
+    }
+    /** Unsubscribe the current session from udid claim messages. */
+    unregisterActiveSession(driver) {
+        const sessionId = driver.sessionId;
+        if (!sessionId) {
+            return;
+        }
+        this.subscriptionsBySessionId.get(sessionId)?.unsubscribe();
+        this.subscriptionsBySessionId.delete(sessionId);
+    }
+    /** Publish this session's udid so any existing session on the same device can terminate. */
+    async claimSessionUdid(driver) {
+        const ipc = await this.getIpc();
+        if (!ipc) {
+            driver.log.debug('Driver-instance IPC is unavailable. Skipping publication of the session udid.');
+            return;
+        }
+        const udid = driver.opts.udid;
+        const sessionId = driver.sessionId;
+        if (!udid || !sessionId) {
+            driver.log.debug('The session udid is not known yet. Skipping udid publication.');
+            return;
+        }
+        const contendingSessionIds = new Set();
+        const releasedSessionIds = new Set();
+        const contendedSubscription = ipc.subscribe(SessionClaimHandler.CONTENDED_TOPIC, this.getPublisherId(driver));
+        const releasedSubscription = ipc.subscribe(SessionClaimHandler.RELEASED_TOPIC, this.getPublisherId(driver));
+        contendedSubscription.on('message', (message) => {
+            if (this.isMatchingSessionUdidMessage(message, udid, sessionId)) {
+                contendingSessionIds.add(message.data.sessionId);
+            }
+        });
+        releasedSubscription.on('message', (message) => {
+            if (this.isMatchingSessionUdidMessage(message, udid, sessionId)) {
+                releasedSessionIds.add(message.data.sessionId);
+            }
+        });
+        try {
+            await ipc.publish(SessionClaimHandler.CLAIMED_TOPIC, this.getPublisherId(driver), {
+                udid,
+                sessionId,
+            });
+            await (0, promises_1.setTimeout)(SessionClaimHandler.CONTENTION_PROBE_MS);
+            if (contendingSessionIds.size === 0) {
+                return;
+            }
+            try {
+                await (0, asyncbox_1.waitForCondition)(() => [...contendingSessionIds].every((id) => releasedSessionIds.has(id)), {
+                    waitMs: SessionClaimHandler.RELEASE_WAIT_MS,
+                    intervalMs: 50,
+                });
+                driver.log.debug(`Received release confirmation from ` +
+                    `${support_1.util.pluralize('session', contendingSessionIds.size, true)} for udid '${udid}'`);
+            }
+            catch {
+                const pendingSessionIds = [...contendingSessionIds].filter((id) => !releasedSessionIds.has(id));
+                driver.log.warn(`Timed out after ${SessionClaimHandler.RELEASE_WAIT_MS}ms waiting for ` +
+                    `${support_1.util.pluralize('session', pendingSessionIds.length, true)} ` +
+                    `[${pendingSessionIds.join(', ')}] to release udid '${udid}'. ` +
+                    `Proceeding with session startup.`);
+            }
+        }
+        finally {
+            contendedSubscription.unsubscribe();
+            releasedSubscription.unsubscribe();
+        }
+    }
+    /** @internal Exposed for unit tests. */
+    resetForTesting() {
+        for (const subscription of this.subscriptionsBySessionId.values()) {
+            subscription.unsubscribe();
+        }
+        this.subscriptionsBySessionId.clear();
+    }
+    async dispatchSessionUdidMessage(driver, udid, sessionId, message) {
+        try {
+            await this.handleSessionUdidMessage(driver, udid, message);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            driver.log.warn(`Could not handle udid claim IPC message for session '${sessionId}': ${msg}`);
+        }
+    }
+    async handleSessionUdidMessage(driver, udid, message) {
+        if (!this.isMatchingSessionUdidMessage(message, udid, driver.sessionId ?? undefined)) {
+            return;
+        }
+        try {
+            await this.publishSessionUdidContended(driver, udid);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            driver.log.warn(`Could not publish udid contention message for session '${driver.sessionId}': ${msg}`);
+        }
+        driver.log.warn(`Session '${message.data.sessionId}' is starting on udid '${udid}', which is already in use ` +
+            `by another session identified by ${driver.sessionId}. Running multiple parallel sessions on the same ` +
+            `device is highly discouraged. Consider enabling the Appium server's '--session-override' flag ` +
+            `and make sure to properly quit the previous session before starting a new one. ` +
+            `Terminating the obsolete session.`);
+        await this.terminateSessionOnRequest(driver, udid);
+    }
+    async publishSessionUdidContended(driver, udid) {
+        const ipc = await this.getIpc();
+        const sessionId = driver.sessionId ?? undefined;
+        if (!ipc || !udid || !sessionId) {
+            return;
+        }
+        await ipc.publish(SessionClaimHandler.CONTENDED_TOPIC, this.getPublisherId(driver), {
+            udid,
+            sessionId,
+        });
+    }
+    async terminateSessionOnRequest(driver, udid) {
+        const sessionId = driver.sessionId ?? undefined;
+        const publisherId = sessionId ? this.getPublisherId(driver) : undefined;
+        const { log } = driver;
+        try {
+            await driver.deleteSession();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.warn(`Could not terminate session '${sessionId}' on IPC request: ${msg}`);
+        }
+        await this.publishSessionUdidReleased(log, udid, sessionId, publisherId);
+    }
+    async publishSessionUdidReleased(log, udid, sessionId, publisherId) {
+        try {
+            const ipc = await this.getIpc();
+            if (!ipc || !udid || !sessionId || !publisherId) {
+                return;
+            }
+            await ipc.publish(SessionClaimHandler.RELEASED_TOPIC, publisherId, {
+                udid,
+                sessionId,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.warn(`Could not publish udid release message for session '${sessionId}': ${msg}`);
+        }
+    }
+    getPublisherId(driver) {
+        return support_1.node.getObjectId(driver);
+    }
+    isMatchingSessionUdidMessage(message, udid, sessionId) {
+        return message.data.udid === udid && message.data.sessionId !== sessionId;
+    }
+}
+exports.SessionClaimHandler = SessionClaimHandler;
+const loadSharedIpc = (0, utils_1.memoize)(async function loadSharedIpc() {
+    try {
+        const { AppiumIpc } = (await import('appium/driver.js'));
+        return AppiumIpc ? new AppiumIpc() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+});
+exports.sessionClaimHandler = new SessionClaimHandler(loadSharedIpc);
+/**
+ * @internal Exposed for unit tests.
+ */
+function setSharedIpcForTesting(ipc) {
+    loadSharedIpc.cache.set(undefined, Promise.resolve(ipc));
+}
+/**
+ * @internal Exposed for unit tests.
+ */
+function resetDriverInstanceIpcForTesting() {
+    exports.sessionClaimHandler.resetForTesting();
+    loadSharedIpc.cache.clear();
+}
+//# sourceMappingURL=session-claim-handler.js.map

package/build/lib/session-claim-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-claim-handler.js","sourceRoot":"","sources":["../../lib/session-claim-handler.ts"],"names":[],"mappings":"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"}

package/lib/commands/find.ts

@@ -1,4 +1,4 @@
-import {CssConverter} from '../css-converter';
+import {cssToNativeLocator} from '../css';
 import type {Element as AppiumElement} from '@appium/types';
 import type {FindElementOpts} from 'appium-android-driver';
 import type {AndroidUiautomator2Driver} from '../driver';
@@ -42,11 +42,10 @@ export async function doFindElementOrEls(
     params.selector = MAGIC_SCROLLABLE_BY;
   }
   if (params.strategy === 'css selector') {
-    params.strategy = '-android uiautomator';
-    params.selector = new CssConverter(
+    ({strategy: params.strategy, selector: params.selector} = await cssToNativeLocator(
       params.selector,
       this.opts.appPackage,
-    ).toUiAutomatorSelector();
+    ));
   }
   return (await uiautomator2.jwproxy.command(
     `/element${params.multiple ? 's' : ''}`,

package/lib/css/constants.ts

@@ -0,0 +1,5 @@
+/** Locator strategy name used for UiAutomator queries. */
+export const UI_AUTOMATOR_STRATEGY = '-android uiautomator';
+
+/** Registry key for the UiAutomator CSS emitter. */
+export const UI_AUTOMATOR_EMITTER_KEY = 'uiautomator';

package/lib/css/index.ts

@@ -0,0 +1,59 @@
+import {errors} from 'appium/driver';
+import {memoize} from '../utils';
+import {UI_AUTOMATOR_EMITTER_KEY, UI_AUTOMATOR_STRATEGY} from './constants';
+import {ATTRIBUTE_SCHEMA} from './schema';
+import {UiAutomatorEmitter} from './ui-automator-emitter';
+import type {CssTransformer, NativeLocator, StrategyKey} from '@appium/css-locator-to-native';
+
+export {UI_AUTOMATOR_STRATEGY} from './constants';
+
+const emitters = {
+  [UI_AUTOMATOR_EMITTER_KEY]: new UiAutomatorEmitter(UI_AUTOMATOR_STRATEGY),
+};
+
+const getTransformCss = memoize(async function loadTransformCss(): Promise<CssTransformer> {
+  const mod = await import('@appium/css-locator-to-native');
+  return mod.createCssTransformer({
+    schema: ATTRIBUTE_SCHEMA,
+    emitters,
+    resolveStrategy(): StrategyKey<typeof emitters> {
+      return UI_AUTOMATOR_EMITTER_KEY;
+    },
+  });
+});
+
+/**
+ * Converts a CSS selector string into a native locator for the resolved strategy.
+ *
+ * @param css - CSS selector to transform
+ * @param appPackage - Optional application package used to qualify resource ids
+ * @returns Native locator strategy name and selector string
+ */
+export async function cssToNativeLocator(
+  css: string,
+  appPackage?: string | null,
+): Promise<NativeLocator> {
+  try {
+    const transformCss = await getTransformCss();
+    return transformCss(css, {appPackage});
+  } catch (err) {
+    throw mapCssError(err, css);
+  }
+}
+
+function mapCssError(err: unknown, css: string): Error {
+  if (isPackageError(err, 'InvalidSelectorError')) {
+    return new errors.InvalidSelectorError(`Invalid CSS selector '${css}'`, err);
+  }
+  if (isPackageError(err, 'UnsupportedSelectorError')) {
+    return new errors.InvalidSelectorError(`Unsupported CSS selector '${css}'`, err);
+  }
+  if (err instanceof Error) {
+    return err;
+  }
+  return new Error(String(err));
+}
+
+function isPackageError(err: unknown, name: string): err is Error {
+  return err instanceof Error && err.name === name;
+}

package/lib/css/schema.ts

@@ -0,0 +1,26 @@
+import type {AttributeSchema} from '@appium/css-locator-to-native';
+
+export const ATTRIBUTE_SCHEMA: AttributeSchema = {
+  attributes: {
+    checkable: {type: 'boolean'},
+    checked: {type: 'boolean'},
+    clickable: {type: 'boolean'},
+    enabled: {type: 'boolean'},
+    focusable: {type: 'boolean'},
+    focused: {type: 'boolean'},
+    'long-clickable': {type: 'boolean'},
+    scrollable: {type: 'boolean'},
+    selected: {type: 'boolean'},
+    index: {type: 'numeric', aliases: ['nth-child']},
+    instance: {type: 'numeric'},
+    description: {
+      type: 'string',
+      aliases: ['content-description', 'content-desc', 'desc', 'accessibility-id'],
+    },
+    'resource-id': {type: 'string', aliases: ['id']},
+    text: {type: 'string'},
+    'class-name': {type: 'string'},
+    'package-name': {type: 'string'},
+  },
+  booleanFormat: 'true-false',
+};

package/lib/css/ui-automator-emitter.ts

@@ -0,0 +1,148 @@
+import {escapeRegExp} from '../utils';
+import type {
+  ParsedAttribute,
+  ParsedRule,
+  ParsedSelector,
+  StrategyEmitter,
+} from '@appium/css-locator-to-native';
+
+const BOOLEAN_ATTRS = new Set([
+  'checkable',
+  'checked',
+  'clickable',
+  'enabled',
+  'focusable',
+  'focused',
+  'long-clickable',
+  'scrollable',
+  'selected',
+]);
+
+const NUMERIC_ATTRS = new Set(['index', 'instance']);
+
+const STRING_ATTRS = new Set(['description', 'resource-id', 'text', 'class-name', 'package-name']);
+
+const ID_LOCATOR_PATTERN = /^[a-zA-Z_][a-zA-Z0-9._]*:id\/[\S]+$/;
+
+export interface UiAutomatorEmitterContext {
+  appPackage?: string | null;
+}
+
+/** Converts parsed CSS selectors into UiAutomator selector strings. */
+export class UiAutomatorEmitter implements StrategyEmitter<UiAutomatorEmitterContext> {
+  readonly strategy: string;
+
+  constructor(strategy: string) {
+    this.strategy = strategy;
+  }
+
+  emit(parsed: ParsedSelector, ctx?: UiAutomatorEmitterContext): string {
+    return this.emitRule(parsed.rule, ctx);
+  }
+
+  private emitRule(rule: ParsedRule, ctx?: UiAutomatorEmitterContext): string {
+    const parts: string[] = ['new UiSelector()'];
+
+    const tagName = rule.tag;
+    const classNames = [...rule.classes];
+
+    if (tagName && tagName !== '*') {
+      if (classNames.length) {
+        parts.push(`.className("${[tagName, ...classNames].join('.')}")`);
+      } else {
+        parts.push(`.classNameMatches("${tagName}")`);
+      }
+    } else if (classNames.length) {
+      parts.push(`.classNameMatches("${classNames.join('\\.')}")`);
+    }
+
+    if (rule.id) {
+      parts.push(`.resourceId("${this.formatIdLocator(rule.id, ctx?.appPackage)}")`);
+    }
+
+    for (const attr of rule.attributes) {
+      parts.push(this.formatEntity(attr, ctx));
+    }
+
+    for (const pseudo of rule.pseudos) {
+      const formatted = this.formatEntity(pseudo, ctx);
+      if (formatted) {
+        parts.push(formatted);
+      }
+    }
+
+    if (rule.nested) {
+      parts.push(`.childSelector(${this.emitRule(rule.nested, ctx)})`);
+    }
+
+    return parts.join('');
+  }
+
+  private formatEntity(attr: ParsedAttribute, ctx?: UiAutomatorEmitterContext): string {
+    if (BOOLEAN_ATTRS.has(attr.name)) {
+      return this.formatBoolean(attr);
+    }
+    if (NUMERIC_ATTRS.has(attr.name)) {
+      return `.${attr.name}(${attr.value})`;
+    }
+    if (STRING_ATTRS.has(attr.name)) {
+      return this.formatStringAttr(attr, ctx);
+    }
+    return '';
+  }
+
+  private formatBoolean(attr: ParsedAttribute): string {
+    const value = attr.value ?? 'true';
+    return `.${toSnakeCase(attr.name)}(${value})`;
+  }
+
+  private formatStringAttr(attr: ParsedAttribute, ctx?: UiAutomatorEmitterContext): string {
+    const methodName = toSnakeCase(attr.name);
+    let value = attr.value ?? '';
+
+    if (attr.name === 'resource-id') {
+      value = this.formatIdLocator(value, ctx?.appPackage);
+    }
+
+    if (value === '') {
+      return `.${methodName}Matches("")`;
+    }
+
+    switch (attr.operator) {
+      case '=':
+        return `.${methodName}("${value}")`;
+      case '*=':
+        if (['description', 'text'].includes(attr.name)) {
+          return `.${methodName}Contains("${value}")`;
+        }
+        return `.${methodName}Matches("${escapeRegExp(value)}")`;
+      case '^=':
+        if (['description', 'text'].includes(attr.name)) {
+          return `.${methodName}StartsWith("${value}")`;
+        }
+        return `.${methodName}Matches("^${escapeRegExp(value)}")`;
+      case '$=':
+        return `.${methodName}Matches("${escapeRegExp(value)}$")`;
+      case '~=':
+        return `.${methodName}Matches("${getWordMatcherRegex(value)}")`;
+      default:
+        return `.${methodName}("${value}")`;
+    }
+  }
+
+  private formatIdLocator(locator: string, appPackage?: string | null): string {
+    return ID_LOCATOR_PATTERN.test(locator) ? locator : `${appPackage || 'android'}:id/${locator}`;
+  }
+}
+
+function toSnakeCase(str: string): string {
+  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 getWordMatcherRegex(word: string): string {
+  return `\\b(\\w*${escapeRegExp(word)}\\w*)\\b`;
+}

package/lib/driver.ts

@@ -121,6 +121,7 @@ import {
   mobileViewPortRect,
 } from './commands/viewport';
 import {executeMethodMap} from './execute-method-map';
+import {sessionClaimHandler} from './session-claim-handler';
 
 // NO_PROXY contains the paths that we never want to proxy to UiAutomator2 server.
 // TODO:  Add the list of paths that we never want to proxy to UiAutomator2 server.
@@ -426,6 +427,10 @@ class AndroidUiautomator2Driver
       this.opts.udid = udid;
       // @ts-expect-error do not put random stuff on opts
       this.opts.emPort = emPort;
+
+      await sessionClaimHandler.registerActiveSession(this);
+      await sessionClaimHandler.claimSessionUdid(this);
+
       // now that we know our java version and device info, we can create our
       // ADB instance
       this.adb = await this.createADB();
@@ -499,7 +504,13 @@ class AndroidUiautomator2Driver
     return {...sessionData, ...uia2Data};
   }
 
+  async onIpcInit(): Promise<void> {
+    await sessionClaimHandler.registerActiveSession(this);
+  }
+
   override async deleteSession() {
+    sessionClaimHandler.unregisterActiveSession(this);
+
     this.log.debug('Deleting UiAutomator2 session');
 
     const screenRecordingStopTasks = [

package/lib/logger.ts

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