@leera.io/qa-runner 1.0.0

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

@@ -0,0 +1,282 @@
+import { basename } from 'node:path';
+import { disposeUnpacked } from '../builds/cleanup.js';
+import { AppNotAvailable, resolveAppFile } from '../builds/install.js';
+import { buildKind, DesktopBuildError, localDesktopApp, unpackDesktopBuild } from '../builds/unpack.js';
+import { findFfmpeg, ScreenRecorder } from '../devices/screen-record.js';
+import { homePaths } from '../home.js';
+import { renderTemplate } from '../template.js';
+import { APPIUM_LOG_MAX_BYTES, appiumLogLines, LOCAL_PATHS_REFUSED } from './android-appium.js';
+import { errorMessage } from './common.js';
+import { Blocked, LaunchRefused, NotFound, Unsupported } from './driver.js';
+import { runNativeAction } from './webdriver/native-actions.js';
+import { nativeFindAll, resolveNativeRef } from './webdriver/native-locate.js';
+import { candidates } from './webdriver/locate.js';
+import { webdriverMessage } from './webdriver/session.js';
+/**
+ * What native macOS and Windows drivers share (contracts §M): where the app comes from, the
+ * first `launch {args}`, the native action runner, refs, the Appium log per step and the ffmpeg
+ * screen recording.
+ */
+export const MAX_LAUNCH_ARGS = 20;
+export const MAX_LAUNCH_ARG_CHARS = 500;
+export const MSI_REFUSED = 'an .msi installer cannot run in place — upload a zip of the app';
+export const PKG_REFUSED = 'a .pkg installer cannot run in place — upload a zip of the app';
+/** Why a build file cannot run as a native desktop app of `platform`, or null (server wording). */
+export function nativeBuildRefusal(platform, fileName) {
+    const lower = fileName.toLowerCase();
+    if (lower.endsWith('.msi'))
+        return MSI_REFUSED;
+    if (lower.endsWith('.pkg'))
+        return PKG_REFUSED;
+    const kind = buildKind(lower);
+    if (platform === 'macos' && !['zip', 'app_zip', 'dmg'].includes(kind))
+        return 'a macos build must be a .zip or .dmg file';
+    if (platform === 'windows' && !['zip', 'app_zip', 'exe'].includes(kind))
+        return 'a windows build must be a .zip or .exe file';
+    return null;
+}
+/** Checks the native lifecycle actions' fields. */
+export function validateNativeAction(platform, action) {
+    if (action.type === 'launch') {
+        const args = action.args;
+        if (args === undefined)
+            return;
+        if (!Array.isArray(args) || args.length > MAX_LAUNCH_ARGS)
+            throw new Error(`launch args must be a list of at most ${MAX_LAUNCH_ARGS} strings`);
+        args.forEach((arg, i) => {
+            if (typeof arg !== 'string')
+                throw new Error(`launch args[${i}] must be a string`);
+            if (arg.length > MAX_LAUNCH_ARG_CHARS)
+                throw new Error(`launch args[${i}] is longer than ${MAX_LAUNCH_ARG_CHARS} characters`);
+        });
+        return;
+    }
+    if (action.type === 'focus_window') {
+        if (typeof action.title !== 'string' || action.title.length === 0)
+            throw new Error('focus_window needs a title');
+        if (action.index !== undefined)
+            throw new Unsupported(`focus_window on ${platform} takes a title, not an index`);
+    }
+}
+export class DesktopAppiumDriver {
+    ctx;
+    appium;
+    client = null;
+    unpacked = null;
+    releaseBuild = null;
+    recorder = null;
+    videoPath;
+    videoStopped = false;
+    firstLaunchDone = false;
+    actionsRun = 0;
+    lastRefs = {};
+    startedAt = Date.now();
+    offsets = new Map();
+    appiumLogOffsets = new Map();
+    constructor(ctx, appium) {
+        this.ctx = ctx;
+        this.appium = appium;
+    }
+    get paths() {
+        return this.ctx.paths ?? homePaths(process.env);
+    }
+    render = (text) => renderTemplate(text, this.ctx.template);
+    requireClient() {
+        if (!this.client)
+            throw new Error('the app is not running; start it with launch');
+        return this.client;
+    }
+    /** Resolves the app of the job: an installed app, or the executable of a build or local path. */
+    async resolveApp(os) {
+        const app = this.ctx.job.app;
+        if (!app)
+            throw new LaunchRefused(`the job names no ${this.platform} app (set the app in the environment)`);
+        const override = app.launch_activity?.trim() || null;
+        if (app.install === 'installed')
+            return { kind: 'installed', executable: null };
+        if (app.install === 'path') {
+            if (!this.ctx.allowLocalPaths)
+                throw new LaunchRefused(LOCAL_PATHS_REFUSED);
+            try {
+                return { kind: 'file', executable: localDesktopApp(app.path ?? '', override, os) };
+            }
+            catch (error) {
+                throw new LaunchRefused(errorMessage(error));
+            }
+        }
+        const named = app.build?.file_name;
+        const early = named ? nativeBuildRefusal(this.platform, named) : null;
+        if (early)
+            throw new LaunchRefused(early);
+        let file;
+        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: ${errorMessage(error)}`;
+            throw error instanceof AppNotAvailable ? new LaunchRefused(message) : new Blocked(message);
+        }
+        if (!file)
+            throw new LaunchRefused(`the job names no ${this.platform} build`);
+        const refusal = nativeBuildRefusal(this.platform, named ?? basename(file));
+        if (refusal)
+            throw new LaunchRefused(refusal);
+        try {
+            this.unpacked = unpackDesktopBuild(file, override, { os });
+        }
+        catch (error) {
+            const message = `the app build could not be unpacked: ${errorMessage(error)}`;
+            throw error instanceof DesktopBuildError ? new LaunchRefused(message) : new Blocked(message);
+        }
+        return { kind: 'file', executable: this.unpacked.executable };
+    }
+    /** The args of a leading `launch {args}` (that action is then not run again). */
+    firstLaunchArgs() {
+        const first = [...this.ctx.job.automation.steps].sort((a, b) => a.index - b.index)[0]?.actions[0];
+        if (first?.type !== 'launch')
+            return [];
+        validateNativeAction(this.platform, first);
+        this.firstLaunchDone = true;
+        return (first.args ?? []).map(this.render);
+    }
+    /** Starts a whole-screen recording when the job wants video and ffmpeg is installed. */
+    async startRecording() {
+        this.startedAt = Date.now();
+        if (this.ctx.video === 'off')
+            return;
+        const ffmpeg = findFfmpeg();
+        if (!ffmpeg)
+            return;
+        const recorder = new ScreenRecorder(ffmpeg, this.platform);
+        try {
+            await recorder.start();
+            this.recorder = recorder;
+        }
+        catch (error) {
+            this.ctx.log.warn('screen recording could not start', { error: errorMessage(error) });
+        }
+    }
+    actionContext() {
+        return {
+            client: this.requireClient(),
+            ops: this.ops,
+            render: this.render,
+            defaultTimeoutMs: this.ctx.timeouts.actionMs,
+        };
+    }
+    /** Runs a shared native action (not launch/terminate/focus_window). */
+    async runShared(action) {
+        const prepared = action.target ? { ...action, target: resolveNativeRef(action.target) } : action;
+        return runNativeAction(this.actionContext(), prepared);
+    }
+    /** Whether this action is the leading `launch` whose args the first start already used. */
+    skipFirstLaunch(action) {
+        const first = this.actionsRun === 0;
+        this.actionsRun += 1;
+        return action.type === 'launch' && first && this.firstLaunchDone;
+    }
+    /** A lost Appium/WebDriverAgent/WinAppDriver session is an environment problem, not a failed check. */
+    translate(error) {
+        if (error instanceof Blocked || error instanceof NotFound)
+            return error;
+        const message = webdriverMessage(error);
+        if (/invalid session id|session is either terminated|ECONNREFUSED|ECONNRESET|socket hang up|WebDriverAgent|WinAppDriver server|not listening/i.test(message)) {
+            return new Blocked(`the app connection was lost: ${message}`);
+        }
+        return error;
+    }
+    async find(target) {
+        const client = this.requireClient();
+        for (const candidate of candidates(resolveNativeRef(target))) {
+            const ids = await nativeFindAll(client, this.ops.selectors, candidate, this.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: [] };
+    }
+    snapshotOptions(options) {
+        return {
+            ...(options.depth !== undefined ? { depth: options.depth } : {}),
+            ...(options.includeHidden !== undefined ? { includeHidden: options.includeHidden } : {}),
+            ...(options.maxChars !== undefined ? { maxChars: options.maxChars } : {}),
+        };
+    }
+    async screenshot() {
+        return Buffer.from(await this.requireClient().takeScreenshot(), 'base64');
+    }
+    source() {
+        return this.requireClient().getPageSource();
+    }
+    async back() {
+        throw new Unsupported(`'back' is not available on ${this.platform}`);
+    }
+    async home() {
+        throw new Unsupported(`'home' is not available on ${this.platform}`);
+    }
+    beginStep(index) {
+        this.offsets.set(index, Math.round((Date.now() - this.startedAt) / 100) / 10);
+        this.appiumLogOffsets.set(index, this.appium.logOffset());
+    }
+    debug(index, result) {
+        if (result !== 'failed' && result !== 'blocked')
+            return undefined;
+        const start = this.appiumLogOffsets.get(index);
+        if (start === undefined)
+            return undefined;
+        const later = [...this.appiumLogOffsets.entries()].filter(([i]) => i > index).map(([, offset]) => offset);
+        const end = later.length > 0 ? Math.min(...later) : undefined;
+        const appium = appiumLogLines(this.appium.logSince(start, APPIUM_LOG_MAX_BYTES, end), this.ctx.redact);
+        if (appium.lines.length === 0)
+            return undefined;
+        const offset = this.offsets.get(index);
+        return {
+            appium_log: appium.lines,
+            ...(appium.dropped > 0 ? { dropped: { appium_log: appium.dropped } } : {}),
+            ...(offset !== undefined && this.recorder ? { video_offset_secs: offset } : {}),
+        };
+    }
+    async stopRecording() {
+        if (!this.recorder || this.videoStopped)
+            return this.videoPath;
+        this.videoStopped = true;
+        this.videoPath = await this.recorder.stop();
+        if (!this.videoPath)
+            this.recorder.cleanup();
+        return this.videoPath;
+    }
+    /** Stops recording (discarding an unfetched video) and removes the unpacked build. */
+    async disposeCommon() {
+        if (this.recorder && !this.videoStopped) {
+            this.videoStopped = true;
+            await this.recorder.stop();
+            this.recorder.cleanup();
+        }
+        await disposeUnpacked(this.unpacked, this.ctx.log);
+        this.releaseBuild?.();
+    }
+}

package/dist/src/drivers/driver.js

@@ -0,0 +1,15 @@
+/** The environment, not the application, stopped the step: unreachable site, missing credential, time limit. */
+export class Blocked extends Error {
+}
+/** The driver cannot perform this action or locator on its platform; reported as blocked. */
+export class Unsupported extends Blocked {
+}
+/**
+ * The job cannot start on this runner as it is configured (for example an app installed from a
+ * local path when `builds.allow_local_paths` is off): the case is reported blocked, not retried.
+ */
+export class LaunchRefused extends Blocked {
+}
+/** No element matched the target (session results report it as `not_found`). */
+export class NotFound extends Error {
+}