@leera.io/qa-runner 1.0.6 → 1.2.0

package/README.md

@@ -197,7 +197,8 @@ ready and `4` when something marked `[fail]` needs fixing, with the command that
 The runner advertises phones (`android`, `android-real`), running emulators and emulators that
 exist but are off (`android`, `android-emulator`); an emulator is booted when a job needs it and
 stays booted. Each job installs the build, clears the app's data, records an MP4 when asked
-(runs over 3 minutes need `ffmpeg` on `PATH`) and captures the app's logcat warnings, errors and
+(runs over 3 minutes are joined with ffmpeg, which the runner downloads when none is installed)
+and captures the app's logcat warnings, errors and
 crashes per step. The same devices serve **device sessions**, in which an AI agent explores the
 app over MCP before writing a script. Details: [Android](https://github.com/leera-app/leera-qa-runner/blob/main/docs/test-runners.md#android),
 [device sessions](https://github.com/leera-app/leera-qa-runner/blob/main/docs/qa-automation-authoring.md#device-sessions).

package/dist/src/capabilities.js

@@ -1,6 +1,6 @@
 import { hostname } from 'node:os';
 import { registryAvailability } from './drivers/registry.js';
-import { findFfmpeg } from './devices/screen-record.js';
+import { ffmpegAvailable } from './devices/ffmpeg.js';
 import { playwrightVersion } from './version.js';
 export const PROTOCOL_VERSION = 2;
 export function osName(platform) {
@@ -53,9 +53,13 @@ export function deriveLabels(devices) {
 }
 /**
  * Protocol features by platform present; `sessions` = this runner handles device sessions
- * (contracts §H3). Web and Electron record webm (Playwright, contracts §K); mobile records mp4;
- * Tauri records no video and adds no feature beyond sessions (contracts §L). Native macOS and
- * Windows apps carry the Appium log on failed steps and record mp4 only with ffmpeg (contracts §M).
+ * (contracts §H3). Web and Electron record webm (Playwright, contracts §K); mobile records mp4.
+ * Tauri, native macOS and Windows apps record mp4 with ffmpeg, which the runner downloads when
+ * none is installed (contracts §L, §M); native apps also carry the Appium log on failed steps.
+ * `data_refs` = this runner fills test data, API URL and job placeholders on every platform
+ * (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`.
  */
 export function featuresFor(platforms, options = {}) {
     const features = [];
@@ -71,12 +75,14 @@ export function featuresFor(platforms, options = {}) {
     if (platforms.some((platform) => platform === 'macos' || platform === 'windows')) {
         if (!features.includes('step_debug'))
             features.push('step_debug');
-        if (options.ffmpeg && !features.includes('video_mp4'))
-            features.push('video_mp4');
     }
+    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');
     return features;
 }
-export function buildCapabilities(devices, host, extraTools = {}, options = { ffmpeg: findFfmpeg() !== null }) {
+export function buildCapabilities(devices, host, extraTools = {}, options = { ffmpeg: ffmpegAvailable() }) {
     const platforms = [...new Set(devices.map((device) => device.platform))];
     const tools = { node: host.node };
     const playwright = playwrightVersion();

package/dist/src/cli/commands/setup.js

@@ -7,11 +7,12 @@ import { ensureHome, homePaths } from '../../home.js';
 import { usageError } from '../output.js';
 import { setupAndroid } from '../../devices/android/setup.js';
 import { displayNeed, findOnPath, XVFB_DISPLAY } from '../../devices/desktop.js';
+import { downloadFfmpeg, ffmpegBuild, ffmpegCheckDetail, findFfmpeg } from '../../devices/ffmpeg.js';
 import { setupIos } from '../../devices/ios/setup.js';
 import { setupMacos } from '../../devices/macos.js';
 import { setupWindows } from '../../devices/windows.js';
 import { findNativeDriver, findTauriDriver, loadTauriSettings, MSEDGEDRIVER_URL, TAURI_DRIVER_INSTALL, TAURI_DRIVER_VERSION, WEBKIT_DRIVER_INSTALL, } from '../../devices/tauri.js';
-const usage = `Usage: leera-qa-runner setup browsers|android|ios|electron|tauri|macos|windows [options]
+const usage = `Usage: leera-qa-runner setup browsers|android|ios|electron|tauri|macos|windows|ffmpeg [options]
 
 Installs what a platform needs. This version supports:
   browsers            Chromium for web jobs (into the runner home unless PLAYWRIGHT_BROWSERS_PATH is set)
@@ -30,6 +31,10 @@ Installs what a platform needs. This version supports:
   windows             (Windows) Prepares Appium's home with the bundled Windows driver, downloads
                       WinAppDriver 1.2.1 (checked by sha256) into the runner home and prints the
                       install and Developer Mode steps
+  ffmpeg              Downloads the ffmpeg video recording uses (Tauri, Windows and macOS apps,
+                      real iPhones, Android cases over 3 minutes) into the runner home, checked by
+                      sha256. Jobs download it themselves when it is missing; an ffmpeg on the
+                      PATH is used instead
 
 Options for android:
   --install-sdk       Install platform-tools, emulator, build-tools and a system image with the
@@ -90,6 +95,9 @@ export function setupTauri(io, paths, lookup = {}) {
             settings.macosPlugin
                 ? 'tauri.macos_plugin is on: this runner advertises a Tauri device.'
                 : 'When your builds embed the plugin, turn it on:\n  leera-qa-runner config set tauri.macos_plugin true',
+            '',
+            `Video: ${ffmpegCheckDetail(io.env, io.platform).detail}. Recording the screen needs Screen Recording`,
+            'permission for the app that runs the runner (System Settings → Privacy & Security → Screen Recording).',
         ].join('\n'));
         return settings.macosPlugin ? ExitCode.ok : ExitCode.environmentNotReady;
     }
@@ -132,11 +140,40 @@ export function setupTauri(io, paths, lookup = {}) {
             '  2. leera-qa-runner config set tauri.native_driver_path C:\\path\\to\\msedgedriver.exe',
         ].join('\n'));
     }
+    io.stdout(`Video: ${ffmpegCheckDetail(io.env, io.platform).detail}.`);
     io.stdout(ready ? 'Tauri is ready.' : 'Tauri is not ready: install what is listed above, then run `leera-qa-runner doctor --platform tauri`.');
     return ready ? ExitCode.ok : ExitCode.environmentNotReady;
 }
+/**
+ * `setup ffmpeg`: downloads the pinned ffmpeg build video recording uses into the runner home,
+ * or reports the one already there (on PATH or downloaded). Exit 4 when this OS and CPU have no
+ * build to download, 1 when the download fails.
+ */
+export async function setupFfmpeg(io, paths, options = {}) {
+    const found = findFfmpeg(io.env, io.platform, undefined, paths);
+    if (found) {
+        io.stdout(`ffmpeg: ${found}`);
+        return ExitCode.ok;
+    }
+    const arch = options.arch ?? process.arch;
+    const build = options.build ?? ffmpegBuild(io.platform, arch);
+    if (!build) {
+        io.stderr(`There is no ffmpeg build to download for ${io.platform} ${arch}: install ffmpeg on the PATH to record video.`);
+        return ExitCode.environmentNotReady;
+    }
+    io.stdout(`Downloading ffmpeg (${Math.round(build.size / 1_000_000)} MB) from ${build.url} ...`);
+    try {
+        ensureHome(paths);
+        io.stdout(`ffmpeg: ${await downloadFfmpeg(paths, { ...options, platform: io.platform, arch })}`);
+        return ExitCode.ok;
+    }
+    catch (error) {
+        io.stderr(`ffmpeg could not be downloaded: ${error instanceof Error ? error.message : String(error)}`);
+        return ExitCode.error;
+    }
+}
 export const command = {
-    summary: 'Install platform tools (browsers, android, ios, electron, tauri, macos, windows)',
+    summary: 'Install platform tools (browsers, android, ios, electron, tauri, macos, windows, ffmpeg)',
     usage,
     async run(args, io) {
         const { positionals, values } = parseArgs({
@@ -185,6 +222,8 @@ export const command = {
             return setupMacos(io, homePaths(io.env));
         if (what === 'windows')
             return setupWindows(io, homePaths(io.env), { install: values.install ?? false });
+        if (what === 'ffmpeg')
+            return setupFfmpeg(io, homePaths(io.env));
         if (what === 'all') {
             throw usageError(`'setup all' is not available in this runner version; set up one platform at a time`, usage);
         }

package/dist/src/debug.js

@@ -13,15 +13,20 @@ const SENSITIVE_PARAM = /token|secret|password|passwd|pwd|auth|session|signature
  * Only what a person debugging a failure needs is kept: console errors and
  * warnings, uncaught page errors, and requests. Headers and bodies are never
  * recorded, since they carry cookies and the credential the script signs in with.
+ * Each step's start time is kept too, and is returned on its own while a video
+ * is being recorded, so the step can be found in the video.
  */
 export class DebugCollector {
     steps = new Map();
     current = null;
     startedAt;
     redact;
-    constructor(startedAt, redact) {
+    recording;
+    /** `recording` is asked when a step's capture is read (Electron only knows after launch whether a window is recorded). */
+    constructor(startedAt, redact, recording = () => false) {
         this.startedAt = startedAt;
         this.redact = redact;
+        this.recording = recording;
     }
     attach(page) {
         page.on('console', (message) => this.onConsole(message));
@@ -39,13 +44,18 @@ export class DebugCollector {
         this.entry(index).video_offset_secs = offset;
         return offset;
     }
-    /** The step's capture, or undefined when nothing but its start time was recorded. */
+    /**
+     * The step's capture. A step that captured nothing still gives its start time while a video is
+     * recorded, since that is its place in the video; without a video it gives undefined.
+     */
     for(index) {
         const debug = this.steps.get(index);
         if (!debug)
             return undefined;
-        const { video_offset_secs: _offset, ...captured } = debug;
-        return Object.keys(captured).length > 0 ? debug : undefined;
+        const { video_offset_secs: offset, ...captured } = debug;
+        if (Object.keys(captured).length > 0)
+            return debug;
+        return offset !== undefined && this.recording() ? debug : undefined;
     }
     onConsole(message) {
         const type = message.type();

package/dist/src/devices/ffmpeg.js

@@ -0,0 +1,135 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { writeResponseBody } from '../download.js';
+import { homePaths } from '../home.js';
+import { findOnPath } from './desktop.js';
+/**
+ * The ffmpeg video recording needs (contracts §L, §M): whole-screen capture for Tauri, Windows
+ * and macOS app jobs, and what Appium uses for real iPhones and for Android cases over 3 minutes.
+ * An ffmpeg on PATH is used as it is. Otherwise the runner downloads a static build once into its
+ * home, checked by size and sha256: the `ffmpeg-static` project's GitHub release, which carries
+ * the builds of johnvansickle.com (Linux), gyan.dev (Windows) and a macOS build, all GPL. The
+ * runner does not ship ffmpeg itself.
+ */
+export const FFMPEG_RELEASE = 'b6.1.1';
+const RELEASE_URL = `https://github.com/eugeneware/ffmpeg-static/releases/download/${FFMPEG_RELEASE}`;
+/** How long a job waits for the first download on a machine. */
+export const FFMPEG_JOB_DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
+/** Pinned builds by `<platform>-<arch>` (sizes and digests from the GitHub release). */
+export const FFMPEG_BUILDS = {
+    'darwin-arm64': { url: `${RELEASE_URL}/ffmpeg-darwin-arm64.gz`, sha256: '8923876afa8db5585022d7860ec7e589af192f441c56793971276d450ed3bbfa', size: 19_246_198 },
+    'darwin-x64': { url: `${RELEASE_URL}/ffmpeg-darwin-x64.gz`, sha256: '929b375c1182d956c51f7ac25e0b2b0411fb01f6f407aa15c9758efeb4242106', size: 25_296_431 },
+    'linux-arm64': { url: `${RELEASE_URL}/ffmpeg-linux-arm64.gz`, sha256: '754a678672298bc68156adff58aa7385a592c2b30b1d0ae8750c45c915c4bac0', size: 25_568_691 },
+    'linux-x64': { url: `${RELEASE_URL}/ffmpeg-linux-x64.gz`, sha256: 'bfe8a8fc511530457b528c48d77b5737527b504a3797a9bc4866aeca69c2dffa', size: 29_354_986 },
+    'win32-x64': { url: `${RELEASE_URL}/ffmpeg-win32-x64.gz`, sha256: '8883a3dffbd0a16cf4ef95206ea05283f78908dbfb118f73c83f4951dcc06d77', size: 29_581_307 },
+};
+/** The pinned build for this OS and CPU (Windows on Arm runs the x64 one), or null. */
+export function ffmpegBuild(platform = process.platform, arch = process.arch) {
+    const key = platform === 'win32' && arch === 'arm64' ? 'win32-x64' : `${platform}-${arch}`;
+    return FFMPEG_BUILDS[key] ?? null;
+}
+function executableName(platform) {
+    return platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg';
+}
+/** Where the downloaded ffmpeg lives: one directory per pinned release, so an update fetches its own. */
+export function managedFfmpegDir(paths) {
+    return join(paths.ffmpeg, FFMPEG_RELEASE);
+}
+export function managedFfmpegPath(paths, platform = process.platform) {
+    return join(managedFfmpegDir(paths), executableName(platform));
+}
+/** ffmpeg on PATH, else the one the runner downloaded; null when there is neither. */
+export function findFfmpeg(env = process.env, platform = process.platform, exists, paths = homePaths(env)) {
+    const onPath = findOnPath(executableName(platform), env, exists);
+    if (onPath)
+        return onPath;
+    const managed = managedFfmpegPath(paths, platform);
+    return (exists ?? existsSync)(managed) ? managed : null;
+}
+/** Whether jobs can record with ffmpeg: one is there, or this OS and CPU have a build to download. */
+export function ffmpegAvailable(env = process.env, platform = process.platform, arch = process.arch) {
+    return findFfmpeg(env, platform) !== null || ffmpegBuild(platform, arch) !== null;
+}
+const downloads = new Map();
+/**
+ * Downloads the pinned build for this machine into the runner home and returns its path; one
+ * already there is kept. Callers at the same time share one download. Throws when this OS and CPU
+ * have no build, or the download fails or does not match its pin.
+ */
+export function downloadFfmpeg(paths, options = {}) {
+    const target = managedFfmpegPath(paths, options.platform ?? process.platform);
+    const pending = downloads.get(target);
+    if (pending)
+        return pending;
+    const download = fetchBuild(target, options).finally(() => downloads.delete(target));
+    downloads.set(target, download);
+    return download;
+}
+async function fetchBuild(target, options) {
+    if (existsSync(target))
+        return target;
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const build = options.build ?? ffmpegBuild(platform, arch);
+    if (!build)
+        throw new Error(`there is no ffmpeg build to download for ${platform} ${arch}; install ffmpeg on the PATH`);
+    const dir = dirname(target);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tag = `${process.pid}-${randomBytes(4).toString('hex')}`;
+    const gzip = join(dir, `.download-${tag}.gz`);
+    const unpacked = join(dir, `.download-${tag}`);
+    try {
+        options.log?.info('downloading ffmpeg for video recording', { url: build.url, bytes: build.size });
+        const response = await (options.fetch ?? fetch)(build.url, { redirect: 'follow', signal: AbortSignal.timeout(options.timeoutMs ?? 10 * 60_000) });
+        if (!response.ok || !response.body)
+            throw new Error(`the ffmpeg download failed with HTTP ${response.status}`);
+        const hash = createHash('sha256');
+        const size = await writeResponseBody(response.body, gzip, (chunk) => hash.update(chunk));
+        const digest = hash.digest('hex');
+        if (size !== build.size || digest !== build.sha256) {
+            throw new Error(`the ffmpeg download does not match its pin (${size} bytes, sha256 ${digest})`);
+        }
+        await pipeline(createReadStream(gzip), createGunzip(), createWriteStream(unpacked, { mode: 0o755 }));
+        if (platform !== 'win32')
+            chmodSync(unpacked, 0o755);
+        renameSync(unpacked, target);
+        options.log?.info('ffmpeg downloaded', { path: target });
+        return target;
+    }
+    finally {
+        rmSync(gzip, { force: true });
+        rmSync(unpacked, { force: true });
+    }
+}
+/**
+ * The ffmpeg to record with: one on PATH or already downloaded, else the pinned build, downloaded
+ * now (the first video job on a machine waits for it). Null, with a warning, when there is none.
+ */
+export async function ensureFfmpeg(options = {}) {
+    const env = options.env ?? process.env;
+    const paths = options.paths ?? homePaths(env);
+    const platform = options.platform ?? process.platform;
+    const found = findFfmpeg(env, platform, undefined, paths);
+    if (found)
+        return found;
+    try {
+        return await downloadFfmpeg(paths, { timeoutMs: FFMPEG_JOB_DOWNLOAD_TIMEOUT_MS, ...options, platform });
+    }
+    catch (error) {
+        options.log?.warn('video is not recorded: ffmpeg could not be downloaded', { error: error instanceof Error ? error.message : String(error) });
+        return null;
+    }
+}
+/** The doctor line for video on a platform that records with ffmpeg. */
+export function ffmpegCheckDetail(env, platform, arch = process.arch) {
+    const found = findFfmpeg(env, platform);
+    if (found)
+        return { ok: true, detail: `ffmpeg ${found}` };
+    if (ffmpegBuild(platform, arch)) {
+        return { ok: true, detail: 'ffmpeg is downloaded on the first job with video (or now with `leera-qa-runner setup ffmpeg`)' };
+    }
+    return { ok: false, detail: `ffmpeg is not installed and there is no build to download for ${platform} ${arch}; jobs record no video` };
+}

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

@@ -3,6 +3,7 @@ import { existsSync, mkdtempSync, renameSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
+import { findFfmpeg } from '../ffmpeg.js';
 import { assertSimUdid } from './simctl.js';
 /**
  * Records a simulator's screen with `simctl io recordVideo` (H.264). simctl always writes a
@@ -27,17 +28,17 @@ export function majorBrand(header) {
 }
 /**
  * Rewrites a QuickTime recording as an MP4 container in place, with `avconvert` (macOS) or else
- * ffmpeg when present. Returns how, or null when neither worked (the QuickTime file is kept;
- * browsers and the server still accept it as video/mp4).
+ * ffmpeg (on PATH or the runner's download) when present. Returns how, or null when neither
+ * worked (the QuickTime file is kept; browsers and the server still accept it as video/mp4).
  */
-export function remuxToMp4(file, run = runQuiet) {
+export function remuxToMp4(file, run = runQuiet, ffmpeg = findFfmpeg() ?? 'ffmpeg') {
     const temp = `${file}.remux.mp4`;
-    for (const [tool, argv] of [
-        ['avconvert', avconvertRemuxArgv(file, temp)],
-        ['ffmpeg', ffmpegRemuxArgv(file, temp)],
+    for (const [tool, command, argv] of [
+        ['avconvert', 'avconvert', avconvertRemuxArgv(file, temp)],
+        ['ffmpeg', ffmpeg, ffmpegRemuxArgv(file, temp)],
     ]) {
         rmSync(temp, { force: true });
-        if (run(tool, [...argv]) && existsSync(temp) && statSync(temp).size > 0) {
+        if (run(command, [...argv]) && existsSync(temp) && statSync(temp).size > 0) {
             renameSync(temp, file);
             return tool;
         }

package/dist/src/devices/macos.js

@@ -8,7 +8,7 @@ import { ensureHome } from '../home.js';
 import { runTool } from './android/adb.js';
 import { appiumDriverListArgv } from './android/setup.js';
 import { developerDir, isCommandLineToolsOnly, xcodeInfo } from './ios/wda.js';
-import { findFfmpeg } from './screen-record.js';
+import { ffmpegCheckDetail } from './ffmpeg.js';
 /**
  * Native macOS apps (contracts §M): Appium's Mac2 driver, which builds and runs
  * WebDriverAgentMac (an XCTest UI-testing bundle) with Xcode on the first session. XCTest needs
@@ -110,8 +110,8 @@ export const ACCESSIBILITY_STEPS = [
     '     when macOS asks.',
     '  3. The first session enables Automation Mode; macOS may ask for an administrator password on this',
     '     screen. Keep the Mac logged in and unlocked while jobs run (a locked screen blocks UI testing).',
-    '  4. Optional: install ffmpeg (`brew install ffmpeg`) and allow Screen Recording for the same app to',
-    '     record job videos.',
+    '  4. For job videos: System Settings → Privacy & Security → Screen Recording: allow the same app. The',
+    '     runner downloads the ffmpeg it records with on the first job with video.',
 ];
 /** Whether this Mac can run macOS app jobs now: Xcode, Appium with Mac2, no recorded Accessibility refusal. */
 export async function macosReadiness(paths, platform = process.platform) {
@@ -172,10 +172,10 @@ export async function macosChecks(env, paths, platform = process.platform) {
     else if (mode) {
         checks.push({ id: 'macos.automation_mode', title: 'macOS apps: Automation Mode', status: 'ok', detail: mode.enabled ? 'enabled' : 'enabled on demand without authentication' });
     }
-    const ffmpeg = findFfmpeg(env, platform);
-    checks.push(ffmpeg
-        ? { id: 'macos.video', title: 'macOS apps: video', status: 'ok', detail: `ffmpeg ${ffmpeg} (needs Screen Recording permission)` }
-        : { id: 'macos.video', title: 'macOS apps: video', status: 'warn', detail: 'ffmpeg is not installed; jobs record no video', fix: 'brew install ffmpeg' });
+    const video = ffmpegCheckDetail(env, platform);
+    checks.push(video.ok
+        ? { id: 'macos.video', title: 'macOS apps: video', status: 'ok', detail: `${video.detail} (needs Screen Recording permission)` }
+        : { id: 'macos.video', title: 'macOS apps: video', status: 'warn', detail: video.detail, fix: 'brew install ffmpeg' });
     return checks;
 }
 /**
@@ -240,8 +240,7 @@ export async function setupMacos(io, paths) {
         io.stdout('');
         io.stdout('Automation Mode is disabled and asks for an administrator password when a session enables it: be at the Mac for the first job.');
     }
-    if (!findFfmpeg(io.env, io.platform))
-        io.stdout('ffmpeg is not installed: macOS app jobs record no video.');
+    io.stdout(`Video: ${ffmpegCheckDetail(io.env, io.platform).detail}.`);
     io.stdout('');
     io.stdout(ok ? 'macOS apps are set up. Check with `leera-qa-runner doctor --platform macos`.' : 'macOS setup is incomplete; see the messages above.');
     return ok ? ExitCode.ok : ExitCode.environmentNotReady;

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

@@ -3,47 +3,56 @@ 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';
 /**
- * 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) {
+/** 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', ...input, ...encodeArgv(framerate), file];
 }
 /** One ffmpeg screen recording; `stop()` asks ffmpeg to finish (`q`) so the mp4 is complete. */
 export class ScreenRecorder {
     ffmpeg;
     os;
-    spawnImpl;
+    options;
     child = null;
     exited = false;
     stderr = '';
     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 });
+        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 });
         this.child = child;
         child.stderr?.on('data', (chunk) => {
             this.stderr = `${this.stderr}${chunk.toString('utf8')}`.slice(-2_000);
@@ -84,6 +93,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;

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,6 +1,6 @@
 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';
@@ -11,6 +11,7 @@ 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 { Blocked, LaunchRefused, NotFound, } from './driver.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,
@@ -456,16 +465,15 @@ export class AndroidAppiumDriver {
     debug(index, result) {
         const captured = this.logcat?.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;
     }
     /** The Appium log lines written from step `index`'s start to the next step's start (or now). */
     appiumLogFor(index) {