@leera.io/qa-runner 1.0.6 → 1.2.0

package/dist/src/drivers/common.js

@@ -1,5 +1,5 @@
 import { setTimeout as sleep } from 'node:timers/promises';
-import { renderTemplate } from '../template.js';
+import { renderTemplate, TemplateError } 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) {
@@ -21,8 +21,46 @@ export function requireTarget(action) {
 export function render(text, ctx) {
     return renderTemplate(text ?? '', ctx);
 }
+/** Schemes a rendered launch arg may not carry: they run code or read the runner's files. */
+const LOCAL_SCHEMES = /^(javascript|vbscript|file|data|blob)$/i;
+/**
+ * The scheme a URL parser would read from `text`. Parsers drop leading control characters and
+ * spaces, and tabs and line breaks anywhere, so `java<tab>script:` still counts as `javascript:`.
+ */
+function urlScheme(text) {
+    let start = 0;
+    while (start < text.length && text.charCodeAt(start) <= 0x20)
+        start += 1;
+    return /^([a-z][a-z0-9+.-]*):/i.exec(text.slice(start).replace(/[\t\n\r]/g, ''))?.[1];
+}
+/**
+ * Renders a `launch` action's args. An arg filled from a placeholder is checked once rendered,
+ * since a data value can hold anything: it must not become a URL (the whole arg, or the value of
+ * `--name=value`) with a scheme that runs code or reads local files, or a switch `reserved` names.
+ */
+export function renderLaunchArgs(args, renderText, reserved) {
+    return (args ?? []).map((arg, i) => {
+        const rendered = renderText(arg);
+        if (rendered === arg)
+            return rendered;
+        const value = /^-[^=\s]*=/.test(rendered) ? rendered.slice(rendered.indexOf('=') + 1) : rendered;
+        const scheme = urlScheme(value);
+        if (scheme && LOCAL_SCHEMES.test(scheme)) {
+            throw new TemplateError(`launch args[${i}] renders a ${scheme.toLowerCase()}: URL, which the runner does not pass to the app`);
+        }
+        if (reserved?.test(rendered))
+            throw new TemplateError(`launch args[${i}] renders '${rendered.split('=')[0]}', which is reserved for the runner`);
+        return rendered;
+    });
+}
+/**
+ * Compares visible text with what the script expects. Both sides are normalised to Unicode NFC,
+ * so an "é" typed as one character matches one the app renders as "e" plus a combining accent.
+ */
 export function matches(actual, expected, mode) {
-    return mode === 'equals' ? actual === expected : actual.includes(expected);
+    const have = actual.normalize('NFC');
+    const want = expected.normalize('NFC');
+    return mode === 'equals' ? have === want : have.includes(want);
 }
 export function verb(mode) {
     return mode === 'equals' ? 'equal' : 'contain';

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

@@ -2,11 +2,12 @@ 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 { ensureFfmpeg } from '../devices/ffmpeg.js';
+import { 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 { errorMessage, renderLaunchArgs } 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';
@@ -148,16 +149,17 @@ export class DesktopAppiumDriver {
             return [];
         validateNativeAction(this.platform, first);
         this.firstLaunchDone = true;
-        return (first.args ?? []).map(this.render);
+        return renderLaunchArgs(first.args, this.render);
     }
-    /** Starts a whole-screen recording when the job wants video and ffmpeg is installed. */
+    /** Starts a whole-screen recording when the job wants video (ffmpeg is downloaded when missing). */
     async startRecording() {
         this.startedAt = Date.now();
         if (this.ctx.video === 'off')
             return;
-        const ffmpeg = findFfmpeg();
+        const ffmpeg = await ensureFfmpeg({ ...(this.ctx.paths ? { paths: this.ctx.paths } : {}), log: this.ctx.log });
         if (!ffmpeg)
             return;
+        this.startedAt = Date.now();
         const recorder = new ScreenRecorder(ffmpeg, this.platform);
         try {
             await recorder.start();
@@ -243,22 +245,21 @@ export class DesktopAppiumDriver {
         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 } : {}),
-        };
+        // While recording, the start time alone is kept: it is the step's place in the video.
+        const debug = offset !== undefined && this.recorder ? { video_offset_secs: offset } : {};
+        const start = this.appiumLogOffsets.get(index);
+        if ((result === 'failed' || result === 'blocked') && start !== undefined) {
+            const later = [...this.appiumLogOffsets.entries()].filter(([i]) => i > index).map(([, at]) => at);
+            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) {
+                debug.appium_log = appium.lines;
+                if (appium.dropped > 0)
+                    debug.dropped = { appium_log: appium.dropped };
+            }
+        }
+        return Object.keys(debug).length > 0 ? debug : undefined;
     }
     async stopRecording() {
         if (!this.recorder || this.videoStopped)

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

@@ -13,7 +13,7 @@ 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 { clip, errorMessage, expectWithin, firstLine, matches, render, renderLaunchArgs } 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';
@@ -26,9 +26,13 @@ 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;
+/** How long the paint wait pauses before checking a window whose page navigated again. */
+const PAINT_RETRY_MS = 100;
+/** How long after the paint a launch waits for its video's first frame (held-back frames come within about 0.5 s). */
+const FIRST_FRAME_WAIT_MS = 1_500;
 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;
+export 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. */
@@ -106,6 +110,65 @@ function freePort() {
         });
     });
 }
