@taqwright/taqwright 0.0.24

package/dist/mobile/index.js

@@ -0,0 +1,762 @@
+import { spawn } from 'node:child_process';
+import { Locator, } from '../locator/index.js';
+import { ANDROID_NAMED_KEYS, IOS_NAMED_KEYS } from '../keys.js';
+import { Platform, } from '../types/index.js';
+export class Mobile {
+    driver;
+    platform;
+    defaultBundleId;
+    ctx;
+    constructor(driver, platform, defaultBundleId, defaultTimeout) {
+        this.driver = driver;
+        this.platform = platform;
+        this.defaultBundleId = defaultBundleId;
+        this.ctx = { driver, platform, defaultTimeout };
+    }
+    static wrap(driver, platform, bundleId, timeout) {
+        return new Mobile(driver, platform, bundleId, timeout);
+    }
+    get raw() {
+        return this.driver;
+    }
+    getPlatform() {
+        return this.platform;
+    }
+    getByText(text, opts) {
+        if (typeof text === 'string') {
+            const exact = opts?.exact ?? true;
+            if (this.platform === Platform.IOS) {
+                const escaped = escapeSingleQuotes(text);
+                const value = exact
+                    ? `label == '${escaped}' OR value == '${escaped}' OR name == '${escaped}'`
+                    : `label CONTAINS '${escaped}' OR value CONTAINS '${escaped}'`;
+                return Locator.fromStrategy(this.ctx, { using: '-ios predicate string', value });
+            }
+            const literal = xpathLiteral(text);
+            const xpath = exact ? `//*[@text=${literal}]` : `//*[contains(@text, ${literal})]`;
+            return Locator.fromStrategy(this.ctx, { using: 'xpath', value: xpath });
+        }
+        const broad = this.platform === Platform.IOS
+            ? { using: 'xpath', value: '//*[@label or @value]', textFilter: text }
+            : { using: 'xpath', value: '//*[@text]', textFilter: text };
+        return Locator.fromStrategy(this.ctx, broad);
+    }
+    getByLabel(label, _opts) {
+        return Locator.fromStrategy(this.ctx, { using: 'accessibility id', value: label });
+    }
+    getById(id) {
+        if (this.platform === Platform.IOS) {
+            return Locator.fromStrategy(this.ctx, { using: 'accessibility id', value: id });
+        }
+        return Locator.fromStrategy(this.ctx, { using: 'id', value: id });
+    }
+    getByTestId(id) {
+        return this.getById(id);
+    }
+    getByPlaceholder(text, opts) {
+        const exact = opts?.exact ?? true;
+        if (this.platform === Platform.IOS) {
+            const escaped = escapeSingleQuotes(text);
+            const value = exact
+                ? `placeholderValue == '${escaped}'`
+                : `placeholderValue CONTAINS '${escaped}'`;
+            return Locator.fromStrategy(this.ctx, { using: '-ios predicate string', value });
+        }
+        const literal = xpathLiteral(text);
+        const xpath = exact ? `//*[@hint=${literal}]` : `//*[contains(@hint, ${literal})]`;
+        return Locator.fromStrategy(this.ctx, { using: 'xpath', value: xpath });
+    }
+    getByRole(role, opts) {
+        const typeMap = {
+            button: { android: 'android.widget.Button', ios: 'XCUIElementTypeButton' },
+            link: { android: 'android.widget.TextView', ios: 'XCUIElementTypeLink' },
+            textbox: { android: 'android.widget.EditText', ios: 'XCUIElementTypeTextField' },
+            switch: { android: 'android.widget.Switch', ios: 'XCUIElementTypeSwitch' },
+            image: { android: 'android.widget.ImageView', ios: 'XCUIElementTypeImage' },
+        };
+        const cls = typeMap[role.toLowerCase()];
+        const using = 'class name';
+        const value = cls ? (this.platform === Platform.IOS ? cls.ios : cls.android) : role;
+        return Locator.fromStrategy(this.ctx, { using, value, textFilter: opts?.name });
+    }
+    getByType(type) {
+        return Locator.fromStrategy(this.ctx, { using: 'class name', value: type });
+    }
+    getByXpath(xpath) {
+        const trimmed = xpath.trim();
+        const m = trimmed.match(/^\/\/([\w.]+)?(?:\[@([\w-]+)\s*=\s*"([^"]*)"\])?$/);
+        if (m) {
+            const [, type, attr, value] = m;
+            if (attr && value !== undefined) {
+                switch (attr) {
+                    case 'hint':
+                    case 'placeholderValue':
+                        return this.getByPlaceholder(value);
+                    case 'content-desc':
+                    case 'contentDescription':
+                    case 'accessibilityLabel':
+                    case 'name':
+                    case 'label':
+                        return this.getByLabel(value);
+                    case 'text':
+                        return this.getByText(value);
+                    case 'resource-id': {
+                        const id = value.includes(':id/') ? value.split(':id/')[1] : value;
+                        return this.getById(id);
+                    }
+                }
+            }
+            if (type && !attr) {
+                return this.getByType(type);
+            }
+        }
+        return Locator.fromStrategy(this.ctx, { using: 'xpath', value: xpath });
+    }
+    getByCss(selector) {
+        return Locator.fromStrategy(this.ctx, { using: 'css selector', value: selector });
+    }
+    getByUiSelector(selector) {
+        if (this.platform !== Platform.ANDROID) {
+            throw new Error('getByUiSelector is Android-only; use getByPredicate or getByClassChain on iOS');
+        }
+        return Locator.fromStrategy(this.ctx, { using: '-android uiautomator', value: selector });
+    }
+    getByPredicate(predicate) {
+        if (this.platform !== Platform.IOS) {
+            throw new Error('getByPredicate is iOS-only; use getByUiSelector on Android');
+        }
+        return Locator.fromStrategy(this.ctx, { using: '-ios predicate string', value: predicate });
+    }
+    getByClassChain(chain) {
+        if (this.platform !== Platform.IOS) {
+            throw new Error('getByClassChain is iOS-only; use getByUiSelector on Android');
+        }
+        return Locator.fromStrategy(this.ctx, { using: '-ios class chain', value: chain });
+    }
+    async installApp(path) {
+        await this.driver.executeScript('mobile: installApp', [{ app: path }]);
+    }
+    async uninstallApp(bundleId) {
+        const id = bundleId ?? this.defaultBundleId;
+        if (!id)
+            throw new Error('uninstallApp: bundleId not provided and no default configured');
+        await this.driver.executeScript('mobile: removeApp', [{ bundleId: id, appId: id }]);
+    }
+    async launchApp(bundleId, opts) {
+        const id = bundleId ?? this.defaultBundleId;
+        if (!id)
+            throw new Error('launchApp: bundleId not provided and no default configured');
+        const arg = this.platform === Platform.IOS ? { bundleId: id } : { appId: id };
+        await this.driver.executeScript('mobile: activateApp', [arg]);
+        if (!opts?.noWaitAfter) {
+            await this.waitForAppForeground(arg);
+        }
+    }
+    async waitForAppForeground(arg) {
+        const deadline = Date.now() + 3000;
+        while (Date.now() < deadline) {
+            const state = await this.driver
+                .executeScript('mobile: queryAppState', [arg])
+                .catch(() => undefined);
+            if (typeof state === 'number' && state >= 3)
+                return;
+            await new Promise((r) => setTimeout(r, 150));
+        }
+    }
+    async terminateApp(bundleId) {
+        const id = bundleId ?? this.defaultBundleId;
+        if (!id)
+            throw new Error('terminateApp: bundleId not provided and no default configured');
+        const arg = this.platform === Platform.IOS ? { bundleId: id } : { appId: id };
+        await this.driver.executeScript('mobile: terminateApp', [arg]);
+    }
+    async activateApp(bundleId) {
+        return this.launchApp(bundleId);
+    }
+    async close() {
+        try {
+            await this.driver.deleteSession();
+        }
+        catch {
+        }
+    }
+    async click(point) {
+        try {
+            await this.driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: point.x, y: point.y },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await this.driver.releaseActions().catch(() => { });
+        }
+    }
+    async tap(point) {
+        return this.click(point);
+    }
+    async swipe(direction, opts) {
+        const rect = await this.driver.getWindowRect();
+        const cx = Math.floor(rect.width / 2);
+        const cy = Math.floor(rect.height / 2);
+        const span = Math.floor(Math.min(rect.width, rect.height) * (opts?.distance ?? 0.4));
+        const defaultFromX = direction === 'left' ? cx + span : direction === 'right' ? cx - span : cx;
+        const defaultFromY = direction === 'up' ? cy + span : direction === 'down' ? cy - span : cy;
+        const defaultToX = direction === 'left' ? cx - span : direction === 'right' ? cx + span : cx;
+        const defaultToY = direction === 'up' ? cy - span : direction === 'down' ? cy + span : cy;
+        const fromX = opts?.from?.x !== undefined ? Math.floor(rect.width * opts.from.x) : defaultFromX;
+        const fromY = opts?.from?.y !== undefined ? Math.floor(rect.height * opts.from.y) : defaultFromY;
+        const toX = opts?.to?.x !== undefined ? Math.floor(rect.width * opts.to.x) : defaultToX;
+        const toY = opts?.to?.y !== undefined ? Math.floor(rect.height * opts.to.y) : defaultToY;
+        if (this.platform === Platform.ANDROID) {
+            const yFrac = opts?.from?.y !== undefined || opts?.to?.y !== undefined
+                ? [opts?.from?.y ?? opts?.to?.y ?? 0.4, opts?.to?.y ?? opts?.from?.y ?? 0.6]
+                : [0.4, 0.6];
+            const xFrac = opts?.from?.x !== undefined || opts?.to?.x !== undefined
+                ? [opts?.from?.x ?? opts?.to?.x ?? 0.5, opts?.to?.x ?? opts?.from?.x ?? 0.5]
+                : [0.5, 0.5];
+            const yLow = Math.min(yFrac[0], yFrac[1]);
+            const yHigh = Math.max(yFrac[0], yFrac[1]);
+            const xLow = Math.min(xFrac[0], xFrac[1]);
+            const xHigh = Math.max(xFrac[0], xFrac[1]);
+            try {
+                await this.driver.executeScript('mobile: swipeGesture', [
+                    {
+                        left: Math.floor(rect.width * xLow),
+                        top: Math.floor(rect.height * yLow),
+                        width: Math.max(2, Math.floor(rect.width * (xHigh - xLow))),
+                        height: Math.max(2, Math.floor(rect.height * (yHigh - yLow))),
+                        direction,
+                        percent: opts?.distance ?? 0.75,
+                    },
+                ]);
+                return;
+            }
+            catch {
+            }
+        }
+        if (this.platform === Platform.IOS) {
+            try {
+                await this.driver.executeScript('mobile: swipe', [{ direction }]);
+                return;
+            }
+            catch {
+            }
+        }
+        try {
+            await this.driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: fromX, y: fromY },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pointerMove', duration: opts?.duration ?? 300, x: toX, y: toY },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await this.driver.releaseActions().catch(() => { });
+        }
+    }
+    async scroll(direction = 'down', opts) {
+        const fingerDir = {
+            up: 'down',
+            down: 'up',
+            left: 'right',
+            right: 'left',
+        };
+        return this.swipe(fingerDir[direction], opts);
+    }
+    async scrollIntoView(locator, opts) {
+        return locator.scrollIntoView(opts);
+    }
+    async dragAndDrop(from, to, opts) {
+        const holdMs = opts?.duration ?? 500;
+        if (this.platform === Platform.IOS) {
+            try {
+                await this.driver.executeScript('mobile: dragFromToForDuration', [
+                    {
+                        duration: holdMs / 1000,
+                        fromX: from.x,
+                        fromY: from.y,
+                        toX: to.x,
+                        toY: to.y,
+                    },
+                ]);
+                return;
+            }
+            catch {
+            }
+        }
+        else if (this.platform === Platform.ANDROID) {
+            try {
+                await this.driver.executeScript('mobile: dragGesture', [
+                    {
+                        startX: from.x,
+                        startY: from.y,
+                        endX: to.x,
+                        endY: to.y,
+                        speed: opts?.speed ?? 2500,
+                    },
+                ]);
+                return;
+            }
+            catch {
+            }
+        }
+        const moveMs = opts?.moveDuration ?? 300;
+        try {
+            await this.driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: from.x, y: from.y },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pause', duration: holdMs },
+                        { type: 'pointerMove', duration: moveMs, x: to.x, y: to.y },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await this.driver.releaseActions().catch(() => { });
+        }
+    }
+    async press(key) {
+        if (this.platform === Platform.ANDROID) {
+            const code = ANDROID_NAMED_KEYS[key];
+            if (code === undefined) {
+                const fallback = {
+                    Enter: 66,
+                    Tab: 61,
+                    Backspace: 67,
+                    Space: 62,
+                };
+                const fk = fallback[key];
+                if (fk === undefined) {
+                    throw new Error(`mobile.press: unsupported Android key "${key}"`);
+                }
+                await this.driver.executeScript('mobile: pressKey', [{ keycode: fk }]);
+                return;
+            }
+            await this.driver.executeScript('mobile: pressKey', [{ keycode: code }]);
+            return;
+        }
+        const name = IOS_NAMED_KEYS[key];
+        if (name === undefined) {
+            throw new Error(`mobile.press: unsupported iOS key "${key}"`);
+        }
+        await this.driver.executeScript('mobile: keys', [{ keys: [{ name }] }]);
+    }
+    async pressButton(button) {
+        if (this.platform === Platform.ANDROID) {
+            const keycode = ANDROID_KEYCODES[button];
+            if (keycode === undefined) {
+                throw new Error(`pressButton: unknown Android button "${button}"`);
+            }
+            await this.driver.executeScript('mobile: pressKey', [{ keycode }]);
+            return;
+        }
+        if (button === 'HOME') {
+            await this.driver.executeScript('mobile: pressButton', [{ name: 'home' }]);
+            return;
+        }
+        if (button === 'VOLUME_UP' || button === 'VOLUME_DOWN') {
+            await this.driver.executeScript('mobile: pressButton', [
+                { name: button === 'VOLUME_UP' ? 'volumeup' : 'volumedown' },
+            ]);
+            return;
+        }
+        throw new Error(`pressButton: "${button}" is not supported on iOS`);
+    }
+    async goBack() {
+        if (this.platform === Platform.ANDROID) {
+            await this.driver.back();
+            return;
+        }
+        const rect = await this.driver.getWindowRect();
+        try {
+            await this.driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x: 1, y: Math.floor(rect.height / 2) },
+                        { type: 'pointerDown', button: 0 },
+                        {
+                            type: 'pointerMove',
+                            duration: 200,
+                            x: Math.floor(rect.width / 2),
+                            y: Math.floor(rect.height / 2),
+                        },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        }
+        finally {
+            await this.driver.releaseActions().catch(() => { });
+        }
+    }
+    async screenshot() {
+        const data = await this.driver.takeScreenshot();
+        return Buffer.from(data, 'base64');
+    }
+    async getScreenSize() {
+        const rect = await this.driver.getWindowRect();
+        return { width: rect.width, height: rect.height };
+    }
+    async gesture(opts) {
+        const actions = opts.pointers.map((pointerPath, i) => {
+            const inner = [];
+            const first = pointerPath[0];
+            if (first) {
+                inner.push({ type: 'pointerMove', duration: 0, x: first.x, y: first.y });
+                inner.push({ type: 'pointerDown', button: 0 });
+                let prevTime = first.time;
+                for (let j = 1; j < pointerPath.length; j++) {
+                    const point = pointerPath[j];
+                    inner.push({
+                        type: 'pointerMove',
+                        duration: Math.max(0, point.time - prevTime),
+                        x: point.x,
+                        y: point.y,
+                    });
+                    prevTime = point.time;
+                }
+                inner.push({ type: 'pointerUp', button: 0 });
+            }
+            return {
+                type: 'pointer',
+                id: `finger${i + 1}`,
+                parameters: { pointerType: 'touch' },
+                actions: inner,
+            };
+        });
+        try {
+            await this.driver.performActions(actions);
+        }
+        finally {
+            await this.driver.releaseActions().catch(() => { });
+        }
+    }
+    async viewTree() {
+        return this.driver.getPageSource();
+    }
+    async getContexts() {
+        return (await this.driver.getAppiumContexts());
+    }
+    async getContext() {
+        return (await this.driver.getAppiumContext());
+    }
+    async switchContext(name) {
+        await this.driver.switchAppiumContext(name);
+    }
+    async switchToWebView(name) {
+        if (name) {
+            await this.driver.switchAppiumContext(name);
+            return name;
+        }
+        const ctxs = (await this.driver.getAppiumContexts());
+        const web = ctxs.find((c) => /^WEBVIEW/i.test(c));
+        if (!web) {
+            throw new Error(`No WebView context available (found: ${ctxs.join(', ') || 'none'}). ` +
+                `On Android a WebView needs chromedriver — enable ` +
+                `appium:chromedriverAutodownload or set appium:chromedriverExecutable.`);
+        }
+        await this.driver.switchAppiumContext(web);
+        return web;
+    }
+    async switchToNative() {
+        await this.driver.switchAppiumContext('NATIVE_APP');
+    }
+    async waitForTimeout(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async pause(opts) {
+        if (process.env.PWDEBUG === '0')
+            return;
+        const { startInspectorServer } = await import('../inspector/server.js');
+        const handle = await startInspectorServer({
+            defaults: { appium: { host: 'localhost', port: 4723, path: '/' }, capabilities: {} },
+            host: 'localhost',
+            port: opts?.port ?? 0,
+            attach: {
+                driver: this.driver,
+                platform: this.platform,
+                ...(this.defaultBundleId
+                    ? { capabilities: { 'appium:bundleId': this.defaultBundleId } }
+                    : {}),
+            },
+        });
+        process.stdout.write(`\n  taqwright paused. Inspector: ${handle.url}\n` +
+            `  Click "Resume" in the inspector to continue.\n\n`);
+        if (opts?.openBrowser !== false) {
+            openInBrowser(handle.url);
+        }
+        const onSigint = () => {
+            handle.close().catch(() => { });
+            process.exit(130);
+        };
+        process.once('SIGINT', onSigint);
+        try {
+            await handle.session.resumeRequested;
+        }
+        finally {
+            process.removeListener('SIGINT', onSigint);
+            await handle.close().catch(() => { });
+        }
+    }
+    async clickByPercent(box, relX = 0.5, relY = 0.5) {
+        return this.click({
+            x: Math.floor(box.x + box.width * relX),
+            y: Math.floor(box.y + box.height * relY),
+        });
+    }
+    async setOrientation(orientation) {
+        await this.driver.setOrientation(orientation.toUpperCase());
+    }
+    async getOrientation() {
+        const o = await this.driver.getOrientation();
+        return o.toLowerCase() === 'landscape' ? 'landscape' : 'portrait';
+    }
+    async hideKeyboard() {
+        if (this.platform === Platform.IOS) {
+            try {
+                await this.driver.executeScript('mobile: hideKeyboard', [{}]);
+                return;
+            }
+            catch {
+            }
+        }
+        await this.driver.hideKeyboard();
+    }
+    async isKeyboardShown() {
+        return this.driver.isKeyboardShown();
+    }
+    async acceptAlert() {
+        if (this.platform === Platform.IOS) {
+            await this.driver.executeScript('mobile: alert', [{ action: 'accept' }]);
+            return;
+        }
+        await this.driver.acceptAlert();
+    }
+    async dismissAlert() {
+        if (this.platform === Platform.IOS) {
+            await this.driver.executeScript('mobile: alert', [{ action: 'dismiss' }]);
+            return;
+        }
+        await this.driver.dismissAlert();
+    }
+    async getAlertText() {
+        return this.driver.getAlertText();
+    }
+    async backgroundApp(seconds = -1) {
+        await this.driver.executeScript('mobile: backgroundApp', [{ seconds }]);
+    }
+    async getCurrentApp() {
+        if (this.platform === Platform.IOS) {
+            const info = (await this.driver.executeScript('mobile: activeAppInfo', [{}]));
+            return { bundleId: info?.bundleId ?? '' };
+        }
+        const pkg = await this.driver.executeScript('mobile: getCurrentPackage', [{}]);
+        return { bundleId: typeof pkg === 'string' ? pkg : '' };
+    }
+    async isAppInstalled(bundleId) {
+        const id = bundleId ?? this.defaultBundleId;
+        if (!id) {
+            throw new Error('isAppInstalled: bundleId not provided and no default configured');
+        }
+        const result = await this.driver.executeScript('mobile: isAppInstalled', [this.appArg(id)]);
+        return result === true;
+    }
+    async queryAppState(bundleId) {
+        const id = bundleId ?? this.defaultBundleId;
+        if (!id) {
+            throw new Error('queryAppState: bundleId not provided and no default configured');
+        }
+        const state = await this.driver.executeScript('mobile: queryAppState', [this.appArg(id)]);
+        if (state === 0)
+            return 'not_installed';
+        if (state === 1)
+            return 'not_running';
+        if (state === 2 || state === 3)
+            return 'background';
+        if (state === 4)
+            return 'foreground';
+        return 'not_running';
+    }
+    async openDeepLink(url, bundleId) {
+        const id = bundleId ?? this.defaultBundleId;
+        if (!id) {
+            throw new Error('openDeepLink: bundleId not provided and no default configured');
+        }
+        const arg = this.platform === Platform.IOS ? { url, bundleId: id } : { url, package: id };
+        await this.driver.executeScript('mobile: deepLink', [arg]);
+    }
+    async getClipboard() {
+        const cmd = this.platform === Platform.IOS ? 'mobile: getPasteboard' : 'mobile: getClipboard';
+        const data = await this.driver.executeScript(cmd, [{}]);
+        const b64 = typeof data === 'string' ? data : '';
+        return Buffer.from(b64, 'base64').toString('utf-8');
+    }
+    async setClipboard(text) {
+        const cmd = this.platform === Platform.IOS ? 'mobile: setPasteboard' : 'mobile: setClipboard';
+        await this.driver.executeScript(cmd, [
+            { content: Buffer.from(text, 'utf-8').toString('base64') },
+        ]);
+    }
+    async setLocation(loc) {
+        await this.driver.setGeoLocation({
+            latitude: loc.latitude,
+            longitude: loc.longitude,
+            altitude: loc.altitude ?? 0,
+        });
+    }
+    async getLocation() {
+        const result = (await this.driver.getGeoLocation());
+        return {
+            latitude: Number(result.latitude),
+            longitude: Number(result.longitude),
+            altitude: Number(result.altitude),
+        };
+    }
+    async setPermission(permission, state) {
+        if (this.platform !== Platform.ANDROID) {
+            throw new Error('setPermission is Android-only; on iOS, configure permissions via the appium:processArguments / appium:autoAcceptAlerts capability or pre-grant in test setup');
+        }
+        await this.driver.executeScript('mobile: changePermissions', [
+            { action: state, permissions: [permission] },
+        ]);
+    }
+    async setNetworkConnection(opts) {
+        if (this.platform !== Platform.ANDROID) {
+            throw new Error('setNetworkConnection is Android-only; on iOS, configure via macOS Network Link Conditioner');
+        }
+        await this.driver.executeScript('mobile: setConnectivity', [
+            {
+                ...(opts.wifi !== undefined ? { wifi: opts.wifi } : {}),
+                ...(opts.data !== undefined ? { data: opts.data } : {}),
+                ...(opts.airplane !== undefined ? { airplaneMode: opts.airplane } : {}),
+            },
+        ]);
+    }
+    async getNetworkConnection() {
+        if (this.platform !== Platform.ANDROID) {
+            throw new Error('getNetworkConnection is Android-only');
+        }
+        const result = (await this.driver.executeScript('mobile: getConnectivity', [{}]));
+        return {
+            wifi: !!result?.wifi,
+            data: !!result?.data,
+            airplane: !!result?.airplaneMode,
+        };
+    }
+    async pushFile(remotePath, content) {
+        const buf = typeof content === 'string' ? Buffer.from(content, 'utf-8') : content;
+        await this.driver.executeScript('mobile: pushFile', [
+            { remotePath, payload: buf.toString('base64') },
+        ]);
+    }
+    async pullFile(remotePath) {
+        const data = await this.driver.executeScript('mobile: pullFile', [{ remotePath }]);
+        return Buffer.from(typeof data === 'string' ? data : '', 'base64');
+    }
+    async getDeviceLogs(type) {
+        const logType = type ?? (this.platform === Platform.ANDROID ? 'logcat' : 'syslog');
+        const entries = (await this.driver.getLogs(logType));
+        return entries.map((e) => ({
+            timestamp: Number(e.timestamp ?? Date.now()),
+            level: String(e.level ?? 'INFO'),
+            message: String(e.message ?? ''),
+        }));
+    }
+    async getLogTypes() {
+        return this.driver.getLogTypes();
+    }
+    async getDeviceTime(format) {
+        const arg = format ? { format } : {};
+        const t = await this.driver.executeScript('mobile: getDeviceTime', [arg]);
+        return typeof t === 'string' ? t : String(t);
+    }
+    async setLocale(locale) {
+        if (this.platform !== Platform.ANDROID) {
+            throw new Error('setLocale is Android-only at runtime; on iOS, set via the appium:language and appium:locale capabilities');
+        }
+        const [language, country] = locale.includes('-') ? locale.split('-') : [locale, undefined];
+        await this.driver.executeScript('mobile: setLocale', [
+            { language, ...(country ? { country } : {}) },
+        ]);
+    }
+    async startScreenRecording(opts) {
+        const arg = {};
+        if (opts?.videoType)
+            arg.videoType = opts.videoType;
+        if (opts?.timeLimit !== undefined)
+            arg.timeLimit = String(opts.timeLimit);
+        await this.driver.startRecordingScreen(arg);
+    }
+    async stopScreenRecording() {
+        const data = await this.driver.stopRecordingScreen();
+        return Buffer.from(typeof data === 'string' ? data : '', 'base64');
+    }
+    appArg(id) {
+        return this.platform === Platform.IOS ? { bundleId: id } : { appId: id };
+    }
+}
+function openInBrowser(url) {
+    try {
+        const cmd = process.platform === 'darwin'
+            ? { c: 'open', args: [url] }
+            : process.platform === 'win32'
+                ? { c: 'cmd', args: ['/c', 'start', '""', url] }
+                : { c: 'xdg-open', args: [url] };
+        const child = spawn(cmd.c, cmd.args, { stdio: 'ignore', detached: true });
+        child.on('error', () => {
+        });
+        child.unref();
+    }
+    catch {
+    }
+}
+const ANDROID_KEYCODES = {
+    HOME: 3,
+    BACK: 4,
+    VOLUME_UP: 24,
+    VOLUME_DOWN: 25,
+    POWER: 26,
+    ENTER: 66,
+};
+function escapeSingleQuotes(s) {
+    return s.replace(/'/g, "\\'");
+}
+function xpathLiteral(s) {
+    if (!s.includes("'"))
+        return `'${s}'`;
+    if (!s.includes('"'))
+        return `"${s}"`;
+    const parts = s.split("'");
+    const pieces = [];
+    parts.forEach((part, i) => {
+        if (i > 0)
+            pieces.push(`"'"`);
+        if (part.length > 0)
+            pieces.push(`'${part}'`);
+    });
+    return `concat(${pieces.join(', ')})`;
+}