@leera.io/qa-runner 1.0.0

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

@@ -0,0 +1,525 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { appiumHomeDir } from '../appium/home.js';
+import { AppiumServer, AppiumUnavailable, bundledAppium, MJPEG_PORTS, SYSTEM_PORTS } from '../appium/server.js';
+import { bundledDrivers } from '../appium/drivers.js';
+import { AppNotAvailable, resolveAppFile } from '../builds/install.js';
+import { androidInstallable } from '../builds/unpack.js';
+import { Adb, resolveAndroidSdk } from '../devices/android/adb.js';
+import { leaseAndroidDevice, listAndroidDevices } from '../devices/android/index.js';
+import { LogcatSink } from '../devices/android/logcat.js';
+import { dismissSystemErrorDialog } from '../devices/android/system-dialog.js';
+import { homePaths, readJsonFile } from '../home.js';
+import { renderTemplate } from '../template.js';
+import { Blocked, LaunchRefused, NotFound, } from './driver.js';
+import { emptyScreen } from './snapshot/format.js';
+import { ANDROID_ACTIONS, androidKeyCode, runAndroidAction } from './webdriver/actions.js';
+import { ANDROID_LOCATORS, candidates, elementIdOf, findAll } from './webdriver/locate.js';
+import { mobile, openSession, uiautomator2Capabilities, webdriverMessage } from './webdriver/session.js';
+import { snapshotFromXml } from './webdriver/xml-tree.js';
+/** The screen recording limit Appium allows (30 min); longer jobs keep the last part only without ffmpeg. */
+const RECORDING_LIMIT_SECS = 1_800;
+export const LOCAL_PATHS_REFUSED = 'the environment installs the app from a file path on the runner, but this runner does not allow local paths (set builds.allow_local_paths to true, or RUNNER_ALLOW_LOCAL_PATHS=true)';
+export const APPIUM_LOG_MAX_LINES = 50;
+export const APPIUM_LOG_MAX_CHARS = 500;
+export const APPIUM_LOG_MAX_BYTES = 64_000;
+/** The last 50 non-empty lines of an Appium log slice, each cut to 500 characters and redacted. */
+export function appiumLogLines(text, redact) {
+    const all = text.split(/\r?\n/).filter((line) => line.trim() !== '');
+    const kept = all.slice(-APPIUM_LOG_MAX_LINES).map((line) => {
+        const clean = redact(line);
+        return clean.length > APPIUM_LOG_MAX_CHARS ? `${clean.slice(0, APPIUM_LOG_MAX_CHARS - 1)}…` : clean;
+    });
+    return { lines: kept, dropped: all.length - kept.length };
+}
+/** `android.sdk_path` from config.json, when the runner config has one. */
+export function configuredSdkPath(paths) {
+    try {
+        const file = readJsonFile(paths.config);
+        return file?.android?.sdk_path?.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function androidSdkFor(env, configured) {
+    return resolveAndroidSdk({ env, ...(configured ? { configured } : {}) });
+}
+/** Environment for Appium and its driver: the SDK they need, whatever the service started with. */
+export function appiumEnv(env, sdk) {
+    const out = { ...env };
+    if (sdk?.root) {
+        out.ANDROID_HOME = sdk.root;
+        out.ANDROID_SDK_ROOT = sdk.root;
+    }
+    return out;
+}
+let processAppium = null;
+/** The process-wide Appium server used when the runner does not pass one in `SharedResources`. */
+export function sharedAppiumServer(paths, sdk) {
+    processAppium ??= new AppiumServer({
+        home: appiumHomeDir(paths),
+        logFile: join(paths.logs, 'appium.log'),
+        env: appiumEnv(process.env, sdk),
+    });
+    return processAppium;
+}
+/**
+ * Stops the process-wide Appium server if one was started. Its child process keeps the event
+ * loop alive, so a runner that stops without calling this never exits.
+ */
+export async function stopSharedAppiumServer() {
+    const server = processAppium;
+    processAppium = null;
+    await server?.stop();
+}
+/** Labels for the devices a runner can use now (connected and authorised, or bootable AVDs). */
+export function androidDeviceLabels(devices) {
+    const labels = new Set();
+    for (const device of devices) {
+        if (device.platform !== 'android' || device.state !== 'available')
+            continue;
+        for (const label of device.labels)
+            labels.add(label);
+    }
+    return [...labels];
+}
+export class AndroidAppiumDriver {
+    ctx;
+    sdk;
+    appium;
+    platform = 'android';
+    capabilities = { actions: ANDROID_ACTIONS, targets: [...ANDROID_LOCATORS], video: 'mp4' };
+    client = null;
+    lease = null;
+    adb = null;
+    logcat = null;
+    systemPort = null;
+    mjpegPort = null;
+    releaseBuild = null;
+    recording = false;
+    videoPath;
+    videoStopped = false;
+    startedAt = Date.now();
+    offsets = new Map();
+    /** Appium log file size when each step began, to slice the log for failed steps. */
+    appiumLogOffsets = new Map();
+    lastRefs = {};
+    density = null;
+    installedFromFile = false;
+    disposed = false;
+    /** A step began: look for a system error dialog before its first action. */
+    dialogCheckPending = false;
+    constructor(ctx, sdk, appium) {
+        this.ctx = ctx;
+        this.sdk = sdk;
+        this.appium = appium;
+    }
+    get appId() {
+        const id = this.ctx.job.app?.id;
+        if (!id)
+            throw new Blocked('the job names no Android app (set the app 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 Android app (set the app in the environment)');
+        // Refuse before booting a device for nothing.
+        if (app.install === 'path' && !this.ctx.allowLocalPaths)
+            throw new LaunchRefused(LOCAL_PATHS_REFUSED);
+        const device = this.ctx.lease?.device ?? (this.ctx.job.device ? { id: this.ctx.job.device.id } : null);
+        if (!device)
+            throw new Blocked('no Android device was assigned to this job');
+        this.adb = new Adb(this.sdk.adb);
+        try {
+            this.lease = await leaseAndroidDevice(device, {
+                sdk: this.sdk,
+                headless: this.ctx.headless,
+                logFile: join(this.paths.logs, `emulator-${device.id.replace(/[^A-Za-z0-9_.-]/g, '_')}.log`),
+            });
+        }
+        catch (error) {
+            throw new Blocked(`the Android device is not ready: ${webdriverMessage(error)}`);
+        }
+        const serial = this.lease.serial;
+        // A booted AVD shows up as emulator-NNNN: keep it leased under that id too.
+        if (serial !== device.id)
+            this.ctx.lease?.bind?.(serial);
+        for (const warning of this.lease.warnings)
+            this.ctx.log.warn('device preparation', { serial, warning });
+        // Install 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);
+        }
+        if (file) {
+            try {
+                androidInstallable(file);
+                await this.adb.install(serial, file);
+                this.installedFromFile = true;
+            }
+            catch (error) {
+                throw new Blocked(`the app could not be installed on ${serial}: ${webdriverMessage(error)}`);
+            }
+        }
+        else if (!(await this.adb.isInstalled(serial, app.id))) {
+            throw new Blocked(`${app.id} is not installed on ${serial}; install it or let the environment install a build`);
+        }
+        // One Appium session per device.
+        const logOffset = this.appium.logOffset();
+        try {
+            const url = await this.appium.ensure();
+            this.systemPort = await SYSTEM_PORTS.take();
+            this.mjpegPort = await MJPEG_PORTS.take();
+            this.client = await openSession(url, uiautomator2Capabilities({
+                serial,
+                appPackage: app.id,
+                appActivity: app.launch_activity,
+                systemPort: this.systemPort,
+                mjpegServerPort: this.mjpegPort,
+                newCommandTimeoutSecs: Math.max(300, Math.ceil((this.ctx.session?.idle_timeout_seconds ?? 0) + 60)),
+            }));
+        }
+        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 ${serial}: ${reason}${log ? ` (appium: ${log})` : ''}`);
+        }
+        // Per-job isolation: no data from a previous job.
+        await mobile(this.client, 'clearApp', { appId: app.id }).catch((error) => {
+            throw new Blocked(`the app's data could not be cleared: ${webdriverMessage(error)}`);
+        });
+        this.logcat = new LogcatSink(this.adb, serial, app.id, this.ctx.redact);
+        this.logcat.start();
+        if (this.ctx.video !== 'off') {
+            try {
+                await this.client.startRecordingScreen({
+                    timeLimit: RECORDING_LIMIT_SECS,
+                    bitRate: 2_000_000,
+                    forceRestart: true,
+                });
+                this.recording = true;
+            }
+            catch (error) {
+                this.ctx.log.warn('screen recording could not start', { error: webdriverMessage(error) });
+            }
+        }
+        this.startedAt = Date.now();
+        await this.answerSystemDialog('before launch');
+        try {
+            if (app.launch_activity)
+                await runAndroidAction(this.actionContext(), { type: 'launch', activity: app.launch_activity });
+            else
+                await mobile(this.client, 'activateApp', { appId: app.id });
+        }
+        catch (error) {
+            throw new Blocked(`the app could not be launched: ${webdriverMessage(error)}`);
+        }
+    }
+    requireClient() {
+        if (!this.client)
+            throw new Blocked('the app is not running');
+        return this.client;
+    }
+    actionContext() {
+        return {
+            client: this.requireClient(),
+            appId: this.appId,
+            render: (text) => renderTemplate(text, this.ctx.template),
+            defaultTimeoutMs: this.ctx.timeouts.actionMs,
+        };
+    }
+    /** A ref's target: its suggestion, falling back to the exact element the snapshot saw. */
+    static resolveRefTarget(target) {
+        const { locate, ...rest } = target;
+        const xpath = typeof locate?.xpath === 'string' ? locate.xpath : null;
+        if (!xpath)
+            return rest;
+        return { ...rest, fallbacks: [...(rest.fallbacks ?? []), { xpath }] };
+    }
+    async run(action) {
+        const prepared = action.target ? { ...action, target: AndroidAppiumDriver.resolveRefTarget(action.target) } : action;
+        if (this.dialogCheckPending) {
+            this.dialogCheckPending = false;
+            await this.answerSystemDialog('before the step');
+        }
+        try {
+            return await runAndroidAction(this.actionContext(), prepared);
+        }
+        catch (error) {
+            // A system dialog (System UI or the launcher not responding) may cover the app: answer it and retry once.
+            if (error instanceof NotFound && (await this.answerSystemDialog('after a failed locate'))) {
+                try {
+                    return await runAndroidAction(this.actionContext(), prepared);
+                }
+                catch (retryError) {
+                    throw this.translate(retryError);
+                }
+            }
+            throw this.translate(error);
+        }
+    }
+    /**
+     * Answers a system "isn't responding" / "keeps stopping" dialog that is not about the app under
+     * test (Wait, or Close app) and notes it in the step's device log. Dialogs about the app under
+     * test are left for the step to fail on. True when a dialog was answered.
+     */
+    async answerSystemDialog(when) {
+        const client = this.client;
+        const adb = this.adb;
+        const serial = this.lease?.serial;
+        if (!client || !adb || !serial)
+            return false;
+        const note = await dismissSystemErrorDialog(this.ctx.job.app?.id ?? null, {
+            pageSource: () => client.getPageSource(),
+            dumpsysWindows: () => adb.shell(serial, ['dumpsys', 'window', 'windows'], 15_000),
+            tapId: async (resourceId) => {
+                const found = await client.findElements('id', resourceId);
+                if (found.length === 0)
+                    return false;
+                await client.elementClick(elementIdOf(found[0]));
+                return true;
+            },
+        });
+        if (!note)
+            return false;
+        const text = `${note} ${when}`;
+        this.logcat?.collector.note(text);
+        this.ctx.log.warn(text);
+        // Let the dialog close and the app underneath redraw.
+        await new Promise((resolve) => setTimeout(resolve, 1_000));
+        return true;
+    }
+    /** A lost Appium/UiAutomator2 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|instrumentation process is not running|UiAutomator2 server/i.test(message)) {
+            return new Blocked(`the device connection was lost: ${message}`);
+        }
+        return error;
+    }
+    async find(target) {
+        const found = await this.findOnce(target);
+        if (found.count === 0 && (await this.answerSystemDialog('after a failed find')))
+            return this.findOnce(target);
+        return found;
+    }
+    async findOnce(target) {
+        const client = this.requireClient();
+        const render = (text) => renderTemplate(text, this.ctx.template);
+        for (const candidate of candidates(AndroidAppiumDriver.resolveRefTarget(target))) {
+            const ids = await findAll(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 === rect.x &&
+                    value.bounds.y === rect.y &&
+                    value.bounds.width === rect.width &&
+                    value.bounds.height === 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 = snapshotFromXml(xml, {
+            appPackage: this.appId,
+            ...(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: 'android',
+            taken_at: new Date().toISOString(),
+            screen,
+            app: { id: this.appId, activity: screen.activity },
+            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, activity, pkg] = await Promise.all([
+            client.getWindowRect().catch(() => null),
+            client.getOrientation().catch(() => null),
+            mobile(client, 'getCurrentActivity').catch(() => null),
+            mobile(client, 'getCurrentPackage').catch(() => null),
+        ]);
+        if (this.density === null) {
+            const density = await mobile(client, 'getDisplayDensity').catch(() => null);
+            this.density = typeof density === 'number' && density > 0 ? density : 0;
+        }
+        return {
+            width: rect?.width ?? null,
+            height: rect?.height ?? null,
+            scale: this.density ? Math.round((this.density / 160) * 1000) / 1000 : null,
+            orientation: orientation ? (orientation.toLowerCase() === 'landscape' ? 'landscape' : 'portrait') : null,
+            activity: typeof activity === 'string' ? activity : null,
+            url: null,
+            title: null,
+            package: typeof pkg === 'string' ? pkg : null,
+        };
+    }
+    async tapAt(x, y) {
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            throw new Error('coordinates must be numbers');
+        await mobile(this.requireClient(), 'clickGesture', { x: Math.round(x), y: Math.round(y) });
+    }
+    async back() {
+        await mobile(this.requireClient(), 'pressKey', { keycode: androidKeyCode('back') });
+    }
+    async home() {
+        await mobile(this.requireClient(), 'pressKey', { keycode: androidKeyCode('home') });
+    }
+    drainLogs() {
+        return this.logcat?.collector.drain() ?? [];
+    }
+    beginStep(index) {
+        this.offsets.set(index, Math.round((Date.now() - this.startedAt) / 100) / 10);
+        this.appiumLogOffsets.set(index, this.appium.logOffset());
+        this.logcat?.collector.begin(index);
+        this.dialogCheckPending = true;
+    }
+    debug(index, result) {
+        const captured = this.logcat?.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;
+    }
+    /** The Appium log lines written from step `index`'s start to the next step's start (or now). */
+    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 || !this.client)
+            return this.videoPath;
+        this.videoStopped = true;
+        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.logcat?.stop();
+        const client = this.client;
+        this.client = null;
+        const appId = this.ctx.job.app?.id;
+        if (client && appId) {
+            await mobile(client, 'terminateApp', { appId }).catch(() => undefined);
+        }
+        if (client)
+            await client.deleteSession().catch(() => undefined);
+        if (this.adb && this.lease && appId && this.installedFromFile) {
+            await this.adb.uninstall(this.lease.serial, appId);
+        }
+        if (this.systemPort !== null)
+            SYSTEM_PORTS.release(this.systemPort);
+        if (this.mjpegPort !== null)
+            MJPEG_PORTS.release(this.mjpegPort);
+        this.releaseBuild?.();
+        await this.lease?.release().catch(() => undefined);
+    }
+}
+export const androidDriverFactory = {
+    platform: 'android',
+    async availability(_host) {
+        const paths = homePaths(process.env);
+        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('android'))) {
+            reasons.push('the Appium UiAutomator2 driver is not installed with this runner');
+        }
+        const sdk = androidSdkFor(process.env, configuredSdkPath(paths));
+        if (!sdk) {
+            reasons.push('the Android SDK was not found (set ANDROID_HOME, or run `leera-qa-runner setup android`)');
+            return { ok: false, labels: [], devices: [], reasons };
+        }
+        let devices = [];
+        try {
+            devices = await listAndroidDevices(sdk, process.env);
+        }
+        catch (error) {
+            reasons.push(`adb could not list devices: ${webdriverMessage(error)}`);
+        }
+        if (reasons.length > 0)
+            return { ok: false, labels: [], devices: [], reasons };
+        const usable = devices.filter((device) => device.state === 'available');
+        if (usable.length === 0) {
+            return { ok: false, labels: [], devices, reasons: ['no Android device is connected and no emulator (AVD) exists'] };
+        }
+        return { ok: true, labels: androidDeviceLabels(usable), devices, reasons: [] };
+    },
+    async create(ctx, shared) {
+        const paths = ctx.paths ?? homePaths(process.env);
+        const sdk = androidSdkFor(process.env, ctx.androidSdkPath ?? configuredSdkPath(paths));
+        if (!sdk)
+            throw new Blocked('the Android SDK was not found on this runner (set ANDROID_HOME)');
+        return new AndroidAppiumDriver(ctx, sdk, shared.appium ?? sharedAppiumServer(paths, sdk));
+    },
+};