+/**
+ * Starts a recording's clock. A video starts with its first frame, not with its window: often a
+ * blank frame while the app's script loads, a frame Chromium held back until there was content, or,
+ * for a window that shows nothing new, the first change. That frame's time stamp comes from
+ * Playwright's screencast of the page, the stream its recorder writes; the listener stops after it.
+ */
+function recordingOf(page, video, log) {
+    const recording = { video, page, openedAt: Date.now(), startedAt: null, started: Promise.resolve(), endedAt: null };
+    recording.started = new Promise((resolve) => {
+        let settled = false;
+        let listener = Promise.resolve(null);
+        const settle = (at) => {
+            if (settled)
+                return;
+            settled = true;
+            if (at !== null)
+                recording.startedAt = at;
+            resolve();
+            void listener.then((started) => started?.dispose()).catch(() => undefined);
+        };
+        page.once('close', () => settle(null));
+        listener = Promise.resolve()
+            .then(() => page.screencast.start({ onFrame: ({ timestamp }) => settle(timestamp) }))
+            .catch((error) => {
+            // Without the time stamp, the window's opening is the earliest the video can start.
+            log.warn("the app window's video start could not be read; step offsets count from the window's opening", { error: firstLine(error) });
+            settle(recording.openedAt);
+            return null;
+        });
+    });
+    return recording;
+}
+/** The paint check, run in the window: settles once it is visible and has run two animation frames. */
+function paintCheck() {
+    return new Promise((resolve) => {
+        const tick = () => {
+            if (document.visibilityState === 'visible')
+                requestAnimationFrame(() => requestAnimationFrame(() => resolve(true)));
+            else
+                setTimeout(tick, 250);
+        };
+        tick();
+    });
+}
+/**
+ * Where a step starts in a recording, in seconds, or undefined when the recording does not show
+ * it: the step ended before the recording's first frame, or began after the recording ended. A
+ * step already running when the recording started (the one that relaunched the app) starts at 0.
+ */
+export function stepVideoOffset(recording, begun, ended) {
+    // No frame yet: a window that never painted records only a closing frame, which shows no step.
+    if (recording.startedAt === null)
+        return undefined;
+    if (recording.endedAt !== null && begun >= recording.endedAt)
+        return undefined;
+    if (ended !== null && ended <= recording.startedAt)
+        return undefined;
+    return Math.max(0, Math.round((begun - recording.startedAt) / 100) / 10);
+}
 export class ElectronPlaywrightDriver {
     ctx;
     options;
@@ -121,7 +184,10 @@ export class ElectronPlaywrightDriver {
     page = null;
     collector = null;
     videoDir = null;
-    videos = [];
+    /** The recordings of the app instances that started, oldest first; the last one is returned (see stopRecording). */
+    recordings = [];
+    /** When each step began (ms), in the order they ran. */
+    stepStarts = [];
     videoPath;
     videoStopped = false;
     /** The script's first action is `launch`: `launch()` already started the app with its args. */
@@ -195,7 +261,7 @@ export class ElectronPlaywrightDriver {
     async launch() {
         this.executable = await this.resolveExecutable();
         try {
-            this.display = await ensureDisplay();
+            this.display = await (this.options.display ?? ensureDisplay)();
         }
         catch (error) {
             throw new Blocked(errorMessage(error));
@@ -206,17 +272,26 @@ export class ElectronPlaywrightDriver {
             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));
+            args = renderLaunchArgs(first.args, (arg) => render(arg, this.ctx.template), RESERVED_ARG);
             this.firstLaunchDone = true;
         }
-        await this.start(args);
+        const started = await this.start(args);
+        // Times count from where the first window's video starts (the web driver counts from its page).
+        // No step has begun yet, so nothing was filed before this. While a window is recorded, a step
+        // that captured nothing is still reported, so debug can give it its place in the video.
+        this.collector = new DebugCollector(started, this.ctx.redact, () => this.recordings.length > 0);
+        for (const page of this.windows)
+            this.collector.attach(page);
     }
+    /**
+     * Starts the app and waits for its first window to paint, and for its video's first frame when
+     * it is recorded. Returns where that video starts (ms), or now when there is none.
+     */
     async start(args) {
         const executable = this.executable;
         if (!executable)
@@ -226,7 +301,7 @@ export class ElectronPlaywrightDriver {
         try {
             if (this.options.launchVia === 'cdp')
                 throw new Error('the DevTools-port launch was requested');
-            const electron = await _electron.launch({
+            const electron = await (this.options.electron ?? _electron).launch({
                 executablePath: executable,
                 args,
                 env,
@@ -235,7 +310,7 @@ export class ElectronPlaywrightDriver {
                 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 });
+            this.adopt({ via: 'playwright', electron, browser: null, context: electron.context(), process: electron.process(), recording: null, closed: false });
             electron.on('window', (page) => this.addWindow(page));
             for (const page of electron.windows())
                 this.addWindow(page);
@@ -259,6 +334,19 @@ export class ElectronPlaywrightDriver {
         this.page = page;
         await page.waitForLoadState('domcontentloaded', { timeout: LAUNCH_TIMEOUT_MS }).catch(() => undefined);
         await this.waitForPaint(page, 'launch');
+        const recording = this.instance?.recording;
+        if (!recording)
+            return Date.now();
+        this.recordings.push(recording);
+        // The first frame comes with the paint, or soon after it when Chromium held it back. A window
+        // that shows nothing new may send none until it changes: that frame still sets the video's
+        // start, only not the case clock, which cannot wait for it.
+        const timer = new AbortController();
+        const shown = await Promise.race([recording.started.then(() => true), sleep(FIRST_FRAME_WAIT_MS, false, { signal: timer.signal }).catch(() => false)]);
+        timer.abort();
+        if (!shown)
+            this.ctx.log.debug('no video frame yet after the app window painted; logged times may not match the video');
+        return recording.startedAt ?? Date.now();
     }
     /**
      * Waits until the window is visible and has painted (two animation frames). A loaded DOM is not
@@ -266,28 +354,81 @@ export class ElectronPlaywrightDriver {
      * 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.
+     *
+     * A page that navigates meanwhile (index.html redirecting to a login page, or a loading page the
+     * app replaces with loadURL) fails the check: Playwright rejects it when the old page's context
+     * goes, or, for a navigation the app starts from its main process, as soon as that navigation
+     * starts. Until the same deadline, the wait then pauses, waits for domcontentloaded and checks
+     * again, as the launch does for the first page. Right after the rejection Playwright can still
+     * report the old page's load state, and a check made before the new page commits can fail at
+     * once: the pause keeps the loop from spinning until it does.
      */
     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 limitMs = this.options.paintTimeoutMs ?? PAINT_TIMEOUT_MS;
         const timer = new AbortController();
-        const painted = await Promise.race([frames, sleep(PAINT_TIMEOUT_MS, false, { signal: timer.signal }).catch(() => false)]);
-        timer.abort();
+        const after = (ms, value) => sleep(ms, value, { signal: timer.signal }).catch(() => value);
+        // A check can outlive its window: one waiting for a new page's context never settles.
+        let gone = () => undefined;
+        const ended = new Promise((resolve) => {
+            gone = resolve;
+        });
+        const onClose = () => gone('closed');
+        const onCrash = () => gone('crashed');
+        page.once('close', onClose);
+        page.once('crash', onCrash);
+        const stop = Promise.race([after(limitMs, 'timeout'), ended]);
+        let outcome;
+        let checks = 0;
+        let navigated = false;
+        try {
+            for (;;) {
+                checks += 1;
+                const check = page.evaluate(paintCheck).then(() => 'painted', (error) => (error instanceof Error ? error : new Error(String(error))));
+                outcome = await Promise.race([check, stop]);
+                if (!(outcome instanceof Error))
+                    break;
+                if (page.isClosed()) {
+                    outcome = 'closed';
+                    break;
+                }
+                // Anything but a lost context (a crash, a script error in the window) fails every check alike.
+                if (!/Execution context was destroyed/.test(outcome.message))
+                    break;
+                navigated = true;
+                const paused = await Promise.race([after(PAINT_RETRY_MS, 'next'), stop]);
+                if (paused !== 'next') {
+                    outcome = paused;
+                    break;
+                }
+                const timeout = Math.max(1, started + limitMs - Date.now());
+                const loaded = await Promise.race([page.waitForLoadState('domcontentloaded', { timeout }).then(() => 'next', () => 'next'), stop]);
+                if (loaded !== 'next') {
+                    outcome = loaded;
+                    break;
+                }
+            }
+        }
+        finally {
+            timer.abort();
+            page.off('close', onClose);
+            page.off('crash', onCrash);
+        }
+        if (navigated)
+            this.ctx.log.debug(`the app window's page navigated before it painted after ${when}`, { checks });
         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}`);
+        if (outcome === 'painted') {
+            if (ms > 2_000)
+                this.ctx.log.warn(`the app window took ${ms} ms to paint after ${when}`);
+        }
+        else if (outcome === 'timeout')
+            this.ctx.log.warn(`the app window did not paint within ${Math.round(limitMs / 1000)} s after ${when}`);
+        else if (outcome === 'closed')
+            this.ctx.log.info(`the app window closed before it painted after ${when}`);
+        else if (outcome === 'crashed')
+            this.ctx.log.warn(`the app window crashed before it painted after ${when}`);
+        else
+            this.ctx.log.warn(`the app window's paint could not be checked after ${when}`, { error: firstLine(outcome) });
     }
     /** Fallback for apps whose fuses block Playwright's launch: spawn with a DevTools port and connect over CDP. */
     async startOverCdp(executable, args, env, cwd) {
@@ -306,7 +447,7 @@ export class ElectronPlaywrightDriver {
         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 };
+        const instance = { via: 'cdp', electron: null, browser: null, context: null, process: child, recording: null, closed: false };
         try {
             const endpoint = `http://127.0.0.1:${port}`;
             const deadline = Date.now() + LAUNCH_TIMEOUT_MS;
@@ -320,7 +461,8 @@ export class ElectronPlaywrightDriver {
                     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 connect = this.options.connectOverCDP ?? ((url, options) => chromium.connectOverCDP(url, options));
+            const browser = await connect(endpoint, { timeout: LAUNCH_TIMEOUT_MS });
             const context = browser.contexts()[0];
             if (!context)
                 throw new Error('the app exposes no browser context');
@@ -355,14 +497,15 @@ export class ElectronPlaywrightDriver {
         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') {
+        if (instance && !instance.recording && instance.via === 'playwright') {
             const video = page.video();
-            if (video) {
-                instance.video = video;
-                this.videos.push(video);
-            }
+            if (video)
+                instance.recording = recordingOf(page, video, this.ctx.log);
         }
         page.once('close', () => {
+            const recording = instance?.recording;
+            if (recording?.page === page)
+                recording.endedAt ??= Date.now();
             this.windows = this.windows.filter((p) => p !== page);
             if (this.page === page)
                 this.page = this.windows[0] ?? null;
@@ -377,7 +520,7 @@ export class ElectronPlaywrightDriver {
                 if (first && this.firstLaunchDone)
                     return {};
                 await this.closeInstance();
-                await this.start((action.args ?? []).map((arg) => render(arg, this.ctx.template)));
+                await this.start(renderLaunchArgs(action.args, (arg) => render(arg, this.ctx.template), RESERVED_ARG));
                 return {};
             }
             case 'terminate':
@@ -461,27 +604,47 @@ export class ElectronPlaywrightDriver {
         return this.requirePage().content();
     }
     beginStep(index) {
+        this.stepStarts.push({ index, at: Date.now() });
         this.collector?.begin(index);
     }
+    /**
+     * The step's capture, with its place in the video stopRecording returns; a step that video does
+     * not show has no offset, and one that also captured nothing has no debug at all. Entry times
+     * (`at_secs`) count from the first window's first paint.
+     */
     debug(index) {
-        return this.collector?.for(index);
+        const captured = this.collector?.for(index);
+        if (!captured)
+            return undefined;
+        const { video_offset_secs: _sinceFirstPaint, ...debug } = captured;
+        const offset = this.videoOffset(index);
+        if (offset !== undefined)
+            return { ...debug, video_offset_secs: offset };
+        return Object.keys(debug).length > 0 ? debug : undefined;
+    }
+    videoOffset(index) {
+        const recording = this.recordings.at(-1);
+        const i = this.stepStarts.findLastIndex((step) => step.index === index);
+        if (!recording || i < 0)
+            return undefined;
+        return stepVideoOffset(recording, this.stepStarts[i].at, this.stepStarts[i + 1]?.at ?? null);
     }
-    /** Closes the app (a video is only complete then) and returns the longest recording. */
+    /**
+     * Closes the app (a video is only complete then) and returns the last recording. A relaunch
+     * (`launch` again, or `terminate` then `launch`) records the new instance in a video of its own;
+     * the last one shows how the case ended, a failure included. Steps that ended before it began
+     * get no offset (see debug), and if it has no file no video is returned rather than one the
+     * offsets do not describe. A relaunch over the DevTools port records nothing, so the video before
+     * it is the last one.
+     */
     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;
+        const path = await this.recordings.at(-1)?.video.path().catch(() => undefined);
+        const size = path ? await stat(path).then((s) => s.size, () => 0) : 0;
+        this.videoPath = size > 0 ? path : undefined;
         if (!this.videoPath && this.videoDir) {
             await rm(this.videoDir, { recursive: true, force: true }).catch(() => undefined);
             this.videoDir = null;
@@ -510,6 +673,9 @@ export class ElectronPlaywrightDriver {
         if (!instance || instance.closed)
             return;
         instance.closed = true;
+        // Its video ends with it: a step that begins later is not in it.
+        if (instance.recording)
+            instance.recording.endedAt ??= Date.now();
         const pid = instance.process?.pid;
         const graceful = instance.electron
             ? instance.electron.close()
@@ -518,7 +684,10 @@ export class ElectronPlaywrightDriver {
                     await page.close({ runBeforeUnload: false }).catch(() => undefined);
                 await instance.browser?.close();
             })();
-        await Promise.race([graceful.catch(() => undefined), sleep(10_000)]);
+        // The timer is cancelled once the app has closed, so it does not keep the process alive.
+        const timer = new AbortController();
+        await Promise.race([graceful.catch(() => undefined), sleep(10_000, undefined, { signal: timer.signal }).catch(() => undefined)]);
+        timer.abort();
         killProcessTree(pid);
         await this.endLeftoverProcesses();
     }

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

@@ -11,6 +11,7 @@ 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 { ensureFfmpeg } from '../devices/ffmpeg.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';
@@ -242,6 +243,8 @@ export class IosAppiumDriver {
                     await recorder.start();
                 }
                 else {
+                    // Appium records a real device through ffmpeg on this Mac: fetch it when missing.
+                    await ensureFfmpeg({ paths: this.paths, log: this.ctx.log });
                     await client.startRecordingScreen({ timeLimit: RECORDING_LIMIT_SECS, videoType: 'h264', forceRestart: true });
                 }
                 this.recording = true;
@@ -427,16 +430,15 @@ export class IosAppiumDriver {
         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);
+        // While recording, the start time alone is kept: it is the step's place in the video.
         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;
+        return Object.keys(debug).length > 0 ? debug : undefined;
     }
     appiumLogFor(index) {
         const start = this.appiumLogOffsets.get(index);

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

@@ -4,7 +4,7 @@ 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 { clip, errorMessage, expectWithin, renderLaunchArgs } from './common.js';
 import { DesktopAppiumDriver, validateNativeAction } from './desktop-appium.js';
 import { Blocked, LaunchRefused, } from './driver.js';
 import { emptyScreen } from './snapshot/format.js';
@@ -200,7 +200,7 @@ export class Mac2AppiumDriver extends DesktopAppiumDriver {
         try {
             switch (action.type) {
                 case 'launch':
-                    await this.start((action.args ?? []).map(this.render));
+                    await this.start(renderLaunchArgs(action.args, this.render));
                     return {};
                 case 'terminate':
                     await macos(this.requireClient(), 'terminateApp', { bundleId: this.bundleId });