appium-uiautomator2-driver 7.6.0 → 7.6.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [7.6.2](https://github.com/appium/appium-uiautomator2-driver/compare/v7.6.1...v7.6.2) (2026-06-19)
+
+### Miscellaneous Chores
+
+* **deps-dev:** bump @types/node from 25.9.4 to 26.0.0 ([#1011](https://github.com/appium/appium-uiautomator2-driver/issues/1011)) ([6783d39](https://github.com/appium/appium-uiautomator2-driver/commit/6783d39dafe7d79ab0b4d5ad43f11004f9e745bb))
+
+## [7.6.1](https://github.com/appium/appium-uiautomator2-driver/compare/v7.6.0...v7.6.1) (2026-06-09)
+
+### Miscellaneous Chores
+
+* Refactor css locator transformer ([#1009](https://github.com/appium/appium-uiautomator2-driver/issues/1009)) ([cba226a](https://github.com/appium/appium-uiautomator2-driver/commit/cba226a075cac199e7df3183f34e7266e1b51e19))
+
 ## [7.6.0](https://github.com/appium/appium-uiautomator2-driver/compare/v7.5.2...v7.6.0) (2026-06-04)
 
 ### Features

package/build/lib/commands/find.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.doFindElementOrEls = doFindElementOrEls;
-const css_converter_1 = require("../css-converter");
+const css_1 = require("../css");
 // we override the xpath search for this first-visible-child selector, which
 // looks like /*[@firstVisible="true"]
 const MAGIC_FIRST_VIS_CHILD_SEL = /\/\*\[@firstVisible ?= ?('|")true\1\]/;
@@ -18,8 +18,7 @@ async function doFindElementOrEls(params) {
         params.selector = MAGIC_SCROLLABLE_BY;
     }
     if (params.strategy === 'css selector') {
-        params.strategy = '-android uiautomator';
-        params.selector = new css_converter_1.CssConverter(params.selector, this.opts.appPackage).toUiAutomatorSelector();
+        ({ strategy: params.strategy, selector: params.selector } = await (0, css_1.cssToNativeLocator)(params.selector, this.opts.appPackage));
     }
     return (await uiautomator2.jwproxy.command(`/element${params.multiple ? 's' : ''}`, 'POST', params));
 }

package/build/lib/commands/find.js.map

@@ -1 +1 @@
-{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../lib/commands/find.ts"],"names":[],"mappings":";;AA0BA,gDA6BC;AAvDD,oDAA8C;AAK9C,4EAA4E;AAC5E,sCAAsC;AACtC,MAAM,yBAAyB,GAAG,uCAAuC,CAAC;AAE1E,MAAM,oBAAoB,GAAG,uCAAuC,CAAC;AACrE,MAAM,mBAAmB,GAAG,mCAAmC,CAAC;AAgBzD,KAAK,UAAU,kBAAkB,CAEtC,MAAuB;IAEvB,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACvC,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnF,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC;QACjC,OAAO,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,OAAO,CACxC,mBAAmB,SAAS,gBAAgB,EAC5C,KAAK,EACL,EAAE,CACH,CAAkB,CAAC;IACtB,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9E,MAAM,CAAC,QAAQ,GAAG,sBAAsB,CAAC;QACzC,MAAM,CAAC,QAAQ,GAAG,mBAAmB,CAAC;IACxC,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;QACvC,MAAM,CAAC,QAAQ,GAAG,sBAAsB,CAAC;QACzC,MAAM,CAAC,QAAQ,GAAG,IAAI,4BAAY,CAChC,MAAM,CAAC,QAAQ,EACf,IAAI,CAAC,IAAI,CAAC,UAAU,CACrB,CAAC,qBAAqB,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,OAAO,CACxC,WAAW,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EACvC,MAAM,EACN,MAAM,CACP,CAAoC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../lib/commands/find.ts"],"names":[],"mappings":";;AA0BA,gDA4BC;AAtDD,gCAA0C;AAK1C,4EAA4E;AAC5E,sCAAsC;AACtC,MAAM,yBAAyB,GAAG,uCAAuC,CAAC;AAE1E,MAAM,oBAAoB,GAAG,uCAAuC,CAAC;AACrE,MAAM,mBAAmB,GAAG,mCAAmC,CAAC;AAgBzD,KAAK,UAAU,kBAAkB,CAEtC,MAAuB;IAEvB,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACvC,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnF,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC;QACjC,OAAO,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,OAAO,CACxC,mBAAmB,SAAS,gBAAgB,EAC5C,KAAK,EACL,EAAE,CACH,CAAkB,CAAC;IACtB,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9E,MAAM,CAAC,QAAQ,GAAG,sBAAsB,CAAC;QACzC,MAAM,CAAC,QAAQ,GAAG,mBAAmB,CAAC;IACxC,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;QACvC,CAAC,EAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAC,GAAG,MAAM,IAAA,wBAAkB,EAChF,MAAM,CAAC,QAAQ,EACf,IAAI,CAAC,IAAI,CAAC,UAAU,CACrB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,OAAO,CACxC,WAAW,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EACvC,MAAM,EACN,MAAM,CACP,CAAoC,CAAC;AACxC,CAAC"}

package/build/lib/css/constants.d.ts

@@ -0,0 +1,5 @@
+/** Locator strategy name used for UiAutomator queries. */
+export declare const UI_AUTOMATOR_STRATEGY = "-android uiautomator";
+/** Registry key for the UiAutomator CSS emitter. */
+export declare const UI_AUTOMATOR_EMITTER_KEY = "uiautomator";
+//# sourceMappingURL=constants.d.ts.map

package/build/lib/css/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../lib/css/constants.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,yBAAyB,CAAC;AAE5D,oDAAoD;AACpD,eAAO,MAAM,wBAAwB,gBAAgB,CAAC"}

package/build/lib/css/constants.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI_AUTOMATOR_EMITTER_KEY = exports.UI_AUTOMATOR_STRATEGY = void 0;
+/** Locator strategy name used for UiAutomator queries. */
+exports.UI_AUTOMATOR_STRATEGY = '-android uiautomator';
+/** Registry key for the UiAutomator CSS emitter. */
+exports.UI_AUTOMATOR_EMITTER_KEY = 'uiautomator';
+//# sourceMappingURL=constants.js.map

package/build/lib/css/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../lib/css/constants.ts"],"names":[],"mappings":";;;AAAA,0DAA0D;AAC7C,QAAA,qBAAqB,GAAG,sBAAsB,CAAC;AAE5D,oDAAoD;AACvC,QAAA,wBAAwB,GAAG,aAAa,CAAC"}

package/build/lib/css/index.d.ts

@@ -0,0 +1,11 @@
+import type { NativeLocator } from '@appium/css-locator-to-native';
+export { UI_AUTOMATOR_STRATEGY } from './constants';
+/**
+ * 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 declare function cssToNativeLocator(css: string, appPackage?: string | null): Promise<NativeLocator>;
+//# sourceMappingURL=index.d.ts.map

package/build/lib/css/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/css/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiB,aAAa,EAAc,MAAM,+BAA+B,CAAC;AAE9F,OAAO,EAAC,qBAAqB,EAAC,MAAM,aAAa,CAAC;AAiBlD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,OAAO,CAAC,aAAa,CAAC,CAOxB"}

package/build/lib/css/index.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI_AUTOMATOR_STRATEGY = void 0;
+exports.cssToNativeLocator = cssToNativeLocator;
+const driver_1 = require("appium/driver");
+const utils_1 = require("../utils");
+const constants_1 = require("./constants");
+const schema_1 = require("./schema");
+const ui_automator_emitter_1 = require("./ui-automator-emitter");
+var constants_2 = require("./constants");
+Object.defineProperty(exports, "UI_AUTOMATOR_STRATEGY", { enumerable: true, get: function () { return constants_2.UI_AUTOMATOR_STRATEGY; } });
+const emitters = {
+    [constants_1.UI_AUTOMATOR_EMITTER_KEY]: new ui_automator_emitter_1.UiAutomatorEmitter(constants_1.UI_AUTOMATOR_STRATEGY),
+};
+const getTransformCss = (0, utils_1.memoize)(async function loadTransformCss() {
+    const mod = await import('@appium/css-locator-to-native');
+    return mod.createCssTransformer({
+        schema: schema_1.ATTRIBUTE_SCHEMA,
+        emitters,
+        resolveStrategy() {
+            return constants_1.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
+ */
+async function cssToNativeLocator(css, appPackage) {
+    try {
+        const transformCss = await getTransformCss();
+        return transformCss(css, { appPackage });
+    }
+    catch (err) {
+        throw mapCssError(err, css);
+    }
+}
+function mapCssError(err, css) {
+    if (isPackageError(err, 'InvalidSelectorError')) {
+        return new driver_1.errors.InvalidSelectorError(`Invalid CSS selector '${css}'`, err);
+    }
+    if (isPackageError(err, 'UnsupportedSelectorError')) {
+        return new driver_1.errors.InvalidSelectorError(`Unsupported CSS selector '${css}'`, err);
+    }
+    if (err instanceof Error) {
+        return err;
+    }
+    return new Error(String(err));
+}
+function isPackageError(err, name) {
+    return err instanceof Error && err.name === name;
+}
+//# sourceMappingURL=index.js.map

package/build/lib/css/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/css/index.ts"],"names":[],"mappings":";;;AA+BA,gDAUC;AAzCD,0CAAqC;AACrC,oCAAiC;AACjC,2CAA4E;AAC5E,qCAA0C;AAC1C,iEAA0D;AAG1D,yCAAkD;AAA1C,kHAAA,qBAAqB,OAAA;AAE7B,MAAM,QAAQ,GAAG;IACf,CAAC,oCAAwB,CAAC,EAAE,IAAI,yCAAkB,CAAC,iCAAqB,CAAC;CAC1E,CAAC;AAEF,MAAM,eAAe,GAAG,IAAA,eAAO,EAAC,KAAK,UAAU,gBAAgB;IAC7D,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;IAC1D,OAAO,GAAG,CAAC,oBAAoB,CAAC;QAC9B,MAAM,EAAE,yBAAgB;QACxB,QAAQ;QACR,eAAe;YACb,OAAO,oCAAwB,CAAC;QAClC,CAAC;KACF,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH;;;;;;GAMG;AACI,KAAK,UAAU,kBAAkB,CACtC,GAAW,EACX,UAA0B;IAE1B,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,MAAM,eAAe,EAAE,CAAC;QAC7C,OAAO,YAAY,CAAC,GAAG,EAAE,EAAC,UAAU,EAAC,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,GAAY,EAAE,GAAW;IAC5C,IAAI,cAAc,CAAC,GAAG,EAAE,sBAAsB,CAAC,EAAE,CAAC;QAChD,OAAO,IAAI,eAAM,CAAC,oBAAoB,CAAC,yBAAyB,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,cAAc,CAAC,GAAG,EAAE,0BAA0B,CAAC,EAAE,CAAC;QACpD,OAAO,IAAI,eAAM,CAAC,oBAAoB,CAAC,6BAA6B,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,cAAc,CAAC,GAAY,EAAE,IAAY;IAChD,OAAO,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC;AACnD,CAAC"}

package/build/lib/css/schema.d.ts

@@ -0,0 +1,3 @@
+import type { AttributeSchema } from '@appium/css-locator-to-native';
+export declare const ATTRIBUTE_SCHEMA: AttributeSchema;
+//# sourceMappingURL=schema.d.ts.map

package/build/lib/css/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../lib/css/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAEnE,eAAO,MAAM,gBAAgB,EAAE,eAuB9B,CAAC"}

package/build/lib/css/schema.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTRIBUTE_SCHEMA = void 0;
+exports.ATTRIBUTE_SCHEMA = {
+    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',
+};
+//# sourceMappingURL=schema.js.map

package/build/lib/css/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../lib/css/schema.ts"],"names":[],"mappings":";;;AAEa,QAAA,gBAAgB,GAAoB;IAC/C,UAAU,EAAE;QACV,SAAS,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC5B,OAAO,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC1B,SAAS,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC5B,OAAO,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC1B,SAAS,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC5B,OAAO,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC1B,gBAAgB,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QACnC,UAAU,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC7B,QAAQ,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC3B,KAAK,EAAE,EAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,WAAW,CAAC,EAAC;QAChD,QAAQ,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;QAC3B,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,CAAC,qBAAqB,EAAE,cAAc,EAAE,MAAM,EAAE,kBAAkB,CAAC;SAC7E;QACD,aAAa,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,EAAC;QAChD,IAAI,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC;QACtB,YAAY,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC;QAC9B,cAAc,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC;KACjC;IACD,aAAa,EAAE,YAAY;CAC5B,CAAC"}

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

@@ -0,0 +1,16 @@
+import type { ParsedSelector, StrategyEmitter } from '@appium/css-locator-to-native';
+export interface UiAutomatorEmitterContext {
+    appPackage?: string | null;
+}
+/** Converts parsed CSS selectors into UiAutomator selector strings. */
+export declare class UiAutomatorEmitter implements StrategyEmitter<UiAutomatorEmitterContext> {
+    readonly strategy: string;
+    constructor(strategy: string);
+    emit(parsed: ParsedSelector, ctx?: UiAutomatorEmitterContext): string;
+    private emitRule;
+    private formatEntity;
+    private formatBoolean;
+    private formatStringAttr;
+    private formatIdLocator;
+}
+//# sourceMappingURL=ui-automator-emitter.d.ts.map

package/build/lib/css/ui-automator-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-automator-emitter.d.ts","sourceRoot":"","sources":["../../../lib/css/ui-automator-emitter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,cAAc,EACd,eAAe,EAChB,MAAM,+BAA+B,CAAC;AAoBvC,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,uEAAuE;AACvE,qBAAa,kBAAmB,YAAW,eAAe,CAAC,yBAAyB,CAAC;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;IAI5B,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,yBAAyB,GAAG,MAAM;IAIrE,OAAO,CAAC,QAAQ;IAsChB,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,gBAAgB;IAkCxB,OAAO,CAAC,eAAe;CAGxB"}

package/build/lib/css/ui-automator-emitter.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UiAutomatorEmitter = void 0;
+const utils_1 = require("../utils");
+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]+$/;
+/** Converts parsed CSS selectors into UiAutomator selector strings. */
+class UiAutomatorEmitter {
+    strategy;
+    constructor(strategy) {
+        this.strategy = strategy;
+    }
+    emit(parsed, ctx) {
+        return this.emitRule(parsed.rule, ctx);
+    }
+    emitRule(rule, ctx) {
+        const parts = ['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('');
+    }
+    formatEntity(attr, ctx) {
+        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 '';
+    }
+    formatBoolean(attr) {
+        const value = attr.value ?? 'true';
+        return `.${toSnakeCase(attr.name)}(${value})`;
+    }
+    formatStringAttr(attr, ctx) {
+        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("${(0, utils_1.escapeRegExp)(value)}")`;
+            case '^=':
+                if (['description', 'text'].includes(attr.name)) {
+                    return `.${methodName}StartsWith("${value}")`;
+                }
+                return `.${methodName}Matches("^${(0, utils_1.escapeRegExp)(value)}")`;
+            case '$=':
+                return `.${methodName}Matches("${(0, utils_1.escapeRegExp)(value)}$")`;
+            case '~=':
+                return `.${methodName}Matches("${getWordMatcherRegex(value)}")`;
+            default:
+                return `.${methodName}("${value}")`;
+        }
+    }
+    formatIdLocator(locator, appPackage) {
+        return ID_LOCATOR_PATTERN.test(locator) ? locator : `${appPackage || 'android'}:id/${locator}`;
+    }
+}
+exports.UiAutomatorEmitter = UiAutomatorEmitter;
+function toSnakeCase(str) {
+    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) {
+    return `\\b(\\w*${(0, utils_1.escapeRegExp)(word)}\\w*)\\b`;
+}
+//# sourceMappingURL=ui-automator-emitter.js.map

package/build/lib/css/ui-automator-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-automator-emitter.js","sourceRoot":"","sources":["../../../lib/css/ui-automator-emitter.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`;
+}