package/dist/src/drivers/common.js

@@ -0,0 +1,64 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { renderTemplate } from '../template.js';
+export const POLL_MS = 200;
+/** Polls `check` until it holds or `timeout` passes, then fails with "expected …". */
+export async function expectWithin(timeout, check, expectation) {
+    const deadline = Date.now() + timeout;
+    for (;;) {
+        if (await check().catch(() => false))
+            return;
+        if (Date.now() >= deadline) {
+            throw new Error(`expected ${typeof expectation === 'string' ? expectation : expectation()}`);
+        }
+        await sleep(POLL_MS);
+    }
+}
+export function requireTarget(action) {
+    if (!action.target)
+        throw new Error(`'${action.type}' needs a target`);
+    return action.target;
+}
+export function render(text, ctx) {
+    return renderTemplate(text ?? '', ctx);
+}
+export function matches(actual, expected, mode) {
+    return mode === 'equals' ? actual === expected : actual.includes(expected);
+}
+export function verb(mode) {
+    return mode === 'equals' ? 'equal' : 'contain';
+}
+export function describe(action) {
+    if (action.description)
+        return action.description;
+    return action.target ? `${action.type} ${describeTarget(action.target)}` : action.type;
+}
+export function describeTarget(target) {
+    if (target.role)
+        return target.name ? `${target.role} "${target.name}"` : target.role;
+    if (target.label)
+        return `field labelled "${target.label}"`;
+    if (target.placeholder)
+        return `field with placeholder "${target.placeholder}"`;
+    if (target.text)
+        return `text "${target.text}"`;
+    if (target.test_id)
+        return `test id "${target.test_id}"`;
+    return `element "${target.css ?? ''}"`;
+}
+export function screenshotName(index, name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40) || 'screenshot';
+    return `step-${index + 1}-${slug}.png`;
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function firstLine(error) {
+    return (errorMessage(error).split('\n')[0] ?? '').slice(0, 500);
+}
+export function clip(text) {
+    return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}