@leera.io/qa-runner 1.0.0

package/dist/src/drivers/mac2-appium.js

@@ -0,0 +1,313 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { AppiumUnavailable, PortRange } from '../appium/server.js';
+import { hostDevice } from '../devices/desktop.js';
+import { ACCESSIBILITY_BLOCKED, appBundleOf, BUNDLE_ID_RE, isAccessibilityError, MACOS_NEEDS_MAC, mac2Capabilities, macosReadiness, markAccessibilityBlocked, readBundleId, } from '../devices/macos.js';
+import { homePaths } from '../home.js';
+import { androidSdkFor, configuredSdkPath, sharedAppiumServer } from './android-appium.js';
+import { clip, errorMessage, expectWithin } from './common.js';
+import { DesktopAppiumDriver, validateNativeAction } from './desktop-appium.js';
+import { Blocked, LaunchRefused, } from './driver.js';
+import { emptyScreen } from './snapshot/format.js';
+import { macKey } from './webdriver/desktop-keys.js';
+import { predicateString } from './webdriver/ios-locate.js';
+import { elementIdOf } from './webdriver/locate.js';
+import { NATIVE_DESKTOP_ACTIONS } from './webdriver/native-actions.js';
+import { describeMacTarget, MACOS_LOCATORS, macSelectors } from './webdriver/native-locate.js';
+import { openSession, webdriverMessage } from './webdriver/session.js';
+import { macSnapshotFromXml } from './webdriver/xml-tree-desktop.js';
+/** WebDriverAgentMac ports on this Mac. */
+export const MAC2_PORTS = new PortRange(10100, 10199);
+/** XCUIElementType raw values the driver checks (`elementType` attribute). */
+const ELEMENT_TYPE_COMBO_BOX = '15';
+/** Runs a Mac2 `macos:` extension command. */
+export function macos(client, command, args = {}) {
+    if (!/^[a-zA-Z]+$/.test(command))
+        throw new Error(`invalid macos command '${command}'`);
+    return client.executeScript(`macos: ${command}`, [args]);
+}
+/** The class chain that finds a window whose title contains (or equals) `title`. */
+export function macWindowChain(title, exact) {
+    const literal = predicateString(title).replace(/`/g, '\\`');
+    return `**/XCUIElementTypeWindow[\`title ${exact ? '==' : 'CONTAINS'} ${literal}\`]`;
+}
+export function macOps(client) {
+    return {
+        platform: 'macos',
+        selectors: macSelectors,
+        describe: describeMacTarget,
+        click: async (elementId) => void (await macos(client, 'click', { elementId })),
+        doubleClick: async (elementId) => void (await macos(client, 'doubleClick', { elementId })),
+        rightClick: async (elementId) => void (await macos(client, 'rightClick', { elementId })),
+        hover: async (elementId) => void (await macos(client, 'hover', { elementId })),
+        press: async (chord, elementId) => {
+            await macos(client, 'keys', { keys: [macKey(chord)], ...(elementId ? { elementId } : {}) });
+        },
+        isChecked: async (elementId) => {
+            const value = (await client.getElementAttribute(elementId, 'value').catch(() => null))?.trim().toLowerCase();
+            if (value === '1' || value === 'true')
+                return true;
+            if (value === '0' || value === 'false')
+                return false;
+            return null;
+        },
+        selectOption: async (elementId, value, timeoutMs) => {
+            const type = await client.getElementAttribute(elementId, 'elementType').catch(() => null);
+            if (type === ELEMENT_TYPE_COMBO_BOX) {
+                await client.elementClear(elementId);
+                await client.elementSendKeys(elementId, value);
+                return;
+            }
+            // A pop-up button: open its menu and click the item.
+            await macos(client, 'click', { elementId });
+            const chain = `**/XCUIElementTypeMenuItem[\`title == ${predicateString(value).replace(/`/g, '\\`')}\`]`;
+            const deadline = Date.now() + Math.max(timeoutMs, 500);
+            for (;;) {
+                for (const found of await client.findElements('-ios class chain', chain).catch(() => [])) {
+                    const id = elementIdOf(found);
+                    if (await client.isElementDisplayed(id).catch(() => false)) {
+                        await macos(client, 'click', { elementId: id });
+                        return;
+                    }
+                }
+                if (Date.now() >= deadline)
+                    break;
+                await sleep(300);
+            }
+            const titles = [];
+            for (const found of (await client.findElements('-ios class chain', '**/XCUIElementTypeMenuItem').catch(() => [])).slice(0, 30)) {
+                const id = elementIdOf(found);
+                if (!(await client.isElementDisplayed(id).catch(() => false)))
+                    continue;
+                const title = await client.getElementAttribute(id, 'title').catch(() => null);
+                if (title)
+                    titles.push(`"${clip(title)}"`);
+            }
+            await macos(client, 'keys', { keys: [macKey({ modifiers: [], key: 'escape' })] }).catch(() => undefined);
+            throw new Error(`the list has no option "${value}" (options: ${titles.join(', ') || 'none'})`);
+        },
+        text: async (elementId) => {
+            const text = (await client.getElementText(elementId).catch(() => '')) ?? '';
+            if (text.trim())
+                return text.trim();
+            for (const name of ['value', 'title', 'label']) {
+                const value = await client.getElementAttribute(elementId, name).catch(() => null);
+                if (value?.trim())
+                    return value.trim();
+            }
+            return '';
+        },
+    };
+}
+/** Native macOS apps through Appium Mac2 (contracts §M). */
+export class Mac2AppiumDriver extends DesktopAppiumDriver {
+    deps;
+    platform = 'macos';
+    capabilities = { actions: NATIVE_DESKTOP_ACTIONS, targets: [...MACOS_LOCATORS], video: 'mp4' };
+    bundleId = null;
+    /** The `.app` to launch by path (builds and local paths), so an installed copy is never used instead. */
+    appPath = null;
+    port = null;
+    launched = false;
+    disposed = false;
+    constructor(ctx, appium, deps = {}) {
+        super(ctx, appium);
+        this.deps = deps;
+    }
+    get ops() {
+        return macOps(this.requireClient());
+    }
+    async launch() {
+        if (process.platform !== 'darwin' && !this.deps.open)
+            throw new LaunchRefused(MACOS_NEEDS_MAC);
+        const app = this.ctx.job.app;
+        const resolved = await this.resolveApp('macos');
+        if (resolved.kind === 'installed') {
+            const id = app?.id?.trim() ?? '';
+            if (!id)
+                throw new LaunchRefused('an installed macOS app needs its bundle id (set the app id in the environment)');
+            if (!BUNDLE_ID_RE.test(id))
+                throw new LaunchRefused(`'${id}' is not a bundle id`);
+            this.bundleId = id;
+        }
+        else {
+            const bundle = appBundleOf(resolved.executable ?? '');
+            if (!bundle)
+                throw new LaunchRefused('macOS apps must be .app bundles (the build or path holds no .app)');
+            this.appPath = bundle;
+            try {
+                this.bundleId = await (this.deps.readBundleId ?? readBundleId)(bundle);
+            }
+            catch (error) {
+                throw new LaunchRefused(`the app's bundle id could not be read: ${errorMessage(error)}`);
+            }
+            if (app?.id && app.id !== this.bundleId) {
+                this.ctx.log.warn('the build has a different bundle id than the environment names', { environment: app.id, build: this.bundleId });
+            }
+        }
+        const args = this.firstLaunchArgs();
+        await this.openSession();
+        await this.startRecording();
+        await this.start(args);
+    }
+    async openSession() {
+        // Appium may (re)start and truncate its log in ensure(): measure the offset afterwards.
+        let logOffset = 0;
+        try {
+            const url = await this.appium.ensure();
+            logOffset = this.appium.logOffset();
+            this.port = await MAC2_PORTS.take();
+            const capabilities = mac2Capabilities({
+                systemPort: this.port,
+                newCommandTimeoutSecs: Math.max(300, Math.ceil((this.ctx.session?.idle_timeout_seconds ?? 0) + 60)),
+            });
+            this.client = await (this.deps.open ?? openSession)(url, capabilities, 600_000);
+        }
+        catch (error) {
+            const log = this.appium.logSince(logOffset, 256_000);
+            const reason = error instanceof AppiumUnavailable ? error.message : webdriverMessage(error);
+            if (isAccessibilityError(`${reason}\n${log}`)) {
+                markAccessibilityBlocked(this.paths, reason);
+                throw new LaunchRefused(ACCESSIBILITY_BLOCKED);
+            }
+            const tail = log.trim().split('\n').slice(-5).join(' | ');
+            throw new Blocked(`Appium could not start a Mac2 session: ${reason}${tail ? ` (appium: ${clip(tail)})` : ''}`);
+        }
+    }
+    appArgs() {
+        return this.appPath ? { path: this.appPath } : { bundleId: this.bundleId };
+    }
+    /** Quits a running copy, then launches the app fresh with `args`. */
+    async start(args) {
+        const client = this.requireClient();
+        await macos(client, 'terminateApp', { bundleId: this.bundleId }).catch(() => undefined);
+        try {
+            await macos(client, 'launchApp', { ...this.appArgs(), arguments: args });
+            this.launched = true;
+        }
+        catch (error) {
+            const message = webdriverMessage(error);
+            if (isAccessibilityError(message)) {
+                markAccessibilityBlocked(this.paths, message);
+                throw new LaunchRefused(ACCESSIBILITY_BLOCKED);
+            }
+            throw new Blocked(`the app could not be launched: ${message}`);
+        }
+    }
+    async run(action) {
+        if (this.skipFirstLaunch(action))
+            return {};
+        validateNativeAction('macos', action);
+        try {
+            switch (action.type) {
+                case 'launch':
+                    await this.start((action.args ?? []).map(this.render));
+                    return {};
+                case 'terminate':
+                    await macos(this.requireClient(), 'terminateApp', { bundleId: this.bundleId });
+                    this.launched = false;
+                    return {};
+                case 'focus_window':
+                    await this.focusWindow(action);
+                    return {};
+                default:
+                    return await this.runShared(action);
+            }
+        }
+        catch (error) {
+            throw this.translate(error);
+        }
+    }
+    /** Activates the app and raises the window with that title (a click on its title bar). */
+    async focusWindow(action) {
+        const client = this.requireClient();
+        const timeout = action.timeout_ms ?? this.ctx.timeouts.actionMs;
+        const wanted = this.render(action.title ?? '');
+        await macos(client, 'activateApp', { bundleId: this.bundleId }).catch(() => undefined);
+        const chain = macWindowChain(wanted, action.match === 'equals');
+        let titles = [];
+        await expectWithin(timeout, async () => {
+            const found = await client.findElements('-ios class chain', chain);
+            const first = found[0];
+            if (!first) {
+                titles = [];
+                for (const window of (await client.findElements('-ios class chain', '**/XCUIElementTypeWindow').catch(() => [])).slice(0, 10)) {
+                    const title = await client.getElementAttribute(elementIdOf(window), 'title').catch(() => null);
+                    titles.push(`"${clip(title ?? '')}"`);
+                }
+                return false;
+            }
+            const rect = await client.getElementRect(elementIdOf(first));
+            await macos(client, 'click', { x: Math.round(rect.x + rect.width / 2), y: Math.round(rect.y + 8) });
+            return true;
+        }, () => `a window whose title ${action.match === 'equals' ? 'equals' : 'contains'} "${wanted}", found ${titles.join(', ') || 'none'}`);
+    }
+    async snapshot(options = {}) {
+        const client = this.requireClient();
+        const tree = macSnapshotFromXml(await client.getPageSource(), this.snapshotOptions(options));
+        this.lastRefs = tree.refs;
+        const screen = await this.screen().catch(() => emptyScreen());
+        return {
+            platform: 'macos',
+            taken_at: new Date().toISOString(),
+            screen,
+            app: { id: this.bundleId, activity: null },
+            root: tree.root,
+            text: tree.text,
+            refs: tree.refs,
+            element_count: tree.element_count,
+            truncated: tree.truncated,
+        };
+    }
+    async screen() {
+        const client = this.requireClient();
+        const rect = await client.getWindowRect().catch(() => null);
+        const window = (await client.findElements('-ios class chain', '**/XCUIElementTypeWindow').catch(() => []))[0];
+        const title = window ? await client.getElementAttribute(elementIdOf(window), 'title').catch(() => null) : null;
+        return {
+            width: rect?.width ?? null,
+            height: rect?.height ?? null,
+            scale: null,
+            orientation: null,
+            activity: null,
+            url: null,
+            title: title || null,
+            package: this.bundleId,
+        };
+    }
+    /** Clicks at screen coordinates (the snapshot's bounds, in points). */
+    async tapAt(x, y) {
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            throw new Error('coordinates must be numbers');
+        await macos(this.requireClient(), 'click', { x: Math.round(x), y: Math.round(y) });
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await this.disposeCommon();
+        const client = this.client;
+        this.client = null;
+        if (client && this.launched && this.bundleId)
+            await macos(client, 'terminateApp', { bundleId: this.bundleId }).catch(() => undefined);
+        if (client)
+            await Promise.race([client.deleteSession().catch(() => undefined), sleep(30_000)]);
+        if (this.port !== null)
+            MAC2_PORTS.release(this.port);
+    }
+}
+export const mac2DriverFactory = {
+    platform: 'macos',
+    async availability(host) {
+        if (host.os !== 'macos')
+            return { ok: false, labels: [], devices: [], reasons: [MACOS_NEEDS_MAC] };
+        const readiness = await macosReadiness(homePaths(process.env));
+        if (!readiness.ok)
+            return { ok: false, labels: [], devices: [], reasons: readiness.reasons };
+        return { ok: true, labels: ['macos'], devices: [hostDevice('macos', { name: host.hostname })], reasons: [] };
+    },
+    async create(ctx, shared) {
+        const paths = ctx.paths ?? homePaths(process.env);
+        const appium = shared.appium ?? sharedAppiumServer(paths, androidSdkFor(process.env, ctx.androidSdkPath ?? configuredSdkPath(paths)));
+        return new Mac2AppiumDriver(ctx, appium);
+    },
+};

