@leera.io/qa-runner 1.0.0

package/dist/src/drivers/electron-playwright.js

@@ -0,0 +1,566 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { _electron, chromium } from 'playwright-core';
+import { AppNotAvailable, resolveAppFile } from '../builds/install.js';
+import { disposeUnpacked, endWindowsProcessesUnder, taskkillArgv } from '../builds/cleanup.js';
+import { DesktopBuildError, localDesktopApp, unpackDesktopBuild } from '../builds/unpack.js';
+import { DebugCollector } from '../debug.js';
+import { ensureDisplay, hostDevice } from '../devices/desktop.js';
+import { homePaths } from '../home.js';
+import { playwrightVersion } from '../version.js';
+import { LOCAL_PATHS_REFUSED } from './android-appium.js';
+import { clip, errorMessage, expectWithin, firstLine, matches, render } from './common.js';
+import { Blocked, LaunchRefused, Unsupported, } from './driver.js';
+import { webSnapshot } from './snapshot/aria.js';
+import { findOnPage, NO_FFMPEG_VIDEO, playwrightFfmpeg, runWebAction, WEB_ACTIONS } from './web-playwright.js';
+/** Electron DSL (contracts §K): web actions minus `goto`, plus launch, terminate and focus_window. */
+export const ELECTRON_ACTIONS = [...WEB_ACTIONS.filter((action) => action !== 'goto'), 'launch', 'terminate', 'focus_window'];
+export const ELECTRON_TARGETS = ['role', 'label', 'placeholder', 'text', 'test_id', 'css'];
+export const MAX_LAUNCH_ARGS = 20;
+export const MAX_LAUNCH_ARG_CHARS = 500;
+export const MAX_WINDOW_INDEX = 100;
+export const INSTALLED_REFUSED = 'electron apps need an uploaded build or a path on the runner';
+const LAUNCH_TIMEOUT_MS = 60_000;
+const PAINT_TIMEOUT_MS = 15_000;
+const VIDEO_SIZE = { width: 1024, height: 576 };
+/** Switches the runner controls itself (debugging ports); a script cannot pass them. */
+const RESERVED_ARG = /^--(inspect|inspect-brk|inspect-port|remote-debugging-port|remote-debugging-pipe|remote-allow-origins)(=|$)/i;
+/** Runner secrets never reach the app's environment. */
+const SECRET_ENV = new Set(['RUNNER_TOKEN', 'LEERA_RUNNER_TOKEN', 'ELECTRON_RUN_AS_NODE', 'NODE_OPTIONS']);
+/** Checks an Electron-only action before it runs; throws what the step reports. */
+export function validateElectronAction(action) {
+    if (action.type === 'goto')
+        throw new Unsupported("'goto' is not an electron action; start the app with launch");
+    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`);
+            if (RESERVED_ARG.test(arg))
+                throw new Error(`launch args[${i}] '${arg.split('=')[0]}' is reserved for the runner`);
+        });
+        return;
+    }
+    if (action.type === 'focus_window') {
+        const hasTitle = typeof action.title === 'string' && action.title.length > 0;
+        const hasIndex = action.index !== undefined;
+        if (hasTitle === hasIndex)
+            throw new Error('focus_window needs exactly one of title or index');
+        if (hasIndex && (!Number.isInteger(action.index) || action.index < 0 || action.index > MAX_WINDOW_INDEX)) {
+            throw new Error(`focus_window index must be a window number from 0 to ${MAX_WINDOW_INDEX}`);
+        }
+    }
+}
+/** The app's environment: the runner's, minus its secrets, plus the display. */
+export function electronEnv(base, extra = {}) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (value !== undefined && !SECRET_ENV.has(key.toUpperCase()))
+            env[key] = value;
+    }
+    return { ...env, ...extra };
+}
+/** The argv of the fallback launch: the app's own arguments plus a DevTools port on loopback. */
+export function cdpLaunchArgv(args, port) {
+    return [...args, `--remote-debugging-port=${port}`, '--remote-allow-origins=http://127.0.0.1'];
+}
+export { endWindowsProcessesUnder, parseWindowsProcesses, taskkillArgv, windowsProcessesUnder, windowsProcessesUnderArgv, } from '../builds/cleanup.js';
+/** Ends a process and everything it started (Electron helpers): the process group on POSIX, taskkill /T on Windows. */
+export function killProcessTree(pid, platform = process.platform) {
+    if (!pid)
+        return;
+    if (platform === 'win32') {
+        spawnSync('taskkill', taskkillArgv(pid), { stdio: 'ignore', windowsHide: true, timeout: 15_000 });
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+export class ElectronPlaywrightDriver {
+    ctx;
+    options;
+    platform = 'electron';
+    capabilities = { actions: ELECTRON_ACTIONS, targets: ELECTRON_TARGETS, video: 'webm' };
+    executable = null;
+    unpacked = null;
+    releaseBuild = null;
+    display = null;
+    instance = null;
+    /** Windows of the running app in opening order (closed ones removed). */
+    windows = [];
+    page = null;
+    collector = null;
+    videoDir = null;
+    videos = [];
+    videoPath;
+    videoStopped = false;
+    /** The script's first action is `launch`: `launch()` already started the app with its args. */
+    firstLaunchDone = false;
+    actionsRun = 0;
+    snapshotTaken = false;
+    disposed = false;
+    constructor(ctx, options = {}) {
+        this.ctx = ctx;
+        this.options = options;
+    }
+    /** How the running app is connected: Playwright's Electron launch or the DevTools-port fallback. */
+    get connection() {
+        return this.instance?.via ?? null;
+    }
+    /** The running app's process id. */
+    get pid() {
+        return this.instance?.process?.pid ?? null;
+    }
+    get paths() {
+        return this.ctx.paths ?? homePaths(process.env);
+    }
+    /** Where the app comes from: an unpacked build, or an app at a path on this runner. */
+    async resolveExecutable() {
+        const app = this.ctx.job.app;
+        if (!app)
+            throw new LaunchRefused('the job names no Electron app (set the app in the environment)');
+        const override = app.launch_activity?.trim() || null;
+        if (app.install === 'installed')
+            throw new LaunchRefused(INSTALLED_REFUSED);
+        if (app.install === 'path') {
+            if (!this.ctx.allowLocalPaths)
+                throw new LaunchRefused(LOCAL_PATHS_REFUSED);
+            try {
+                return localDesktopApp(app.path ?? '', override);
+            }
+            catch (error) {
+                throw new LaunchRefused(errorMessage(error));
+            }
+        }
+        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(INSTALLED_REFUSED);
+        try {
+            this.unpacked = unpackDesktopBuild(file, override);
+        }
+        catch (error) {
+            const message = `the app build could not be unpacked: ${errorMessage(error)}`;
+            throw error instanceof DesktopBuildError ? new LaunchRefused(message) : new Blocked(message);
+        }
+        return this.unpacked.executable;
+    }
+    async launch() {
+        this.executable = await this.resolveExecutable();
+        try {
+            this.display = await ensureDisplay();
+        }
+        catch (error) {
+            throw new Blocked(errorMessage(error));
+        }
+        if (this.ctx.video !== 'off') {
+            if (playwrightFfmpeg() === null)
+                this.ctx.log.warn(NO_FFMPEG_VIDEO);
+            else
+                this.videoDir = await mkdtemp(join(tmpdir(), 'qa-video-'));
+        }
+        this.collector = new DebugCollector(Date.now(), this.ctx.redact);
+        // A script that starts with `launch {args}` gets its arguments on the first start.
+        const first = [...this.ctx.job.automation.steps].sort((a, b) => a.index - b.index)[0]?.actions[0];
+        let args = [];
+        if (first?.type === 'launch') {
+            validateElectronAction(first);
+            args = (first.args ?? []).map((arg) => render(arg, this.ctx.template));
+            this.firstLaunchDone = true;
+        }
+        await this.start(args);
+    }
+    async start(args) {
+        const executable = this.executable;
+        if (!executable)
+            throw new Blocked('the app was not prepared');
+        const env = electronEnv(process.env, this.display?.env ?? {});
+        const cwd = dirname(executable);
+        try {
+            if (this.options.launchVia === 'cdp')
+                throw new Error('the DevTools-port launch was requested');
+            const electron = await _electron.launch({
+                executablePath: executable,
+                args,
+                env,
+                cwd,
+                timeout: LAUNCH_TIMEOUT_MS,
+                acceptDownloads: false,
+                ...(this.videoDir ? { recordVideo: { dir: this.videoDir, size: VIDEO_SIZE } } : {}),
+            });
+            this.adopt({ via: 'playwright', electron, browser: null, context: electron.context(), process: electron.process(), video: null, closed: false });
+            electron.on('window', (page) => this.addWindow(page));
+            for (const page of electron.windows())
+                this.addWindow(page);
+            if (this.windows.length === 0)
+                await electron.firstWindow({ timeout: LAUNCH_TIMEOUT_MS });
+        }
+        catch (error) {
+            if (this.instance)
+                await this.closeInstance();
+            this.ctx.log.warn('Playwright could not launch the Electron app; retrying with a DevTools port', { error: firstLine(error) });
+            try {
+                await this.startOverCdp(executable, args, env, cwd);
+            }
+            catch (fallback) {
+                throw new Blocked(`the app could not be launched: ${firstLine(error)}; with a DevTools port: ${firstLine(fallback)}`);
+            }
+        }
+        const page = this.windows[0];
+        if (!page)
+            throw new Blocked('the app opened no window');
+        this.page = page;
+        await page.waitForLoadState('domcontentloaded', { timeout: LAUNCH_TIMEOUT_MS }).catch(() => undefined);
+        await this.waitForPaint(page, 'launch');
+    }
+    /**
+     * Waits until the window is visible and has painted (two animation frames). A loaded DOM is not
+     * enough: right after a cold start the window may produce no frames yet (seen on a fresh Linux
+     * VM under Xvfb), and Chromium's screenshot waits for a frame, so the first screenshot timed out
+     * while actions on the DOM passed. Animation frames only run while frames are produced. Bounded;
+     * a window that never paints is reported by the step that needs it, not here.
+     */
+    async waitForPaint(page, when) {
+        const started = Date.now();
+        const frames = page
+            .evaluate(() => new Promise((resolve) => {
+            const tick = () => {
+                if (document.visibilityState === 'visible')
+                    requestAnimationFrame(() => requestAnimationFrame(() => resolve(true)));
+                else
+                    setTimeout(tick, 250);
+            };
+            tick();
+        }))
+            .catch(() => false);
+        const timer = new AbortController();
+        const painted = await Promise.race([frames, sleep(PAINT_TIMEOUT_MS, false, { signal: timer.signal }).catch(() => false)]);
+        timer.abort();
+        const ms = Date.now() - started;
+        if (!painted)
+            this.ctx.log.warn(`the app window did not paint within ${Math.round(PAINT_TIMEOUT_MS / 1000)} s after ${when}`);
+        else if (ms > 2_000)
+            this.ctx.log.warn(`the app window took ${ms} ms to paint after ${when}`);
+    }
+    /** Fallback for apps whose fuses block Playwright's launch: spawn with a DevTools port and connect over CDP. */
+    async startOverCdp(executable, args, env, cwd) {
+        const port = await freePort();
+        const child = spawn(executable, cdpLaunchArgv(args, port), {
+            cwd,
+            env,
+            stdio: 'ignore',
+            detached: process.platform !== 'win32',
+            windowsHide: false,
+        });
+        let exited = null;
+        child.once('exit', (code, signal) => {
+            exited = `the app exited (${signal ?? `code ${code}`})`;
+        });
+        child.once('error', (error) => {
+            exited = `the app could not start: ${error.message}`;
+        });
+        const instance = { via: 'cdp', electron: null, browser: null, context: null, process: child, video: null, closed: false };
+        try {
+            const endpoint = `http://127.0.0.1:${port}`;
+            const deadline = Date.now() + LAUNCH_TIMEOUT_MS;
+            for (;;) {
+                if (exited)
+                    throw new Error(exited);
+                const ready = await fetch(`${endpoint}/json/version`, { signal: AbortSignal.timeout(2_000) }).then((response) => response.ok, () => false);
+                if (ready)
+                    break;
+                if (Date.now() > deadline)
+                    throw new Error(`no DevTools endpoint on port ${port} within ${LAUNCH_TIMEOUT_MS / 1000} s`);
+                await sleep(250);
+            }
+            const browser = await chromium.connectOverCDP(endpoint, { timeout: LAUNCH_TIMEOUT_MS });
+            const context = browser.contexts()[0];
+            if (!context)
+                throw new Error('the app exposes no browser context');
+            instance.browser = browser;
+            instance.context = context;
+            this.adopt(instance);
+            context.on('page', (page) => this.addWindow(page));
+            for (const page of context.pages())
+                this.addWindow(page);
+            if (this.windows.length === 0)
+                await context.waitForEvent('page', { timeout: LAUNCH_TIMEOUT_MS });
+            if (this.videoDir)
+                this.ctx.log.warn('video is not recorded for an Electron app launched with a DevTools port');
+            return instance;
+        }
+        catch (error) {
+            await this.closeInstance();
+            killProcessTree(child.pid);
+            throw error;
+        }
+    }
+    adopt(instance) {
+        this.instance = instance;
+        this.windows = [];
+        this.page = null;
+    }
+    addWindow(page) {
+        if (this.windows.includes(page) || page.url().startsWith('devtools://'))
+            return;
+        this.windows.push(page);
+        page.setDefaultTimeout(this.ctx.timeouts.actionMs);
+        page.setDefaultNavigationTimeout(Math.max(this.ctx.timeouts.actionMs, 30_000));
+        this.collector?.attach(page);
+        const instance = this.instance;
+        if (instance && !instance.video && instance.via === 'playwright') {
+            const video = page.video();
+            if (video) {
+                instance.video = video;
+                this.videos.push(video);
+            }
+        }
+        page.once('close', () => {
+            this.windows = this.windows.filter((p) => p !== page);
+            if (this.page === page)
+                this.page = this.windows[0] ?? null;
+        });
+    }
+    async run(action) {
+        const first = this.actionsRun === 0;
+        this.actionsRun += 1;
+        validateElectronAction(action);
+        switch (action.type) {
+            case 'launch': {
+                if (first && this.firstLaunchDone)
+                    return {};
+                await this.closeInstance();
+                await this.start((action.args ?? []).map((arg) => render(arg, this.ctx.template)));
+                return {};
+            }
+            case 'terminate':
+                await this.closeInstance();
+                return {};
+            case 'focus_window':
+                await this.focusWindow(action);
+                return {};
+            default:
+                return runWebAction(this.requirePage(), action, this.ctx.template, this.ctx.timeouts.actionMs);
+        }
+    }
+    async focusWindow(action) {
+        if (!this.instance)
+            throw new Error('the app is not running; start it with launch');
+        const timeout = action.timeout_ms ?? this.ctx.timeouts.actionMs;
+        const wanted = action.title !== undefined ? render(action.title, this.ctx.template) : null;
+        let titles = [];
+        let found = null;
+        await expectWithin(timeout, async () => {
+            const open = this.windows.filter((page) => !page.isClosed());
+            if (wanted === null) {
+                found = open[action.index ?? 0] ?? null;
+                titles = [];
+                return found !== null;
+            }
+            titles = await Promise.all(open.map((page) => page.title().catch(() => '')));
+            const i = titles.findIndex((title) => matches(title, wanted, action.match));
+            found = i >= 0 ? open[i] : null;
+            return found !== null;
+        }, () => wanted === null
+            ? `window ${action.index} to be open, found ${this.windows.length} window(s)`
+            : `a window whose title ${action.match === 'equals' ? 'equals' : 'contains'} "${wanted}", found ${titles.map((t) => `"${clip(t)}"`).join(', ') || 'none'}`);
+        const page = found;
+        if (!page)
+            return;
+        this.page = page;
+        await page.bringToFront().catch(() => undefined);
+        await this.waitForPaint(page, 'focus_window');
+    }
+    find(target) {
+        return findOnPage(this.requirePage(), target, this.ctx.template, this.snapshotTaken);
+    }
+    async snapshot(options = {}) {
+        const page = this.requirePage();
+        const snapshot = await webSnapshot(page, options);
+        snapshot.screen = await this.screen();
+        this.snapshotTaken = true;
+        return snapshot;
+    }
+    /** The focused window: its inner size, URL and title (Electron windows have no emulated viewport). */
+    async screen() {
+        const page = this.requirePage();
+        const size = await page
+            .evaluate(() => ({ width: window.innerWidth, height: window.innerHeight, scale: window.devicePixelRatio }))
+            .catch(() => null);
+        return {
+            width: size?.width ?? null,
+            height: size?.height ?? null,
+            scale: size?.scale ?? null,
+            orientation: size ? (size.width >= size.height ? 'landscape' : 'portrait') : null,
+            activity: null,
+            url: page.url(),
+            title: await page.title().catch(() => null),
+            package: this.ctx.job.app?.id || null,
+        };
+    }
+    async tapAt(x, y) {
+        await this.requirePage().mouse.click(x, y);
+    }
+    async back() {
+        throw new Unsupported("'back' is not available on electron");
+    }
+    async home() {
+        throw new Unsupported("'home' is not available on electron");
+    }
+    screenshot() {
+        return this.requirePage().screenshot({ type: 'png' });
+    }
+    source() {
+        return this.requirePage().content();
+    }
+    beginStep(index) {
+        this.collector?.begin(index);
+    }
+    debug(index) {
+        return this.collector?.for(index);
+    }
+    /** Closes the app (a video is only complete then) and returns the longest recording. */
+    async stopRecording() {
+        if (this.videoStopped)
+            return this.videoPath;
+        this.videoStopped = true;
+        await this.closeInstance();
+        let best = null;
+        for (const video of this.videos) {
+            const path = await video.path().catch(() => undefined);
+            if (!path)
+                continue;
+            const size = await stat(path).then((s) => s.size, () => 0);
+            if (size > 0 && (!best || size > best.size))
+                best = { path, size };
+        }
+        this.videoPath = best?.path;
+        if (!this.videoPath && this.videoDir) {
+            await rm(this.videoDir, { recursive: true, force: true }).catch(() => undefined);
+            this.videoDir = null;
+        }
+        return this.videoPath;
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await this.closeInstance();
+        // Without a returned video (stopRecording not called, or nothing recorded) the directory is ours to delete.
+        if (!this.videoPath && this.videoDir)
+            await rm(this.videoDir, { recursive: true, force: true }).catch(() => undefined);
+        await this.display?.stop().catch(() => undefined);
+        await disposeUnpacked(this.unpacked, this.ctx.log);
+        this.releaseBuild?.();
+    }
+    /** Closes the running app gracefully, then kills whatever of its process tree is left. */
+    async closeInstance() {
+        const instance = this.instance;
+        this.instance = null;
+        this.windows = [];
+        this.page = null;
+        this.snapshotTaken = false;
+        if (!instance || instance.closed)
+            return;
+        instance.closed = true;
+        const pid = instance.process?.pid;
+        const graceful = instance.electron
+            ? instance.electron.close()
+            : (async () => {
+                for (const page of instance.context?.pages() ?? [])
+                    await page.close({ runBeforeUnload: false }).catch(() => undefined);
+                await instance.browser?.close();
+            })();
+        await Promise.race([graceful.catch(() => undefined), sleep(10_000)]);
+        killProcessTree(pid);
+        await this.endLeftoverProcesses();
+    }
+    /** Windows: no process from the app's folder may outlive the instance (see endWindowsProcessesUnder). */
+    async endLeftoverProcesses() {
+        if (process.platform !== 'win32')
+            return;
+        const dir = this.unpacked?.root ?? (this.executable ? dirname(this.executable) : null);
+        if (!dir)
+            return;
+        // A folder the runner unpacked is ours alone: anything naming it on its command line goes too.
+        const { killed, remaining } = await endWindowsProcessesUnder(dir, { commandLine: this.unpacked?.tempDir === dir });
+        if (killed.length > 0)
+            this.ctx.log.warn('ended app processes left running after the app closed', { processes: killed.map((p) => `${p.pid} ${p.name}`) });
+        if (remaining.length > 0)
+            this.ctx.log.warn('app processes are still running after 15 s', { processes: remaining.map((p) => `${p.pid} ${p.name}`) });
+    }
+    requirePage() {
+        if (!this.page || this.page.isClosed()) {
+            if (!this.instance)
+                throw new Error('the app is not running; start it with launch');
+            const next = this.windows.find((page) => !page.isClosed());
+            if (!next)
+                throw new Error('the app has no open window');
+            this.page = next;
+        }
+        return this.page;
+    }
+}
+/** True when this playwright-core can drive Electron. */
+export function electronSupported() {
+    return typeof _electron?.launch === 'function';
+}
+export const electronDriverFactory = {
+    platform: 'electron',
+    async availability(host) {
+        if (!electronSupported() || !playwrightVersion()) {
+            return { ok: false, labels: [], devices: [], reasons: ['playwright-core with Electron support is not installed with this runner'] };
+        }
+        return { ok: true, labels: ['electron'], devices: [hostDevice('electron', { name: host.hostname })], reasons: [] };
+    },
+    async create(ctx, _shared) {
+        return new ElectronPlaywrightDriver(ctx);
+    },
+};