@leera.io/qa-runner 1.0.0

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

@@ -0,0 +1,535 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { bundledDrivers } from '../appium/drivers.js';
+import { AppiumUnavailable, bundledAppium, MJPEG_PORTS, PortRange } from '../appium/server.js';
+import { appExecutable, appPlatform, iosBuildDecision, unpackAppZip } from '../builds/ios-app.js';
+import { AppNotAvailable, resolveAppFile } from '../builds/install.js';
+import { leaseIosDevice, listIosDevices, Simctl } from '../devices/ios/index.js';
+import { SimulatorRecorder } from '../devices/ios/record.js';
+import { loadIosSettings } from '../devices/ios/settings.js';
+import { assertBundleId } from '../devices/ios/simctl.js';
+import { parseDeviceSyslogLine, SimulatorLogSink, SyslogCollector } from '../devices/ios/syslog.js';
+import { developerDir, isCommandLineToolsOnly, wdaRealDeviceDir, wdaStatus } from '../devices/ios/wda.js';
+import { homePaths } from '../home.js';
+import { renderTemplate } from '../template.js';
+import { AndroidAppiumDriver, androidSdkFor, APPIUM_LOG_MAX_BYTES, appiumLogLines, configuredSdkPath, LOCAL_PATHS_REFUSED, sharedAppiumServer } from './android-appium.js';
+import { Blocked, LaunchRefused, } from './driver.js';
+import { emptyScreen } from './snapshot/format.js';
+import { IOS_ACTIONS, runIosAction } from './webdriver/ios-actions.js';
+import { IOS_LOCATORS, iosFindAll } from './webdriver/ios-locate.js';
+import { candidates } from './webdriver/locate.js';
+import { mobile, openSession, webdriverMessage, xcuitestCapabilities } from './webdriver/session.js';
+import { iosSnapshotFromXml } from './webdriver/xml-tree-ios.js';
+/** WebDriverAgent ports on this Mac, one per device session. */
+export const WDA_PORTS = new PortRange(8100, 8199);
+const RECORDING_LIMIT_SECS = 1_800;
+export const IOS_NEEDS_MAC = 'iOS jobs need a Mac with Xcode';
+export const TEAM_ID_MISSING = 'real iOS devices need your Apple Developer Team ID to sign WebDriverAgent: run `leera-qa-runner config set ios.team_id <TEAM ID>` (or set RUNNER_IOS_TEAM_ID)';
+/** Labels for the iOS devices a runner can use now (available, or simulators it can boot). */
+export function iosDeviceLabels(devices) {
+    const labels = new Set();
+    for (const device of devices) {
+        if (device.platform !== 'ios' || device.state !== 'available')
+            continue;
+        for (const label of device.labels)
+            labels.add(label);
+    }
+    return [...labels];
+}
+export class IosAppiumDriver {
+    ctx;
+    appium;
+    simctl;
+    platform = 'ios';
+    capabilities = { actions: IOS_ACTIONS, targets: [...IOS_LOCATORS], video: 'mp4' };
+    client = null;
+    lease = null;
+    simLog = null;
+    realLog = null;
+    wdaPort = null;
+    mjpegPort = null;
+    releaseBuild = null;
+    unpacked = null;
+    /** The `.app` directory or `.ipa` installed for this job, when the app came from a build. */
+    installPath = null;
+    recording = false;
+    /** Simulators record with simctl (no ffmpeg needed); real devices through Appium. */
+    recorder = null;
+    videoPath;
+    videoStopped = false;
+    startedAt = Date.now();
+    offsets = new Map();
+    appiumLogOffsets = new Map();
+    lastRefs = {};
+    scale = null;
+    disposed = false;
+    constructor(ctx, appium, simctl = new Simctl()) {
+        this.ctx = ctx;
+        this.appium = appium;
+        this.simctl = simctl;
+    }
+    get bundleId() {
+        const id = this.ctx.job.app?.id;
+        if (!id)
+            throw new Blocked('the job names no iOS app (set the bundle id in the environment)');
+        return id;
+    }
+    get paths() {
+        return this.ctx.paths ?? homePaths(process.env);
+    }
+    async launch() {
+        const app = this.ctx.job.app;
+        if (!app?.id)
+            throw new Blocked('the job names no iOS app (set the bundle id in the environment)');
+        try {
+            assertBundleId(app.id);
+        }
+        catch (error) {
+            throw new LaunchRefused(webdriverMessage(error));
+        }
+        if (process.platform !== 'darwin')
+            throw new LaunchRefused(IOS_NEEDS_MAC);
+        if (app.install === 'path' && !this.ctx.allowLocalPaths)
+            throw new LaunchRefused(LOCAL_PATHS_REFUSED);
+        const claimed = this.ctx.job.device;
+        const device = this.ctx.lease?.device ?? (claimed ? { id: claimed.id, ...(claimed.kind === 'real' ? { kind: 'real' } : {}) } : null);
+        if (!device)
+            throw new Blocked('no iOS device was assigned to this job');
+        const kind = device.kind === 'real' ? 'real' : 'simulator';
+        // Refuse a build of the wrong kind before booting anything (contracts §I).
+        const namedFile = app.build?.file_name ?? (app.install === 'path' ? app.path : null);
+        if (app.install !== 'installed' && namedFile) {
+            const decision = iosBuildDecision(namedFile, kind);
+            if (!decision.ok)
+                throw new LaunchRefused(decision.message);
+        }
+        const settings = loadIosSettings(process.env, this.paths);
+        if (kind === 'real' && !settings.teamId)
+            throw new LaunchRefused([TEAM_ID_MISSING, ...settings.problems].join('; '));
+        try {
+            this.lease = await leaseIosDevice(device, {
+                simctl: this.simctl,
+                headed: !this.ctx.headless,
+                bootTimeoutMs: settings.simulatorBootTimeoutMs,
+                log: (message, fields) => this.ctx.log.info(message, fields),
+            });
+        }
+        catch (error) {
+            throw new Blocked(`the iOS device is not ready: ${webdriverMessage(error)}`);
+        }
+        const udid = this.lease.udid;
+        for (const problem of settings.problems)
+            this.ctx.log.warn('ios settings', { problem });
+        for (const warning of this.lease.warnings)
+            this.ctx.log.warn('simulator preparation', { udid, warning });
+        // The app under test.
+        let file = null;
+        try {
+            const resolved = await resolveAppFile({
+                app,
+                paths: this.paths,
+                allowLocalPaths: this.ctx.allowLocalPaths ?? false,
+                getUrl: (buildId) => {
+                    if (!this.ctx.buildDownloadUrl)
+                        throw new Blocked('this runner cannot download builds for this job');
+                    return this.ctx.buildDownloadUrl(buildId);
+                },
+            });
+            this.releaseBuild = resolved.release;
+            file = resolved.path;
+        }
+        catch (error) {
+            const message = `the app build is not available: ${webdriverMessage(error)}`;
+            throw error instanceof AppNotAvailable ? new LaunchRefused(message) : new Blocked(message);
+        }
+        let executable = null;
+        if (file) {
+            const decision = iosBuildDecision(app.build?.file_name ?? basename(file), kind);
+            if (!decision.ok)
+                throw new LaunchRefused(decision.message);
+            if (decision.kind === 'app_zip') {
+                try {
+                    this.unpacked = unpackAppZip(file);
+                }
+                catch (error) {
+                    throw new LaunchRefused(`the simulator build could not be unpacked: ${webdriverMessage(error)}`);
+                }
+                if (appPlatform(this.unpacked.app) === 'device') {
+                    throw new LaunchRefused('this .app was built for devices; simulators need a zipped .app built with -sdk iphonesimulator');
+                }
+                this.installPath = this.unpacked.app;
+                executable = appExecutable(this.unpacked.app);
+            }
+            else {
+                this.installPath = file;
+            }
+        }
+        // One Appium session per device.
+        const wda = await wdaStatus(this.paths);
+        if (!wda.dir)
+            throw new Blocked('WebDriverAgent cannot be built: Xcode or the XCUITest driver is missing (run `leera-qa-runner setup ios`)');
+        const prebuilt = kind === 'simulator' && wda.built;
+        if (kind === 'simulator' && !wda.built) {
+            this.ctx.log.warn('WebDriverAgent is not prebuilt; Appium builds it now (run `leera-qa-runner setup ios` once to skip this)', { dir: wda.dir });
+        }
+        const logOffset = this.appium.logOffset();
+        const sessionStarted = Date.now();
+        try {
+            const url = await this.appium.ensure();
+            this.wdaPort = await WDA_PORTS.take();
+            this.mjpegPort = await MJPEG_PORTS.take();
+            this.client = await openSession(url, xcuitestCapabilities({
+                udid,
+                simulator: kind === 'simulator',
+                platformVersion: this.lease.osVersion,
+                wdaLocalPort: this.wdaPort,
+                mjpegServerPort: this.mjpegPort,
+                derivedDataPath: kind === 'simulator' ? wda.dir : wdaRealDeviceDir(wda.dir),
+                usePrebuiltWDA: prebuilt,
+                newCommandTimeoutSecs: Math.max(300, Math.ceil((this.ctx.session?.idle_timeout_seconds ?? 0) + 60)),
+                isHeadless: !this.lease.uiClientRunning,
+                simulatorStartupTimeoutMs: settings.simulatorBootTimeoutMs,
+                teamId: settings.teamId,
+                signingId: settings.signingId,
+                wdaBundleId: settings.wdaBundleId,
+            }), prebuilt ? 300_000 : 1_200_000);
+        }
+        catch (error) {
+            const log = this.appium.logSince(logOffset, 2_000).trim().split('\n').slice(-5).join(' | ');
+            const reason = error instanceof AppiumUnavailable ? error.message : webdriverMessage(error);
+            throw new Blocked(`Appium could not start a session on ${udid}: ${reason}${log ? ` (appium: ${log})` : ''}`);
+        }
+        this.ctx.log.info('Appium session started', { udid, ms: Date.now() - sessionStarted, headless_simulator: kind === 'simulator' ? !this.lease.uiClientRunning : null });
+        // Per-job isolation: stop the app, then a fresh install from the build (or the installed app as it is).
+        const client = this.client;
+        await mobile(client, 'terminateApp', { bundleId: app.id }).catch(() => undefined);
+        if (this.installPath) {
+            try {
+                await this.reinstall();
+            }
+            catch (error) {
+                throw new Blocked(`the app could not be installed on ${udid}: ${webdriverMessage(error)}`);
+            }
+        }
+        else {
+            const installed = await mobile(client, 'isAppInstalled', { bundleId: app.id }).catch(() => true);
+            if (installed === false) {
+                throw new Blocked(`${app.id} is not installed on ${udid}; install it or let the environment install a build`);
+            }
+        }
+        // Device log: the simulator's unified log for the app's process; Appium's syslog on real devices.
+        executable ??= kind === 'simulator' ? await this.simctl.executableName(udid, app.id) : null;
+        if (executable) {
+            try {
+                if (kind === 'simulator') {
+                    this.simLog = new SimulatorLogSink(udid, executable, this.ctx.redact);
+                    this.simLog.start();
+                }
+                else if (client.getLogs) {
+                    this.realLog = new SyslogCollector(executable, this.ctx.redact);
+                }
+            }
+            catch (error) {
+                this.ctx.log.warn('the device log cannot be followed', { error: webdriverMessage(error) });
+            }
+        }
+        if (this.ctx.video !== 'off') {
+            try {
+                if (kind === 'simulator') {
+                    const recorder = new SimulatorRecorder(udid);
+                    this.recorder = recorder;
+                    await recorder.start();
+                }
+                else {
+                    await client.startRecordingScreen({ timeLimit: RECORDING_LIMIT_SECS, videoType: 'h264', forceRestart: true });
+                }
+                this.recording = true;
+            }
+            catch (error) {
+                // Real devices need ffmpeg on this Mac; the job runs without a video.
+                this.recorder = null;
+                this.ctx.log.warn('screen recording could not start', { error: webdriverMessage(error) });
+            }
+        }
+        this.startedAt = Date.now();
+        try {
+            await mobile(client, 'launchApp', { bundleId: app.id });
+        }
+        catch (error) {
+            throw new Blocked(`the app could not be launched: ${webdriverMessage(error)}`);
+        }
+    }
+    /** Uninstalls the app and installs the job's build again. */
+    async reinstall() {
+        const client = this.requireClient();
+        await mobile(client, 'removeApp', { bundleId: this.bundleId }).catch(() => undefined);
+        await mobile(client, 'installApp', { app: this.installPath, timeoutMs: 300_000 });
+    }
+    /** `reset`: a fresh install from the build, or (simulators, installed apps) cleared app data. */
+    async resetApp() {
+        if (this.installPath)
+            return this.reinstall();
+        if (this.lease?.kind === 'simulator') {
+            await mobile(this.requireClient(), 'clearApp', { bundleId: this.bundleId });
+            return;
+        }
+        throw new Blocked('reset needs the app to come from a build on real devices (the environment uses an installed app)');
+    }
+    requireClient() {
+        if (!this.client)
+            throw new Blocked('the app is not running');
+        return this.client;
+    }
+    actionContext() {
+        return {
+            client: this.requireClient(),
+            bundleId: this.bundleId,
+            render: (text) => renderTemplate(text, this.ctx.template),
+            defaultTimeoutMs: this.ctx.timeouts.actionMs,
+            resetApp: () => this.resetApp(),
+        };
+    }
+    async run(action) {
+        const prepared = action.target ? { ...action, target: AndroidAppiumDriver.resolveRefTarget(action.target) } : action;
+        try {
+            return await runIosAction(this.actionContext(), prepared);
+        }
+        catch (error) {
+            throw this.translate(error);
+        }
+    }
+    /** A lost Appium/WebDriverAgent session is an environment problem, not a failed check. */
+    translate(error) {
+        const message = webdriverMessage(error);
+        if (/invalid session id|session is either terminated|ECONNREFUSED|socket hang up|WebDriverAgent|xcodebuild failed/i.test(message)) {
+            return new Blocked(`the device connection was lost: ${message}`);
+        }
+        return error;
+    }
+    async find(target) {
+        const client = this.requireClient();
+        const render = (text) => renderTemplate(text, this.ctx.template);
+        for (const candidate of candidates(AndroidAppiumDriver.resolveRefTarget(target))) {
+            const ids = await iosFindAll(client, candidate, render);
+            if (ids.length === 0)
+                continue;
+            const refs = [];
+            for (const id of ids.slice(0, 20)) {
+                const rect = await client.getElementRect(id).catch(() => null);
+                if (!rect)
+                    continue;
+                const ref = Object.entries(this.lastRefs).find(([, value]) => value.bounds &&
+                    value.bounds.x === Math.round(rect.x) &&
+                    value.bounds.y === Math.round(rect.y) &&
+                    value.bounds.width === Math.round(rect.width) &&
+                    value.bounds.height === Math.round(rect.height));
+                if (ref && !refs.includes(ref[0]))
+                    refs.push(ref[0]);
+            }
+            return { count: ids.length, refs };
+        }
+        return { count: 0, refs: [] };
+    }
+    async snapshot(options = {}) {
+        const client = this.requireClient();
+        const xml = await client.getPageSource();
+        const tree = iosSnapshotFromXml(xml, {
+            ...(options.depth !== undefined ? { depth: options.depth } : {}),
+            ...(options.includeHidden !== undefined ? { includeHidden: options.includeHidden } : {}),
+            ...(options.maxChars !== undefined ? { maxChars: options.maxChars } : {}),
+        });
+        this.lastRefs = tree.refs;
+        const screen = await this.screen().catch(() => emptyScreen());
+        return {
+            platform: 'ios',
+            taken_at: new Date().toISOString(),
+            screen,
+            app: { id: tree.bundleId ?? this.bundleId, activity: null },
+            root: tree.root,
+            text: tree.text,
+            refs: tree.refs,
+            element_count: tree.element_count,
+            truncated: tree.truncated,
+        };
+    }
+    async screenshot() {
+        return Buffer.from(await this.requireClient().takeScreenshot(), 'base64');
+    }
+    source() {
+        return this.requireClient().getPageSource();
+    }
+    async screen() {
+        const client = this.requireClient();
+        const [rect, orientation, active] = await Promise.all([
+            client.getWindowRect().catch(() => null),
+            client.getOrientation().catch(() => null),
+            mobile(client, 'activeAppInfo').catch(() => null),
+        ]);
+        if (this.scale === null) {
+            const info = (await mobile(client, 'deviceScreenInfo').catch(() => null));
+            this.scale = typeof info?.scale === 'number' && info.scale > 0 ? info.scale : 0;
+        }
+        const bundle = active?.bundleId;
+        return {
+            width: rect?.width ?? null,
+            height: rect?.height ?? null,
+            scale: this.scale || null,
+            orientation: orientation ? (orientation.toLowerCase() === 'landscape' ? 'landscape' : 'portrait') : null,
+            activity: null,
+            url: null,
+            title: null,
+            package: typeof bundle === 'string' ? bundle : null,
+        };
+    }
+    /** Taps at screen coordinates in points (the snapshot's bounds). */
+    async tapAt(x, y) {
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            throw new Error('coordinates must be numbers');
+        await mobile(this.requireClient(), 'tap', { x: Math.round(x), y: Math.round(y) });
+    }
+    async home() {
+        await mobile(this.requireClient(), 'pressButton', { name: 'home' });
+    }
+    /** Real devices: Appium's syslog since the last read, fed to the collector. */
+    pollRealLog() {
+        const collector = this.realLog;
+        const client = this.client;
+        if (!collector || !client?.getLogs)
+            return;
+        void client
+            .getLogs('syslog')
+            .then((entries) => {
+            for (const entry of entries) {
+                const message = entry?.message;
+                if (typeof message === 'string')
+                    collector.accept(parseDeviceSyslogLine(message));
+            }
+        })
+            .catch(() => undefined);
+    }
+    get collector() {
+        return this.simLog?.collector ?? this.realLog;
+    }
+    drainLogs() {
+        this.simLog?.checkCrashes();
+        this.pollRealLog();
+        return this.collector?.drain() ?? [];
+    }
+    beginStep(index) {
+        this.simLog?.checkCrashes();
+        this.pollRealLog();
+        this.offsets.set(index, Math.round((Date.now() - this.startedAt) / 100) / 10);
+        this.appiumLogOffsets.set(index, this.appium.logOffset());
+        this.collector?.begin(index);
+    }
+    debug(index, result) {
+        this.simLog?.checkCrashes();
+        const captured = this.collector?.for(index);
+        const appium = result === 'failed' || result === 'blocked' ? this.appiumLogFor(index) : null;
+        if (!captured && !appium)
+            return undefined;
+        const offset = this.offsets.get(index);
+        const debug = { ...captured, ...(offset !== undefined && this.recording ? { video_offset_secs: offset } : {}) };
+        if (appium && appium.lines.length > 0) {
+            debug.appium_log = appium.lines;
+            if (appium.dropped > 0)
+                debug.dropped = { ...debug.dropped, appium_log: appium.dropped };
+        }
+        return debug;
+    }
+    appiumLogFor(index) {
+        const start = this.appiumLogOffsets.get(index);
+        if (start === undefined)
+            return null;
+        const later = [...this.appiumLogOffsets.entries()].filter(([i]) => i > index).map(([, offset]) => offset);
+        const end = later.length > 0 ? Math.min(...later) : undefined;
+        return appiumLogLines(this.appium.logSince(start, APPIUM_LOG_MAX_BYTES, end), this.ctx.redact);
+    }
+    async stopRecording() {
+        if (!this.recording || this.videoStopped)
+            return this.videoPath;
+        this.videoStopped = true;
+        if (this.recorder) {
+            this.videoPath = await this.recorder.stop();
+            return this.videoPath;
+        }
+        if (!this.client)
+            return undefined;
+        try {
+            const base64 = await this.client.stopRecordingScreen();
+            if (!base64)
+                return undefined;
+            const dir = mkdtempSync(join(tmpdir(), 'qa-video-'));
+            this.videoPath = join(dir, 'video.mp4');
+            writeFileSync(this.videoPath, Buffer.from(base64, 'base64'));
+            return this.videoPath;
+        }
+        catch (error) {
+            this.ctx.log.warn('screen recording could not be saved', { error: webdriverMessage(error) });
+            return undefined;
+        }
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.simLog?.stop();
+        if (this.recorder && !this.videoStopped) {
+            this.videoStopped = true;
+            await this.recorder.stop();
+            this.recorder.cleanup();
+        }
+        const client = this.client;
+        this.client = null;
+        const bundleId = this.ctx.job.app?.id;
+        if (client && bundleId) {
+            await mobile(client, 'terminateApp', { bundleId }).catch(() => undefined);
+            if (this.installPath)
+                await mobile(client, 'removeApp', { bundleId }).catch(() => undefined);
+        }
+        if (client)
+            await client.deleteSession().catch(() => undefined);
+        if (this.wdaPort !== null)
+            WDA_PORTS.release(this.wdaPort);
+        if (this.mjpegPort !== null)
+            MJPEG_PORTS.release(this.mjpegPort);
+        this.releaseBuild?.();
+        this.unpacked?.cleanup();
+        await this.lease?.release().catch(() => undefined);
+    }
+}
+export const iosDriverFactory = {
+    platform: 'ios',
+    async availability(host) {
+        if (host.os !== 'macos')
+            return { ok: false, labels: [], devices: [], reasons: [IOS_NEEDS_MAC] };
+        const reasons = [];
+        if (!bundledAppium())
+            reasons.push('Appium is not installed with this runner (optional dependencies were omitted)');
+        else if (bundledDrivers().every((d) => !d.platforms.includes('ios')))
+            reasons.push('the Appium XCUITest driver is not installed with this runner');
+        const dir = await developerDir();
+        if (!dir || isCommandLineToolsOnly(dir)) {
+            reasons.push('Xcode is not selected (install Xcode from the App Store, then run `sudo xcode-select -s /Applications/Xcode.app`)');
+            return { ok: false, labels: [], devices: [], reasons };
+        }
+        const inventory = await listIosDevices();
+        // devicectl missing (old Xcode) is not fatal when simulators are listed.
+        if (inventory.devices.length === 0)
+            reasons.push(...inventory.errors);
+        if (reasons.length > 0)
+            return { ok: false, labels: [], devices: [], reasons };
+        const usable = inventory.devices.filter((device) => device.state === 'available');
+        if (usable.length === 0) {
+            return { ok: false, labels: [], devices: inventory.devices, reasons: ['no iOS simulator exists and no iPhone or iPad is ready', ...inventory.notReady] };
+        }
+        return { ok: true, labels: iosDeviceLabels(usable), devices: inventory.devices, reasons: [] };
+    },
+    async create(ctx, shared) {
+        const paths = ctx.paths ?? homePaths(process.env);
+        // The same process-wide server serves Android and iOS; it keeps the Android SDK in its environment.
+        const appium = shared.appium ?? sharedAppiumServer(paths, androidSdkFor(process.env, ctx.androidSdkPath ?? configuredSdkPath(paths)));
+        return new IosAppiumDriver(ctx, appium);
+    },
+};