@taqwright/taqwright 0.0.24

package/dist/inspector/devices.js

@@ -0,0 +1,422 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { androidEnvForAvd, resolveAvdSdk } from '../setup/avd.js';
+const execFileP = promisify(execFile);
+const exe = (name) => (process.platform === 'win32' ? `${name}.exe` : name);
+export async function listDevices() {
+    const [androidAll, ios, toolsMissing] = await Promise.all([
+        listAndroid().catch(() => []),
+        process.platform === 'darwin' ? listIos().catch(() => []) : Promise.resolve([]),
+        detectMissingTools(),
+    ]);
+    const android = await annotateAndroidBootability(androidAll);
+    return { android, ios, toolsMissing };
+}
+export async function annotateAndroidBootability(devices) {
+    const out = [];
+    for (const dev of devices) {
+        if (dev.state !== 'shutdown' || dev.type !== 'android' || !dev.avdName) {
+            out.push(dev);
+            continue;
+        }
+        const { image, sdkRoot } = await resolveAvdSdk(dev.avdName);
+        if (image && !sdkRoot) {
+            out.push({
+                ...dev,
+                bootable: false,
+                bootHint: `system image "${image}" is not installed in any Android SDK`,
+            });
+        }
+        else {
+            out.push(dev);
+        }
+    }
+    return out;
+}
+async function detectMissingTools() {
+    const out = {};
+    if (!(await commandExists('adb')))
+        out.adb = true;
+    if (!(await commandExists('emulator')))
+        out.emulator = true;
+    if (process.platform === 'darwin' && !(await commandExists('xcrun')))
+        out.xcrun = true;
+    return out;
+}
+async function listAndroid() {
+    const avds = (await commandExists('emulator')) ? await runningAvds() : [];
+    const online = (await commandExists('adb'))
+        ? await onlineAdbDevices()
+        : new Map();
+    const out = [];
+    const claimedSerials = new Set();
+    for (const avd of avds) {
+        let serial;
+        let osVersion;
+        for (const [s, info] of online) {
+            if (info.avdName === avd) {
+                serial = s;
+                osVersion = info.osVersion;
+                claimedSerials.add(s);
+                break;
+            }
+        }
+        out.push({
+            type: 'android',
+            udid: serial ?? `avd:${avd}`,
+            name: avd.replaceAll('_', ' '),
+            osVersion,
+            state: serial ? 'booted' : 'shutdown',
+            avdName: avd,
+        });
+    }
+    for (const [serial, info] of online) {
+        if (claimedSerials.has(serial))
+            continue;
+        out.push({
+            type: 'android',
+            udid: serial,
+            name: info.avdName ?? serial,
+            osVersion: info.osVersion,
+            state: 'booted',
+            avdName: info.avdName,
+        });
+    }
+    return out;
+}
+async function runningAvds() {
+    try {
+        const { stdout } = await execFileP('emulator', ['-list-avds']);
+        return stdout
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+async function onlineAdbDevices() {
+    const out = new Map();
+    let stdout;
+    try {
+        ({ stdout } = await execFileP('adb', ['devices', '-l']));
+    }
+    catch {
+        return out;
+    }
+    const lines = stdout.split('\n').slice(1);
+    const serials = [];
+    for (const line of lines) {
+        const m = line.match(/^(\S+)\s+device\b/);
+        if (m)
+            serials.push(m[1]);
+    }
+    await Promise.all(serials.map(async (serial) => {
+        const info = {};
+        try {
+            const { stdout: name } = await execFileP('adb', [
+                '-s',
+                serial,
+                'shell',
+                'getprop',
+                'ro.boot.qemu.avd_name',
+            ]);
+            const trimmed = name.trim();
+            if (trimmed)
+                info.avdName = trimmed;
+        }
+        catch {
+            return;
+        }
+        if (!info.avdName) {
+            try {
+                const { stdout: name } = await execFileP('adb', ['-s', serial, 'emu', 'avd', 'name']);
+                info.avdName = name.split('\n')[0]?.trim();
+            }
+            catch {
+            }
+        }
+        try {
+            const { stdout: ver } = await execFileP('adb', [
+                '-s',
+                serial,
+                'shell',
+                'getprop',
+                'ro.build.version.release',
+            ]);
+            info.osVersion = ver.trim();
+        }
+        catch {
+        }
+        out.set(serial, info);
+    }));
+    return out;
+}
+export async function startAndroidEmulator(avdName) {
+    const { image, sdkRoot } = await resolveAvdSdk(avdName);
+    if (image && !sdkRoot) {
+        throw new Error(`Cannot boot "${avdName}": its system image "${image}" is not installed in any Android ` +
+            `SDK (checked the managed SDK, ANDROID_HOME, and your system SDK). Install it with ` +
+            `\`sdkmanager "${image.replace(/\//g, ';')}"\`, or recreate the AVD against an installed image.`);
+    }
+    const env = { ...process.env, ...((await androidEnvForAvd(avdName)) ?? {}) };
+    if (sdkRoot) {
+        env.ANDROID_HOME = sdkRoot;
+        env.ANDROID_SDK_ROOT = sdkRoot;
+    }
+    else if (env.ANDROID_HOME && !env.ANDROID_SDK_ROOT) {
+        env.ANDROID_SDK_ROOT = env.ANDROID_HOME;
+    }
+    const resolved = env.ANDROID_HOME
+        ? path.join(env.ANDROID_HOME, 'emulator', exe('emulator'))
+        : undefined;
+    const cmd = resolved && existsSync(resolved) ? resolved : 'emulator';
+    if (cmd === 'emulator' && !(await commandExists('emulator'))) {
+        throw new Error('No Android SDK found to boot the emulator — set ANDROID_HOME (or run `taqwright install`).');
+    }
+    const child = spawn(cmd, ['-avd', avdName], {
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env,
+    });
+    let out = '';
+    const accumulate = (d) => {
+        out += d.toString();
+    };
+    child.stdout?.on('data', accumulate);
+    child.stderr?.on('data', accumulate);
+    await new Promise((resolve, reject) => {
+        const done = () => {
+            clearTimeout(timer);
+            child.off('exit', onExit);
+            child.off('error', onError);
+        };
+        const onExit = (code) => {
+            done();
+            const tail = out.trim().split('\n').slice(-12).join('\n');
+            reject(new Error(`Emulator "${avdName}" exited (code ${code ?? 'null'}) during startup.` +
+                (tail ? `\n${tail}` : '')));
+        };
+        const onError = (err) => {
+            done();
+            reject(err);
+        };
+        const timer = setTimeout(() => {
+            done();
+            child.stdout?.off('data', accumulate);
+            child.stderr?.off('data', accumulate);
+            child.stdout?.resume();
+            child.stderr?.resume();
+            child.unref();
+            resolve();
+        }, 4000);
+        child.once('exit', onExit);
+        child.once('error', onError);
+    });
+    if (process.platform === 'win32')
+        maximizeEmulatorWindowWindows();
+}
+function maximizeEmulatorWindowWindows() {
+    const ps = [
+        'Add-Type @"',
+        'using System;using System.Runtime.InteropServices;',
+        'public class TwWin{',
+        '[DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h,int n);',
+        '[DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);',
+        '[DllImport("user32.dll")] public static extern bool IsZoomed(IntPtr h);}',
+        '"@',
+        '$deadline=(Get-Date).AddSeconds(60)',
+        '$stable=0',
+        'while((Get-Date) -lt $deadline){',
+        '  $p=Get-Process | Where-Object {$_.MainWindowTitle -like "*Android Emulator*" -and $_.MainWindowHandle -ne 0} | Select-Object -First 1',
+        '  if($p){',
+        '    $h=$p.MainWindowHandle',
+        '    if([TwWin]::IsZoomed($h)){ $stable++; if($stable -ge 3){ break } }',
+        '    else { [TwWin]::ShowWindow($h,3) | Out-Null; [TwWin]::SetForegroundWindow($h) | Out-Null; $stable=0 }',
+        '  }',
+        '  Start-Sleep -Milliseconds 1000',
+        '}',
+    ].join('\n');
+    try {
+        const encoded = Buffer.from(ps, 'utf16le').toString('base64');
+        const child = spawn('powershell', ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded], { detached: true, stdio: 'ignore', windowsHide: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+    }
+}
+export async function stopAndroidEmulator(serial) {
+    if (!serial.startsWith('emulator-')) {
+        throw new Error(`Cannot stop a device that isn't an emulator (got: ${serial}).`);
+    }
+    await execFileP('adb', ['-s', serial, 'emu', 'kill']);
+}
+export function findSerialForAvd(online, avdName) {
+    for (const [serial, info] of online) {
+        if (info.avdName === avdName)
+            return serial;
+    }
+    return undefined;
+}
+async function isAndroidDeviceReady(serial) {
+    try {
+        const { stdout: booted } = await execFileP('adb', [
+            '-s',
+            serial,
+            'shell',
+            'getprop',
+            'sys.boot_completed',
+        ]);
+        if (booted.trim() !== '1')
+            return false;
+        const { stdout: pmPath } = await execFileP('adb', [
+            '-s',
+            serial,
+            'shell',
+            'pm',
+            'path',
+            'android',
+        ]);
+        return pmPath.includes('package:');
+    }
+    catch {
+        return false;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function ensureAndroidAvdReady(avdName, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const deadline = Date.now() + timeoutMs;
+    let serial = findSerialForAvd(await onlineAdbDevices(), avdName);
+    if (!serial) {
+        await startAndroidEmulator(avdName);
+        while (!serial && Date.now() < deadline) {
+            await sleep(2000);
+            serial = findSerialForAvd(await onlineAdbDevices(), avdName);
+        }
+        if (!serial) {
+            throw new Error(`taqwright: AVD "${avdName}" did not come online within ${Math.round(timeoutMs / 1000)}s.`);
+        }
+    }
+    await execFileP('adb', ['-s', serial, 'wait-for-device']).catch(() => {
+    });
+    while (Date.now() < deadline) {
+        if (await isAndroidDeviceReady(serial))
+            return serial;
+        await sleep(2000);
+    }
+    throw new Error(`taqwright: emulator ${serial} (AVD "${avdName}") was not ready (boot_completed + ` +
+        `PackageManager) within ${Math.round(timeoutMs / 1000)}s.`);
+}
+export async function waitForAndroidDeviceReady(serial, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if ((await onlineAdbDevices()).has(serial) && (await isAndroidDeviceReady(serial))) {
+            return true;
+        }
+        await sleep(1500);
+    }
+    return false;
+}
+export async function resolveAndroidSerial(opts) {
+    const { udid, avdName } = opts;
+    if (udid && !udid.startsWith('avd:'))
+        return udid;
+    if (avdName)
+        return findSerialForAvd(await onlineAdbDevices(), avdName);
+    return undefined;
+}
+export function isTransientDeviceError(message) {
+    return [
+        /device offline/i,
+        /was not in the list of connected devices/i,
+        /io\.appium\.settings/i,
+        /error executing adbexec/i,
+        /cannot start the .* application/i,
+        /device unauthorized/i,
+    ].some((re) => re.test(message));
+}
+async function listIos() {
+    if (!(await commandExists('xcrun')))
+        return [];
+    let stdout;
+    try {
+        ({ stdout } = await execFileP('xcrun', ['simctl', 'list', 'devices', 'available', '--json']));
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const [runtimeKey, entries] of Object.entries(parsed.devices ?? {})) {
+        const osVersion = parseRuntimeVersion(runtimeKey);
+        for (const entry of entries) {
+            if (entry.isAvailable === false)
+                continue;
+            out.push({
+                type: 'ios',
+                udid: entry.udid,
+                name: entry.name,
+                osVersion,
+                state: stateFromSimctl(entry.state),
+                runtime: runtimeKey,
+            });
+        }
+    }
+    out.sort((a, b) => {
+        if (a.state !== b.state)
+            return a.state === 'booted' ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+    return out;
+}
+function parseRuntimeVersion(runtimeKey) {
+    const m = runtimeKey.match(/iOS-(\d+)-(\d+)$/);
+    return m ? `${m[1]}.${m[2]}` : undefined;
+}
+function stateFromSimctl(s) {
+    switch (s) {
+        case 'Booted':
+            return 'booted';
+        case 'Shutdown':
+            return 'shutdown';
+        case 'Booting':
+            return 'booting';
+        default:
+            return 'unknown';
+    }
+}
+export async function startIosSimulator(udid) {
+    if (!(await commandExists('xcrun'))) {
+        throw new Error('`xcrun` is not on PATH (Xcode command-line tools missing).');
+    }
+    await execFileP('xcrun', ['simctl', 'boot', udid]).catch((err) => {
+        if (!/already booted|state: Booted/i.test(String(err.stderr ?? err.message ?? '')))
+            throw err;
+    });
+    await execFileP('open', ['-a', 'Simulator']).catch(() => {
+    });
+}
+export async function stopIosSimulator(udid) {
+    await execFileP('xcrun', ['simctl', 'shutdown', udid]);
+}
+async function commandExists(name) {
+    return new Promise((resolve) => {
+        const child = spawn(process.platform === 'win32' ? 'where' : 'which', [name], {
+            stdio: 'ignore',
+        });
+        child.on('exit', (code) => resolve(code === 0));
+        child.on('error', () => resolve(false));
+    });
+}

package/dist/inspector/locator-suggester.d.ts

@@ -0,0 +1,23 @@
+import { Platform, type LocatorDescriptor } from '../types/index.js';
+export type LocatorCategory = 'id' | 'uiautomator' | 'predicate' | 'classChain' | 'xpath' | 'css';
+export interface LocatorCandidate {
+    category: LocatorCategory;
+    subLabel: string;
+    priority: number;
+    code: string;
+    using: string;
+    value: string;
+    descriptor?: LocatorDescriptor;
+}
+export interface LocatorSuggestion extends LocatorCandidate {
+    count: number;
+    unique: boolean;
+}
+export type ElementAttrs = Record<string, string | undefined>;
+export declare const CATEGORY_ORDER: Record<Platform, LocatorCategory[]>;
+export declare const WEB_CATEGORY_ORDER: LocatorCategory[];
+export declare function generateCandidates(platform: Platform, attrs: ElementAttrs, _xpath: string, isWeb?: boolean): LocatorCandidate[];
+export declare function selectBestPerCategory(platform: Platform, suggestions: LocatorSuggestion[], isWeb?: boolean): LocatorSuggestion[];
+export declare function isPositional(s: LocatorCandidate): boolean;
+export declare function pickRecommended(platform: Platform, verified: LocatorSuggestion[], isWeb?: boolean): LocatorSuggestion | undefined;
+export declare function makeNthSuggestion(base: LocatorCandidate, idx: number): LocatorSuggestion;