package/dist/src/drivers/registry.js

@@ -0,0 +1,47 @@
+import { androidDriverFactory } from './android-appium.js';
+import { electronDriverFactory } from './electron-playwright.js';
+import { iosDriverFactory } from './ios-appium.js';
+import { mac2DriverFactory } from './mac2-appium.js';
+import { tauriDriverFactory } from './tauri-webdriver.js';
+import { webPlaywrightFactory } from './web-playwright.js';
+import { windowsDriverFactory } from './windows-appium.js';
+/** True in the web-only Docker image (`ENV RUNNER_DOCKER=1` in the Dockerfile). */
+export function isDockerRunner(env = process.env) {
+    return ['1', 'true', 'yes', 'on'].includes((env.RUNNER_DOCKER ?? '').trim().toLowerCase());
+}
+/**
+ * The factories this runner version ships: web (Playwright), android (Appium UiAutomator2),
+ * ios (Appium XCUITest), electron (Playwright), tauri (WebDriver), macos (Appium Mac2) and
+ * windows (Appium Windows + WinAppDriver). The Docker image is web-only (contracts §L): with
+ * `RUNNER_DOCKER=1` only web is registered, so it never advertises desktop host devices.
+ */
+export function defaultFactories(env = process.env) {
+    if (isDockerRunner(env))
+        return [webPlaywrightFactory];
+    return [webPlaywrightFactory, androidDriverFactory, iosDriverFactory, electronDriverFactory, tauriDriverFactory, mac2DriverFactory, windowsDriverFactory];
+}
+/** The platforms this runner version can drive. */
+export function createRegistry(factories = defaultFactories()) {
+    return new Map(factories.map((factory) => [factory.platform, factory]));
+}
+/**
+ * Every platform's availability on this host. A factory that throws is reported as
+ * unavailable with the error instead of failing the whole check.
+ */
+export async function registryAvailability(registry, host) {
+    const out = new Map();
+    for (const [platform, factory] of registry) {
+        try {
+            out.set(platform, await factory.availability(host));
+        }
+        catch (error) {
+            out.set(platform, {
+                ok: false,
+                labels: [],
+                devices: [],
+                reasons: [`could not check: ${error instanceof Error ? error.message : String(error)}`],
+            });
+        }
+    }
+    return out;
+}