@leera.io/qa-runner 1.1.0 → 1.4.0

package/dist/src/devices/screen-record.js

@@ -3,66 +3,139 @@ import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { findOnPath } from './desktop.js';
+import { ensureFfmpeg } from './ffmpeg.js';
 /**
- * Whole-screen video for native desktop jobs (contracts §M): only when ffmpeg is installed —
- * `avfoundation` on macOS (needs Screen Recording permission for the runner), `gdigrab` on
- * Windows. Without ffmpeg jobs record no video.
+ * H.264 at the capture rate, at most 1920 px wide (a Retina screen is scaled down), both sides even.
+ * The output rate must be set: macOS screen capture reports 1,000,000 fps, and ffmpeg would
+ * duplicate frames to match, growing the file by megabytes a second and never getting to `q`.
+ * veryfast at CRF 28 keeps a mostly still screen near 1 MB a minute for about the CPU of ultrafast.
  */
-export function findFfmpeg(env = process.env, platform = process.platform, exists) {
-    return findOnPath(platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg', env, exists);
+function encodeArgv(framerate) {
+    return ['-r', String(framerate), '-vf', "scale='trunc(min(1920,iw)/2)*2':-2", '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '28', '-pix_fmt', 'yuv420p', '-movflags', '+faststart'];
 }
-const ENCODE = ['-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2', '-c:v', 'libx264', '-preset', 'ultrafast', '-pix_fmt', 'yuv420p', '-movflags', '+faststart'];
-/** The fixed ffmpeg argv that records the main screen into `file` (an .mp4). */
-export function screenRecordArgv(file, os, framerate = 10) {
+/**
+ * Progress reports on stdout, key=value lines that end in `progress=…`, ten a second. ffmpeg
+ * reports nothing until its output has started, so the first report tells when the first frame
+ * was captured (see ScreenRecorder.startedAt); at the default period, 0.5 s, it could come half a
+ * second after it.
+ */
+const PROGRESS_ARGV = ['-progress', 'pipe:1', '-stats_period', '0.1'];
+/** An X display name: `:99`, `:0.0`, `host:10.0`. */
+const X_DISPLAY = /^[A-Za-z0-9.-]*:\d{1,5}(?:\.\d{1,3})?$/;
+/** The fixed ffmpeg argv that records the main screen (on Linux, the X `display`) into `file` (an .mp4). */
+export function screenRecordArgv(file, os, framerate = 10, display) {
     if (!file.endsWith('.mp4'))
         throw new Error('the recording file must end in .mp4');
     if (!Number.isInteger(framerate) || framerate < 1 || framerate > 30)
         throw new Error(`invalid frame rate ${framerate}`);
-    const input = os === 'macos'
-        ? ['-f', 'avfoundation', '-capture_cursor', '1', '-framerate', String(framerate), '-i', 'Capture screen 0:none']
-        : ['-f', 'gdigrab', '-draw_mouse', '1', '-framerate', String(framerate), '-i', 'desktop'];
-    return ['-hide_banner', '-loglevel', 'error', '-y', ...input, ...ENCODE, file];
+    let input;
+    if (os === 'macos')
+        input = ['-f', 'avfoundation', '-capture_cursor', '1', '-framerate', String(framerate), '-i', 'Capture screen 0:none'];
+    else if (os === 'windows')
+        input = ['-f', 'gdigrab', '-draw_mouse', '1', '-framerate', String(framerate), '-i', 'desktop'];
+    else {
+        if (!display || !X_DISPLAY.test(display))
+            throw new Error(`invalid X display ${JSON.stringify(display ?? '')}`);
+        input = ['-f', 'x11grab', '-draw_mouse', '1', '-framerate', String(framerate), '-i', display];
+    }
+    return ['-hide_banner', '-loglevel', 'error', '-y', ...PROGRESS_ARGV, ...input, ...encodeArgv(framerate), file];
 }
-/** One ffmpeg screen recording; `stop()` asks ffmpeg to finish (`q`) so the mp4 is complete. */
+/** `argv` for an ffmpeg without `-stats_period` (Ubuntu 20.04 ships 4.2): it reports every 0.5 s. */
+function withoutStatsPeriod(argv) {
+    const at = argv.indexOf('-stats_period');
+    return at < 0 ? argv : [...argv.slice(0, at), ...argv.slice(at + 2)];
+}
+/** How long start() waits for the first frame: on a busy machine ffmpeg can take seconds to start. */
+export const FIRST_FRAME_TIMEOUT_MS = 10_000;
+/**
+ * One ffmpeg screen recording; `stop()` asks ffmpeg to finish (`q`) so the mp4 is complete.
+ * `startedAt` and `endedAt` place the video in time, so a step's offset in it counts from its
+ * first frame rather than from when ffmpeg was started (see stepVideoOffset).
+ */
 export class ScreenRecorder {
     ffmpeg;
     os;
-    spawnImpl;
+    options;
     child = null;
+    /** Counts ffmpeg starts; events from an earlier one are ignored. */
+    runs = 0;
     exited = false;
     stderr = '';
+    progress = '';
+    firstFrameAt = null;
+    endAt = null;
     dir;
     file;
-    constructor(ffmpeg, os, spawnImpl = spawn) {
+    constructor(ffmpeg, os, options = {}) {
         this.ffmpeg = ffmpeg;
         this.os = os;
-        this.spawnImpl = spawnImpl;
+        this.options = options;
         this.dir = mkdtempSync(join(tmpdir(), 'qa-video-'));
         this.file = join(this.dir, 'video.mp4');
     }
-    /** Starts ffmpeg and waits briefly: an immediate exit (no permission, no device) throws. */
-    async start(settleMs = 1_500) {
-        const child = this.spawnImpl(this.ffmpeg, screenRecordArgv(this.file, this.os), { stdio: ['pipe', 'ignore', 'pipe'], windowsHide: true });
+    /** When the video's first frame was captured (ms), its time 0; null until ffmpeg reports it (about 0.1 s later). */
+    get startedAt() {
+        return this.firstFrameAt;
+    }
+    /** When the video ended (ms): ffmpeg was asked to stop, or exited; null while it records. */
+    get endedAt() {
+        return this.endAt;
+    }
+    /**
+     * Starts ffmpeg and waits for the first frame, so the video shows what the job does next. An
+     * exit before it (no permission, no device) throws. A first frame later than `timeoutMs` does
+     * not: the job goes on, and the video starts when the frame comes (startedAt).
+     */
+    async start(timeoutMs = FIRST_FRAME_TIMEOUT_MS) {
+        const argv = screenRecordArgv(this.file, this.os, 10, this.options.display);
+        await this.run(argv, timeoutMs);
+        if (this.stoppedAtOnce() && this.stderr.includes('stats_period'))
+            await this.run(withoutStatsPeriod(argv), timeoutMs);
+        if (this.stoppedAtOnce()) {
+            this.cleanup();
+            throw new Error(`ffmpeg stopped recording at once: ${this.stderr.trim().split('\n').pop() ?? 'no output'}`);
+        }
+    }
+    stoppedAtOnce() {
+        return this.exited && this.firstFrameAt === null;
+    }
+    /** Starts ffmpeg with `argv` and waits for its first frame, its exit or `timeoutMs`. */
+    async run(argv, timeoutMs) {
+        const run = ++this.runs;
+        const current = () => run === this.runs;
+        this.exited = false;
+        this.endAt = null;
+        this.stderr = '';
+        this.progress = '';
+        const child = (this.options.spawn ?? spawn)(this.ffmpeg, argv, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
         this.child = child;
+        // Read to the end: ffmpeg must never block on a full pipe.
+        child.stdout?.on('data', (chunk) => {
+            if (!current() || this.firstFrameAt !== null)
+                return;
+            this.progress = `${this.progress}${chunk.toString('utf8')}`.slice(-2_000);
+            if (/^progress=continue/m.test(this.progress))
+                this.firstFrameAt = Date.now();
+        });
         child.stderr?.on('data', (chunk) => {
-            this.stderr = `${this.stderr}${chunk.toString('utf8')}`.slice(-2_000);
+            if (current())
+                this.stderr = `${this.stderr}${chunk.toString('utf8')}`.slice(-2_000);
         });
         child.once('exit', () => {
+            if (!current())
+                return;
             this.exited = true;
+            this.endAt ??= Date.now();
         });
         child.once('error', (error) => {
+            if (!current())
+                return;
             this.exited = true;
             this.stderr += error.message;
         });
-        const deadline = Date.now() + settleMs;
-        while (Date.now() < deadline) {
-            if (this.exited) {
-                this.cleanup();
-                throw new Error(`ffmpeg stopped recording at once: ${this.stderr.trim().split('\n').pop() ?? 'no output'}`);
-            }
-            await sleep(100);
-        }
+        const deadline = Date.now() + timeoutMs;
+        while (this.firstFrameAt === null && !this.exited && Date.now() < deadline)
+            await sleep(50);
     }
     /** Stops the recording; returns the mp4 path, or undefined when nothing usable was written. */
     async stop(timeoutMs = 15_000) {
@@ -70,6 +143,8 @@ export class ScreenRecorder {
         this.child = null;
         if (!child)
             return undefined;
+        // The video ends about here: ffmpeg records on until it reads the `q`.
+        this.endAt ??= Date.now();
         if (!this.exited) {
             const done = new Promise((resolve) => child.once('exit', () => resolve()));
             try {
@@ -84,6 +159,11 @@ export class ScreenRecorder {
                 child.kill();
                 await Promise.race([done, sleep(2_000)]);
             }
+            // An ffmpeg stuck in a capture call can ignore SIGTERM; never leave it running.
+            if (!this.exited) {
+                child.kill('SIGKILL');
+                await Promise.race([done, sleep(2_000)]);
+            }
         }
         if (existsSync(this.file) && statSync(this.file).size > 0)
             return this.file;
@@ -93,3 +173,10 @@ export class ScreenRecorder {
         rmSync(this.dir, { recursive: true, force: true });
     }
 }
+/** ScreenRecorder with the ffmpeg on PATH or in the runner home (downloaded now when missing). */
+export function ffmpegRecorder(paths, log) {
+    return async (os, display) => {
+        const ffmpeg = await ensureFfmpeg({ paths, log });
+        return ffmpeg ? new ScreenRecorder(ffmpeg, os, display ? { display } : {}) : null;
+    };
+}

package/dist/src/devices/tauri.js

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { readJsonFile } from '../home.js';
 import { displayNeed, findOnPath, NO_DISPLAY, XVFB_DISPLAY } from './desktop.js';
+import { ffmpegCheckDetail } from './ffmpeg.js';
 /**
  * Where Tauri jobs run (contracts §L): `tauri-driver` 2.0.6 with the platform's native
  * WebDriver (WebKitWebDriver on Linux, msedgedriver on Windows), or on macOS an app build that
@@ -151,6 +152,8 @@ export function tauriChecks(settings, options = {}) {
                 detail: 'macOS has no tauri-driver; this Mac runs Tauri jobs only for builds that embed the WebDriver plugin',
                 fix: 'leera-qa-runner config set tauri.macos_plugin true (only when your builds embed the plugin)',
             });
+        if (settings.macosPlugin)
+            checks.push(videoCheck(env, platform, ' (needs Screen Recording permission)'));
         return checks;
     }
     if (platform !== 'linux' && platform !== 'win32') {
@@ -185,5 +188,13 @@ export function tauriChecks(settings, options = {}) {
                 fix: `download the msedgedriver matching your WebView2 Runtime from ${MSEDGEDRIVER_URL}, then leera-qa-runner config set tauri.native_driver_path C:\\path\\to\\msedgedriver.exe`,
             });
     }
+    checks.push(videoCheck(env, platform));
     return checks;
 }
+/** Tauri video: ffmpeg on PATH or downloaded, or downloadable on the first job with video. */
+function videoCheck(env, platform, note = '') {
+    const video = ffmpegCheckDetail(env, platform);
+    return video.ok
+        ? { id: 'tauri.video', title: 'Tauri: video', status: 'ok', detail: `${video.detail}${note}` }
+        : { id: 'tauri.video', title: 'Tauri: video', status: 'warn', detail: video.detail, fix: 'install ffmpeg on the PATH' };
+}

package/dist/src/devices/windows.js

@@ -12,7 +12,7 @@ import { ExitCode, messageOf } from '../errors.js';
 import { ensureHome, readJsonFile } from '../home.js';
 import { runTool } from './android/adb.js';
 import { findOnPath } from './desktop.js';
-import { findFfmpeg } from './screen-record.js';
+import { ffmpegCheckDetail } from './ffmpeg.js';
 /**
  * Native Windows apps (contracts §M): Appium's Windows driver in front of WinAppDriver 1.2.1,
  * which the runner starts itself on a free loopback port. WinAppDriver needs Developer Mode and
@@ -255,10 +255,10 @@ export async function windowsChecks(env, paths, platform = process.platform) {
     checks.push((await developerModeOn())
         ? { id: 'windows.developer_mode', title: 'Windows apps: Developer Mode', status: 'ok', detail: 'on' }
         : { id: 'windows.developer_mode', title: 'Windows apps: Developer Mode', status: 'fail', detail: 'off (WinAppDriver needs it)', fix: DEVELOPER_MODE_STEPS });
-    const ffmpeg = findFfmpeg(env, platform);
-    checks.push(ffmpeg
-        ? { id: 'windows.video', title: 'Windows apps: video', status: 'ok', detail: `ffmpeg ${ffmpeg}` }
-        : { id: 'windows.video', title: 'Windows apps: video', status: 'warn', detail: 'ffmpeg is not installed; jobs record no video', fix: 'winget install ffmpeg' });
+    const video = ffmpegCheckDetail(env, platform);
+    checks.push(video.ok
+        ? { id: 'windows.video', title: 'Windows apps: video', status: 'ok', detail: video.detail }
+        : { id: 'windows.video', title: 'Windows apps: video', status: 'warn', detail: video.detail, fix: 'winget install ffmpeg' });
     return checks;
 }
 export async function sha256File(path) {
@@ -355,8 +355,7 @@ export async function setupWindows(io, paths, options = {}, deps = {}) {
         io.stdout('Developer Mode: on');
     }
     io.stdout('Windows app jobs need an interactive desktop: run the runner in a logged-in session (not as a Windows service without a desktop) and keep the screen unlocked.');
-    if (!findFfmpeg(io.env, io.platform))
-        io.stdout('ffmpeg is not installed: Windows app jobs record no video.');
+    io.stdout(`Video: ${ffmpegCheckDetail(io.env, io.platform).detail}.`);
     io.stdout(ok ? 'Windows apps are set up. Check with `leera-qa-runner doctor --platform windows`.' : 'Windows setup is incomplete; see the messages above.');
     return ok ? ExitCode.ok : ExitCode.environmentNotReady;
 }

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

@@ -1,18 +1,19 @@
 import { mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { delimiter, 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 { Adb, DEVICE_DOWNLOADS, resolveAndroidSdk } from '../devices/android/adb.js';
 import { waitForDeviceBack } from '../devices/android/emulator.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 { ensureFfmpeg, managedFfmpegDir } from '../devices/ffmpeg.js';
 import { homePaths, readJsonFile } from '../home.js';
-import { renderTemplate } from '../template.js';
+import { renderTemplate, resolveFileEntries } 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';
@@ -75,12 +76,18 @@ 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) {
+export function appiumEnv(env, sdk, ffmpegDir) {
     const out = { ...env };
     if (sdk?.root) {
         out.ANDROID_HOME = sdk.root;
         out.ANDROID_SDK_ROOT = sdk.root;
     }
+    // Appium finds ffmpeg on PATH (joining Android recordings, real iPhones): after one already
+    // there, the one the runner downloads. (Windows spells the key Path.)
+    if (ffmpegDir) {
+        const key = Object.keys(out).find((name) => name.toUpperCase() === 'PATH') ?? 'PATH';
+        out[key] = out[key] ? `${out[key]}${delimiter}${ffmpegDir}` : ffmpegDir;
+    }
     return out;
 }
 let processAppium = null;
@@ -89,7 +96,7 @@ export function sharedAppiumServer(paths, sdk) {
     processAppium ??= new AppiumServer({
         home: appiumHomeDir(paths),
         logFile: join(paths.logs, 'appium.log'),
-        env: appiumEnv(process.env, sdk),
+        env: appiumEnv(process.env, sdk, managedFfmpegDir(paths)),
     });
     return processAppium;
 }
@@ -245,6 +252,8 @@ export class AndroidAppiumDriver {
         this.logcat = new LogcatSink(this.adb, serial, app.id, this.ctx.redact);
         this.logcat.start();
         if (this.ctx.video !== 'off') {
+            // Appium records in 3-minute parts and joins them with ffmpeg: fetch it when missing.
+            await ensureFfmpeg({ paths: this.paths, log: this.ctx.log });
             try {
                 await this.client.startRecordingScreen({
                     timeLimit: RECORDING_LIMIT_SECS,
@@ -291,6 +300,10 @@ export class AndroidAppiumDriver {
         return { ...rest, fallbacks: [...(rest.fallbacks ?? []), { xpath }] };
     }
     async run(action) {
+        if (action.type === 'add_files') {
+            await this.addFiles(action);
+            return {};
+        }
         const prepared = action.target ? { ...action, target: AndroidAppiumDriver.resolveRefTarget(action.target) } : action;
         if (this.dialogCheckPending) {
             this.dialogCheckPending = false;
@@ -312,6 +325,29 @@ export class AndroidAppiumDriver {
             throw this.translate(error);
         }
     }
+    /**
+     * `add_files`: copies the files into the device's Download folder, where the system file picker
+     * lists them, and asks the device to index them for photo pickers. The script then taps through
+     * the app's picker.
+     */
+    async addFiles(action) {
+        const files = resolveFileEntries(action.files, this.ctx.template);
+        const adb = this.adb;
+        const serial = this.lease?.serial;
+        if (!adb || !serial)
+            throw new Blocked('the device is not connected');
+        for (const file of files) {
+            const remote = `${DEVICE_DOWNLOADS}/${file.file.file_name}`;
+            try {
+                await adb.push(serial, file.path, remote);
+            }
+            catch (error) {
+                throw new Blocked(`test file ${file.name} could not be copied to ${serial}: ${webdriverMessage(error)}`);
+            }
+            // The media index is best effort: file pickers read the folder itself.
+            await adb.scanMedia(serial, remote).catch(() => undefined);
+        }
+    }
     /**
      * 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

package/dist/src/drivers/common.js

@@ -100,3 +100,26 @@ export function firstLine(error) {
 export function clip(text) {
     return text.length > 120 ? `${text.slice(0, 117)}...` : text;
 }
+/**
+ * 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 (in Electron, the one that relaunched the app)
+ * starts at 0.
+ */
+export function stepVideoOffset(recording, begun, ended) {
+    // No frame yet: it shows no step (an Electron window that never painted records only a closing frame).
+    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);
+}
+/** Where step `index` starts in `recording` (see stepVideoOffset): it ran until the next step began. */
+export function stepStartOffset(recording, starts, index) {
+    const i = starts.findLastIndex((step) => step.index === index);
+    if (i < 0)
+        return undefined;
+    return stepVideoOffset(recording, starts[i].at, starts[i + 1]?.at ?? null);
+}

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

@@ -2,11 +2,11 @@ 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 { ffmpegRecorder } from '../devices/screen-record.js';
 import { homePaths } from '../home.js';
-import { renderTemplate } from '../template.js';
+import { renderTemplate, resolveFileEntries } from '../template.js';
 import { APPIUM_LOG_MAX_BYTES, appiumLogLines, LOCAL_PATHS_REFUSED } from './android-appium.js';
-import { errorMessage, renderLaunchArgs } from './common.js';
+import { errorMessage, renderLaunchArgs, stepStartOffset } 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';
@@ -61,6 +61,7 @@ export function validateNativeAction(platform, action) {
 export class DesktopAppiumDriver {
     ctx;
     appium;
+    makeRecorder;
     client = null;
     unpacked = null;
     releaseBuild = null;
@@ -70,12 +71,15 @@ export class DesktopAppiumDriver {
     firstLaunchDone = false;
     actionsRun = 0;
     lastRefs = {};
-    startedAt = Date.now();
-    offsets = new Map();
+    /** When each step began (ms), in the order they ran; offsets count from the video's first frame. */
+    stepStarts = [];
     appiumLogOffsets = new Map();
-    constructor(ctx, appium) {
+    constructor(ctx, appium, 
+    /** A whole-screen recorder, or null when there is no ffmpeg (default: ffmpegRecorder). */
+    makeRecorder) {
         this.ctx = ctx;
         this.appium = appium;
+        this.makeRecorder = makeRecorder;
     }
     get paths() {
         return this.ctx.paths ?? homePaths(process.env);
@@ -150,15 +154,13 @@ export class DesktopAppiumDriver {
         this.firstLaunchDone = true;
         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();
-        if (!ffmpeg)
+        const recorder = await (this.makeRecorder ?? ffmpegRecorder(this.paths, this.ctx.log))(this.platform, undefined);
+        if (!recorder)
             return;
-        const recorder = new ScreenRecorder(ffmpeg, this.platform);
         try {
             await recorder.start();
             this.recorder = recorder;
@@ -180,6 +182,23 @@ export class DesktopAppiumDriver {
         const prepared = action.target ? { ...action, target: resolveNativeRef(action.target) } : action;
         return runNativeAction(this.actionContext(), prepared);
     }
+    /**
+     * `upload {target, files}`: clicks the target, which must open the system Open dialog, and picks
+     * the files there. An Open dialog picks from one folder, so the files are first gathered into a
+     * fresh folder of their own; the platform then points the dialog at it.
+     */
+    async upload(action) {
+        const files = resolveFileEntries(action.files, this.ctx.template);
+        const store = this.ctx.files;
+        if (!store)
+            throw new Blocked('the runner prepared no test files for this job');
+        const folder = store.folderWith(files.map((file) => file.path));
+        const timeout = action.timeout_ms ?? this.ctx.timeouts.actionMs;
+        if (!action.target)
+            throw new Error("'upload' needs a target");
+        await this.runShared({ type: 'click', target: action.target, timeout_ms: timeout });
+        await this.pickInOpenDialog(folder, files.map((file) => file.file.file_name), timeout);
+    }
     /** Whether this action is the leading `launch` whose args the first start already used. */
     skipFirstLaunch(action) {
         const first = this.actionsRun === 0;
@@ -239,13 +258,13 @@ export class DesktopAppiumDriver {
         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.stepStarts.push({ index, at: Date.now() });
         this.appiumLogOffsets.set(index, this.appium.logOffset());
     }
     debug(index, result) {
-        const offset = this.offsets.get(index);
+        const offset = this.recorder ? stepStartOffset(this.recorder, this.stepStarts, index) : undefined;
         // 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 debug = offset !== undefined ? { 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);

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

@@ -13,10 +13,11 @@ 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, renderLaunchArgs } from './common.js';
+import { clip, errorMessage, expectWithin, firstLine, matches, render, renderLaunchArgs, stepStartOffset } 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';
+import { resolveFileEntries } from '../template.js';
+import { fileInputOf, findOnPage, locateAction, NO_FFMPEG_VIDEO, playwrightFfmpeg, runWebAction, uploadFiles, 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'];
@@ -142,6 +143,47 @@ function recordingOf(page, video, log) {
     });
     return recording;
 }
+/**
+ * Runs in the app's main process: the next Open dialog answers with `paths` instead of opening,
+ * once, then the real dialog is back. Self-contained, since Playwright sends its source.
+ */
+export function answerOpenDialog(electron, paths) {
+    const { dialog } = electron;
+    const holder = globalThis;
+    holder.__qaOpenDialog ??= {
+        showOpenDialog: dialog.showOpenDialog,
+        showOpenDialogSync: dialog.showOpenDialogSync,
+        answered: false,
+    };
+    const state = holder.__qaOpenDialog;
+    state.answered = false;
+    const restore = () => {
+        dialog.showOpenDialog = state.showOpenDialog;
+        dialog.showOpenDialogSync = state.showOpenDialogSync;
+    };
+    dialog.showOpenDialog = async () => {
+        state.answered = true;
+        restore();
+        return { canceled: false, filePaths: paths };
+    };
+    dialog.showOpenDialogSync = () => {
+        state.answered = true;
+        restore();
+        return paths;
+    };
+}
+/** Runs in the main process: whether the swapped dialog answered. */
+export function openDialogAnswered() {
+    return globalThis.__qaOpenDialog?.answered === true;
+}
+/** Runs in the main process: puts the real Open dialog back. */
+export function restoreOpenDialog(electron) {
+    const state = globalThis.__qaOpenDialog;
+    if (!state)
+        return;
+    electron.dialog.showOpenDialog = state.showOpenDialog;
+    electron.dialog.showOpenDialogSync = state.showOpenDialogSync;
+}
 /** The paint check, run in the window: settles once it is visible and has run two animation frames. */
 function paintCheck() {
     return new Promise((resolve) => {
@@ -154,21 +196,6 @@ function paintCheck() {
         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;
@@ -529,10 +556,54 @@ export class ElectronPlaywrightDriver {
             case 'focus_window':
                 await this.focusWindow(action);
                 return {};
+            case 'upload':
+                await this.upload(action);
+                return {};
             default:
                 return runWebAction(this.requirePage(), action, this.ctx.template, this.ctx.timeouts.actionMs);
         }
     }
+    /**
+     * `upload` as on the web, and also through the app's own Open dialog: before the click, the main
+     * process's `dialog.showOpenDialog` and `showOpenDialogSync` are swapped for ones that answer with
+     * the files, then put back. Apps started over CDP have no main process to reach, so they only get
+     * the web way.
+     */
+    async upload(action) {
+        const page = this.requirePage();
+        const timeout = action.timeout_ms ?? this.ctx.timeouts.actionMs;
+        const paths = resolveFileEntries(action.files, this.ctx.template).map((file) => file.path);
+        const locator = await locateAction(page, action, this.ctx.template, timeout);
+        const electron = this.instance?.electron ?? null;
+        if (!electron || (await fileInputOf(locator, timeout)).input) {
+            await uploadFiles(page, locator, paths, timeout);
+            return;
+        }
+        await electron.evaluate(answerOpenDialog, paths);
+        try {
+            const chooser = page.waitForEvent('filechooser', { timeout }).catch(() => null);
+            await locator.click({ timeout });
+            const deadline = Date.now() + timeout;
+            for (;;) {
+                if (await electron.evaluate(openDialogAnswered).catch(() => false))
+                    return;
+                const opened = await Promise.race([chooser, sleep(200).then(() => undefined)]);
+                if (opened) {
+                    if (paths.length > 1 && !opened.isMultiple()) {
+                        throw new Error(`the file input takes one file, but the action hands over ${paths.length}`);
+                    }
+                    await opened.setFiles(paths, { timeout });
+                    return;
+                }
+                if (opened === null || Date.now() > deadline)
+                    break;
+            }
+            throw new Error("clicking the element opened neither a file chooser nor the app's Open dialog; target the <input type=file> or the button that opens the dialog");
+        }
+        finally {
+            await electron.evaluate(restoreOpenDialog).catch(() => undefined);
+        }
+    }
     async focusWindow(action) {
         if (!this.instance)
             throw new Error('the app is not running; start it with launch');
@@ -624,10 +695,7 @@ export class ElectronPlaywrightDriver {
     }
     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);
+        return recording ? stepStartOffset(recording, this.stepStarts, index) : undefined;
     }
     /**
      * Closes the app (a video is only complete then) and returns the last recording. A relaunch