@leera.io/qa-runner 1.2.0 → 1.4.0

package/dist/src/builds/download.js

@@ -11,9 +11,10 @@ export class BuildIntegrityError extends Error {
  */
 export async function obtainBuild(options) {
     const { cache, build } = options;
+    const what = options.what ?? `build ${build.id}`;
     const expected = build.sha256.toLowerCase();
     if (!SHA256_RE.test(expected))
-        throw new BuildIntegrityError(`build ${build.id} has no valid sha256`);
+        throw new BuildIntegrityError(`${what} has no valid sha256`);
     const release = cache.pin(expected);
     try {
         const cached = cache.get(expected);
@@ -21,11 +22,11 @@ export async function obtainBuild(options) {
             return { path: cached, sha256: expected, fromCache: true, release };
         const info = await options.getUrl();
         if (info.sha256.toLowerCase() !== expected) {
-            throw new BuildIntegrityError(`the server offered build ${build.id} with digest ${info.sha256}, not ${expected}`);
+            throw new BuildIntegrityError(`the server offered ${what} with digest ${info.sha256}, not ${expected}`);
         }
         const url = new URL(info.url);
         if (url.protocol !== 'https:' && url.protocol !== 'http:')
-            throw new Error(`refusing to download a build from ${url.protocol} URL`);
+            throw new Error(`refusing to download ${what} from a ${url.protocol} URL`);
         const temp = cache.tempPath(info.file_name);
         try {
             const response = await (options.fetchImpl ?? fetch)(url, {
@@ -33,22 +34,22 @@ export async function obtainBuild(options) {
                 signal: AbortSignal.timeout(options.timeoutMs ?? 30 * 60_000),
             });
             if (!response.ok || !response.body)
-                throw new Error(`the build download failed with HTTP ${response.status}`);
+                throw new Error(`the download of ${what} failed with HTTP ${response.status}`);
             const hash = createHash('sha256');
             let received = 0;
             const limit = info.size_bytes;
             await writeResponseBody(response.body, temp, (chunk) => {
                 received += chunk.length;
                 if (received > limit)
-                    throw new BuildIntegrityError(`the build download is larger than the expected ${limit} bytes`);
+                    throw new BuildIntegrityError(`the download of ${what} is larger than the expected ${limit} bytes`);
                 hash.update(chunk);
                 options.onProgress?.(received, limit);
             });
             if (received !== limit)
-                throw new BuildIntegrityError(`the build download has ${received} bytes, expected ${limit}`);
+                throw new BuildIntegrityError(`the download of ${what} has ${received} bytes, expected ${limit}`);
             const digest = hash.digest('hex');
             if (digest !== expected)
-                throw new BuildIntegrityError(`the downloaded build's sha256 ${digest} does not match ${expected}`);
+                throw new BuildIntegrityError(`the sha256 ${digest} of the downloaded ${what} does not match ${expected}`);
             const path = cache.put(expected, info.file_name || build.file_name, temp);
             cache.prune();
             return { path, sha256: expected, fromCache: false, release };

package/dist/src/capabilities.js

@@ -60,6 +60,8 @@ export function deriveLabels(devices) {
  * (contracts §Q); the server gives such scripts only to runners labelled `data-refs`.
  * `credential_otp` = this runner types the account's fixed one-time code (`{{credential.otp}}`);
  * the server gives such scripts only to runners labelled `credential-otp`.
+ * `test_files` = this runner downloads or generates a job's test files and hands them to the app
+ * (contracts §S); the server gives such scripts only to runners labelled `test-files`.
  */
 export function featuresFor(platforms, options = {}) {
     const features = [];
@@ -79,7 +81,7 @@ export function featuresFor(platforms, options = {}) {
     if (options.ffmpeg && platforms.some((platform) => platform === 'tauri' || platform === 'macos' || platform === 'windows') && !features.includes('video_mp4')) {
         features.push('video_mp4');
     }
-    features.push('data_refs', 'credential_otp');
+    features.push('data_refs', 'credential_otp', 'test_files');
     return features;
 }
 export function buildCapabilities(devices, host, extraTools = {}, options = { ffmpeg: ffmpegAvailable() }) {

package/dist/src/client.js

@@ -110,6 +110,10 @@ export class RunnerClient {
             ...(owner.jobId !== undefined ? { job_id: owner.jobId } : { session_id: owner.sessionId }),
         }));
     }
+    /** A short-lived download URL for a stored test file of a running job (contracts §S). */
+    async testFileDownloadUrl(testFileId, jobId) {
+        return this.expect(await this.json('/api/v1/qa/runner/files/download-url', { test_file_id: testFileId, job_id: jobId }));
+    }
     json(path, body) {
         return this.request(path, {
             method: 'POST',

package/dist/src/devices/android/adb.js

@@ -245,6 +245,14 @@ export class Adb {
     async pidof(serial, pkg) {
         return parsePidof(await this.shell(serial, ['pidof', assertPackage(pkg)], 10_000).catch(() => ''));
     }
+    /** Copies a file of this machine to the device (no shell: the remote path is one argv item). */
+    async push(serial, local, remote, timeoutMs = 300_000) {
+        await this.run(['-s', assertSerial(serial), 'push', local, remote], timeoutMs);
+    }
+    /** Asks the device to add a file it holds to its media index, so photo pickers list it. */
+    async scanMedia(serial, remote) {
+        await this.shell(serial, mediaScanArgs(remote), 15_000);
+    }
     /** Drops adb's connection to a device so it reconnects (the fix for one stuck `offline`). */
     async reconnect(serial) {
         await this.run(['-s', assertSerial(serial), 'reconnect'], 15_000).catch(() => undefined);
@@ -253,3 +261,17 @@ export class Adb {
         await this.run(['-s', assertSerial(serial), 'emu', 'kill'], 15_000).catch(() => undefined);
     }
 }
+/** The Download folder on the device, where the system file picker finds added files. */
+export const DEVICE_DOWNLOADS = '/sdcard/Download';
+/** Quotes one word for the device's shell. */
+export function deviceShellQuote(text) {
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * `am broadcast` of MEDIA_SCANNER_SCAN_FILE for a file on the device; the file URI is
+ * percent-encoded and quoted, since `adb shell` hands its words to the device's shell.
+ */
+export function mediaScanArgs(remote) {
+    const uri = `file://${encodeURI(remote)}`;
+    return ['am', 'broadcast', '-a', 'android.intent.action.MEDIA_SCANNER_SCAN_FILE', '-d', deviceShellQuote(uri)];
+}

package/dist/src/devices/ios/simctl.js

@@ -53,6 +53,21 @@ export function simctlBootstatusArgv(udid) {
 export function simctlShutdownArgv(udid) {
     return ['simctl', 'shutdown', assertSimUdid(udid)];
 }
+/** Adds photos and videos to the simulator's Photos library. */
+export function simctlAddMediaArgv(udid, paths) {
+    return ['simctl', 'addmedia', assertSimUdid(udid), ...paths];
+}
+/** The app's data container on the simulator (its `Documents` folder is inside). */
+export function simctlDataContainerArgv(udid, bundleId) {
+    return ['simctl', 'get_app_container', assertSimUdid(udid), assertBundleId(bundleId), 'data'];
+}
+/** File types `simctl addmedia` puts into the Photos library. */
+export const SIMULATOR_MEDIA_EXTENSIONS = ['jpg', 'jpeg', 'png', 'heic', 'gif', 'mp4', 'mov', 'm4v'];
+/** Whether a file goes to the Photos library (by its extension). */
+export function isSimulatorMedia(fileName) {
+    const ext = fileName.toLowerCase().split('.').pop() ?? '';
+    return fileName.includes('.') && SIMULATOR_MEDIA_EXTENSIONS.includes(ext);
+}
 /** An executable name that is safe inside a log predicate string. */
 export const PROCESS_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._+-]{0,99}$/;
 /**
@@ -178,6 +193,18 @@ export class Simctl {
     async shutdown(udid) {
         await this.run(simctlShutdownArgv(udid), 60_000).catch(() => undefined);
     }
+    async addMedia(udid, paths) {
+        await this.run(simctlAddMediaArgv(udid, paths), 120_000);
+    }
+    /** The app's data container, or null when the app is not installed on the simulator. */
+    async dataContainer(udid, bundleId) {
+        try {
+            return (await this.run(simctlDataContainerArgv(udid, bundleId), 20_000)).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
     async executableName(udid, bundleId) {
         try {
             return parseAppinfoExecutable(await this.run(simctlAppinfoArgv(udid, bundleId), 20_000));

package/dist/src/devices/mp4.js

@@ -0,0 +1,80 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+/** The boxes that follow each other in [from, to); stops at the first that does not fit. */
+function* boxes(read, from, to) {
+    let at = from;
+    while (at + 8 <= to) {
+        const head = read(at, 8);
+        if (!head)
+            return;
+        let size = head.readUInt32BE(0);
+        let header = 8;
+        if (size === 1) {
+            const large = read(at + 8, 8);
+            if (!large)
+                return;
+            size = Number(large.readBigUInt64BE(0));
+            header = 16;
+        }
+        else if (size === 0) {
+            size = to - at;
+        }
+        if (size < header || at + size > to)
+            return;
+        yield { type: head.toString('latin1', 4, 8), start: at + header, end: at + size };
+        at += size;
+    }
+}
+/**
+ * An MP4's length in seconds, from its movie header (`moov/mvhd`), as players and `ffmpeg -i`
+ * report it; null for a file that is not an MP4 (a webm), has no header (a recording cut short) or
+ * gives no length.
+ */
+export function mp4Seconds(file) {
+    let fd;
+    try {
+        fd = openSync(file, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = fstatSync(fd).size;
+        const read = (at, length) => {
+            if (at + length > size)
+                return null;
+            const buffer = Buffer.alloc(length);
+            return readSync(fd, buffer, 0, length, at) === length ? buffer : null;
+        };
+        const top = boxes(read, 0, size);
+        const first = top.next();
+        if (first.done || first.value.type !== 'ftyp')
+            return null;
+        for (const box of top) {
+            if (box.type !== 'moov')
+                continue;
+            for (const child of boxes(read, box.start, box.end)) {
+                if (child.type !== 'mvhd')
+                    continue;
+                // version 0: 32-bit times, timescale at 12 and duration at 16; version 1: 64-bit, at 20 and 24.
+                const header = read(child.start, Math.min(32, child.end - child.start));
+                const v1 = header?.[0] === 1;
+                if (!header || header.length < (v1 ? 32 : 20))
+                    return null;
+                const timescale = header.readUInt32BE(v1 ? 20 : 12);
+                const duration = v1 ? header.readBigUInt64BE(24) : BigInt(header.readUInt32BE(16));
+                const unknown = v1 ? 0xffffffffffffffffn : 0xffffffffn;
+                if (timescale === 0 || duration === 0n || duration === unknown)
+                    return null;
+                return Number(duration) / timescale;
+            }
+            return null;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}

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

@@ -3,6 +3,7 @@ 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 { ensureFfmpeg } from './ffmpeg.js';
 /**
  * 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
@@ -12,6 +13,13 @@ import { setTimeout as sleep } from 'node:timers/promises';
 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'];
 }
+/**
+ * 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). */
@@ -30,16 +38,32 @@ export function screenRecordArgv(file, os, framerate = 10, 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', ...input, ...encodeArgv(framerate), file];
+    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;
     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, options = {}) {
@@ -49,29 +73,69 @@ export class ScreenRecorder {
         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) {
+    /** 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);
-        const child = (this.options.spawn ?? spawn)(this.ffmpeg, argv, { stdio: ['pipe', 'ignore', 'pipe'], windowsHide: true });
+        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) {
@@ -79,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 {
@@ -107,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/drivers/android-appium.js

@@ -6,14 +6,14 @@ import { AppiumServer, AppiumUnavailable, bundledAppium, MJPEG_PORTS, SYSTEM_POR
 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';
@@ -300,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;
@@ -321,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,12 +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 { ensureFfmpeg } from '../devices/ffmpeg.js';
-import { 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';
@@ -62,6 +61,7 @@ export function validateNativeAction(platform, action) {
 export class DesktopAppiumDriver {
     ctx;
     appium;
+    makeRecorder;
     client = null;
     unpacked = null;
     releaseBuild = null;
@@ -71,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);
@@ -153,14 +156,11 @@ export class DesktopAppiumDriver {
     }
     /** 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 = await ensureFfmpeg({ ...(this.ctx.paths ? { paths: this.ctx.paths } : {}), log: this.ctx.log });
-        if (!ffmpeg)
+        const recorder = await (this.makeRecorder ?? ffmpegRecorder(this.paths, this.ctx.log))(this.platform, undefined);
+        if (!recorder)
             return;
-        this.startedAt = Date.now();
-        const recorder = new ScreenRecorder(ffmpeg, this.platform);
         try {
             await recorder.start();
             this.recorder = recorder;
@@ -182,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;
@@ -241,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);