@leera.io/qa-runner 1.1.0 → 1.4.0

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

@@ -1,4 +1,4 @@
-import { mkdtempSync, writeFileSync } from 'node:fs';
+import { copyFileSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { bundledDrivers } from '../appium/drivers.js';
@@ -8,13 +8,14 @@ import { AppNotAvailable, resolveAppFile } from '../builds/install.js';
 import { leaseIosDevice, listIosDevices, Simctl } from '../devices/ios/index.js';
 import { SimulatorRecorder } from '../devices/ios/record.js';
 import { loadIosSettings } from '../devices/ios/settings.js';
-import { assertBundleId } from '../devices/ios/simctl.js';
+import { assertBundleId, isSimulatorMedia } from '../devices/ios/simctl.js';
 import { parseDeviceSyslogLine, SimulatorLogSink, SyslogCollector } from '../devices/ios/syslog.js';
 import { developerDir, isCommandLineToolsOnly, wdaRealDeviceDir, wdaStatus } from '../devices/ios/wda.js';
+import { ensureFfmpeg } from '../devices/ffmpeg.js';
 import { homePaths } from '../home.js';
-import { renderTemplate } from '../template.js';
+import { renderTemplate, resolveFileEntries } from '../template.js';
 import { AndroidAppiumDriver, androidSdkFor, APPIUM_LOG_MAX_BYTES, appiumLogLines, configuredSdkPath, LOCAL_PATHS_REFUSED, sharedAppiumServer } from './android-appium.js';
-import { Blocked, LaunchRefused, } from './driver.js';
+import { Blocked, LaunchRefused, Unsupported, } from './driver.js';
 import { emptyScreen } from './snapshot/format.js';
 import { IOS_ACTIONS, runIosAction } from './webdriver/ios-actions.js';
 import { IOS_LOCATORS, iosFindAll } from './webdriver/ios-locate.js';
@@ -242,6 +243,8 @@ export class IosAppiumDriver {
                     await recorder.start();
                 }
                 else {
+                    // Appium records a real device through ffmpeg on this Mac: fetch it when missing.
+                    await ensureFfmpeg({ paths: this.paths, log: this.ctx.log });
                     await client.startRecordingScreen({ timeLimit: RECORDING_LIMIT_SECS, videoType: 'h264', forceRestart: true });
                 }
                 this.recording = true;
@@ -291,6 +294,10 @@ export class IosAppiumDriver {
         };
     }
     async run(action) {
+        if (action.type === 'add_files') {
+            await this.addFiles(action);
+            return {};
+        }
         const prepared = action.target ? { ...action, target: AndroidAppiumDriver.resolveRefTarget(action.target) } : action;
         try {
             return await runIosAction(this.actionContext(), prepared);
@@ -299,6 +306,39 @@ export class IosAppiumDriver {
             throw this.translate(error);
         }
     }
+    /**
+     * `add_files` on a simulator: photos and videos go to its Photos library (`simctl addmedia`),
+     * other files into the app's Documents folder, where the app and the Files app (for apps that
+     * share their documents) find them. Real devices cannot take files yet.
+     */
+    async addFiles(action) {
+        const files = resolveFileEntries(action.files, this.ctx.template);
+        const lease = this.lease;
+        if (!lease)
+            throw new Blocked('the device is not connected');
+        if (lease.kind !== 'simulator') {
+            throw new Unsupported('add_files works on simulators; adding files to a real iPhone or iPad is not available yet');
+        }
+        const media = files.filter((file) => isSimulatorMedia(file.file.file_name));
+        const documents = files.filter((file) => !isSimulatorMedia(file.file.file_name));
+        if (media.length > 0) {
+            try {
+                await this.simctl.addMedia(lease.udid, media.map((file) => file.path));
+            }
+            catch (error) {
+                throw new Blocked(`the photos could not be added to the simulator: ${webdriverMessage(error)}`);
+            }
+        }
+        if (documents.length === 0)
+            return;
+        const container = await this.simctl.dataContainer(lease.udid, this.bundleId);
+        if (!container)
+            throw new Blocked(`${this.bundleId} has no data folder on the simulator; launch the app first`);
+        const folder = join(container, 'Documents');
+        mkdirSync(folder, { recursive: true });
+        for (const file of documents)
+            copyFileSync(file.path, join(folder, file.file.file_name));
+    }
     /** A lost Appium/WebDriverAgent session is an environment problem, not a failed check. */
     translate(error) {
         const message = webdriverMessage(error);

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

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { AppiumUnavailable, PortRange } from '../appium/server.js';
 import { hostDevice } from '../devices/desktop.js';
@@ -8,7 +9,7 @@ import { clip, errorMessage, expectWithin, renderLaunchArgs } from './common.js'
 import { DesktopAppiumDriver, validateNativeAction } from './desktop-appium.js';
 import { Blocked, LaunchRefused, } from './driver.js';
 import { emptyScreen } from './snapshot/format.js';
-import { macKey } from './webdriver/desktop-keys.js';
+import { macKey, macOpenDialogChords } from './webdriver/desktop-keys.js';
 import { predicateString } from './webdriver/ios-locate.js';
 import { elementIdOf } from './webdriver/locate.js';
 import { NATIVE_DESKTOP_ACTIONS } from './webdriver/native-actions.js';
@@ -25,6 +26,25 @@ export function macos(client, command, args = {}) {
         throw new Error(`invalid macos command '${command}'`);
     return client.executeScript(`macos: ${command}`, [args]);
 }
+/** Puts text on the Mac's pasteboard (the runner runs on the Mac it drives). */
+export function copyToPasteboard(text) {
+    const result = spawnSync('pbcopy', { input: text, timeout: 10_000 });
+    if (result.status !== 0)
+        throw new Error(`the folder of the files could not be put on the pasteboard (pbcopy exited ${String(result.status)})`);
+}
+/**
+ * Picks files in a macOS Open panel: Go to Folder with the folder's path pasted (typing it would
+ * depend on the keyboard layout), then the folder's only file (down) or all of them (cmd+a), and
+ * Open. The panel animates in and out, so each chord waits a little.
+ */
+export async function fillMacOpenDialog(client, folder, names, copy = copyToPasteboard, pauseMs = 600) {
+    await sleep(pauseMs);
+    copy(folder);
+    for (const chords of macOpenDialogChords(names.length)) {
+        await macos(client, 'keys', { keys: chords.map(macKey) });
+        await sleep(pauseMs);
+    }
+}
 /** The class chain that finds a window whose title contains (or equals) `title`. */
 export function macWindowChain(title, exact) {
     const literal = predicateString(title).replace(/`/g, '\\`');
@@ -110,7 +130,7 @@ export class Mac2AppiumDriver extends DesktopAppiumDriver {
     launched = false;
     disposed = false;
     constructor(ctx, appium, deps = {}) {
-        super(ctx, appium);
+        super(ctx, appium, deps.recorder);
         this.deps = deps;
     }
     get ops() {
@@ -209,6 +229,9 @@ export class Mac2AppiumDriver extends DesktopAppiumDriver {
                 case 'focus_window':
                     await this.focusWindow(action);
                     return {};
+                case 'upload':
+                    await this.upload(action);
+                    return {};
                 default:
                     return await this.runShared(action);
             }
@@ -217,6 +240,9 @@ export class Mac2AppiumDriver extends DesktopAppiumDriver {
             throw this.translate(error);
         }
     }
+    pickInOpenDialog(folder, names) {
+        return fillMacOpenDialog(this.requireClient(), folder, names);
+    }
     /** Activates the app and raises the window with that title (a click on its title bar). */
     async focusWindow(action) {
         const client = this.requireClient();

package/dist/src/drivers/tauri-webdriver.js

@@ -6,13 +6,15 @@ import { disposeUnpacked } from '../builds/cleanup.js';
 import { AppNotAvailable, resolveAppFile } from '../builds/install.js';
 import { buildKind, DesktopBuildError, localDesktopApp, unpackDesktopBuild } from '../builds/unpack.js';
 import { ensureDisplay, hostDevice } from '../devices/desktop.js';
+import { ffmpegRecorder } from '../devices/screen-record.js';
 import { loadTauriSettings, MACOS_PLUGIN_BLOCKED, tauriBackend, tauriCapabilities, tauriDriverArgv, } from '../devices/tauri.js';
 import { homePaths } from '../home.js';
+import { resolveFileEntries } from '../template.js';
 import { LOCAL_PATHS_REFUSED } from './android-appium.js';
-import { clip, errorMessage, expectWithin, matches, render, renderLaunchArgs, requireTarget, verb } from './common.js';
+import { clip, errorMessage, expectWithin, matches, POLL_MS, render, renderLaunchArgs, requireTarget, stepStartOffset, verb } from './common.js';
 import { Blocked, LaunchRefused, NotFound, Unsupported, } from './driver.js';
 import { ELECTRON_ACTIONS, electronEnv, killProcessTree, RESERVED_ARG, validateElectronAction } from './electron-playwright.js';
-import { DOM_LOCATORS, describeDomTarget, domCandidates, domFindAll, domLocate, domLocateOnce, domScript, elementRef, keyActions, validateDomTarget, webdriverKeys, } from './webdriver/dom.js';
+import { DOM_LOCATORS, describeDomTarget, domCandidates, domLocateOnce, domLocateRequest, domQuery, domScript, domToken, elementRef, keyActions, parseDomMatches, validateDomTarget, webdriverKeys, } from './webdriver/dom.js';
 import { buildDomSnapshot, domRefOf, domScreen } from './webdriver/dom-tree.js';
 import { elementIdOf } from './webdriver/locate.js';
 import { openSession, webdriverMessage } from './webdriver/session.js';
@@ -24,9 +26,13 @@ export const MSI_REFUSED = 'an .msi installer cannot run in place — upload the
 export const DEB_REFUSED = 'a .deb package cannot run in place — upload the .AppImage or a zip of the installed app folder';
 /** How long a macOS plugin build has to answer `GET /status` (contracts §L). */
 export const PLUGIN_STATUS_TIMEOUT_MS = 30_000;
+/** The label Tauri gives an app's first window unless the app names it; the plugin's window handles are labels. */
+export const MAIN_WINDOW_LABEL = 'main';
 const DRIVER_START_TIMEOUT_MS = 20_000;
 const SESSION_TIMEOUT_MS = 120_000;
 const PAGE_READY_TIMEOUT_MS = 30_000;
+/** Matches a session `find` names refs for. */
+const FIND_LIMIT = 20;
 /** Checks a Tauri action before it runs; throws what the step reports. */
 export function validateTauriAction(action) {
     if (action.type === 'goto')
@@ -36,6 +42,30 @@ export function validateTauriAction(action) {
     if (action.target)
         validateDomTarget(action.target);
 }
+/** Whether an element is a file input or a label for one, with that input (a WebDriver script). */
+const FILE_INPUT_SCRIPT = `const el = arguments[0];
+const control = el instanceof HTMLLabelElement ? el.control : el;
+if (!(control instanceof HTMLInputElement) || control.type !== 'file') return { input: null, multiple: false };
+return { input: control, multiple: control.multiple };`;
+/** A hidden multiple file input for a drop's files (a WebDriver script). */
+const DROP_SOURCE_SCRIPT = `const input = document.createElement('input');
+input.type = 'file';
+input.multiple = true;
+input.style.display = 'none';
+input.setAttribute('data-qa-drop-source', '');
+(document.body || document.documentElement).appendChild(input);
+return input;`;
+/** Drops the files of arguments[1] onto arguments[0]; true when a handler took them (a WebDriver script). */
+const DROP_SCRIPT = `const target = arguments[0];
+const transfer = new DataTransfer();
+for (const file of Array.from(arguments[1].files || [])) transfer.items.add(file);
+const box = target.getBoundingClientRect();
+const init = { bubbles: true, cancelable: true, composed: true, dataTransfer: transfer,
+  clientX: box.left + box.width / 2, clientY: box.top + box.height / 2 };
+target.dispatchEvent(new DragEvent('dragenter', init));
+const over = !target.dispatchEvent(new DragEvent('dragover', init));
+const dropped = !target.dispatchEvent(new DragEvent('drop', init));
+return over || dropped;`;
 /** Why a build file cannot run as a Tauri app, or null (installers are refused, contracts §L). */
 export function tauriBuildRefusal(fileName) {
     const lower = fileName.toLowerCase();
@@ -134,7 +164,7 @@ export class TauriWebDriver {
     backend;
     deps;
     platform = 'tauri';
-    capabilities = { actions: TAURI_ACTIONS, targets: TAURI_TARGETS, video: 'none' };
+    capabilities = { actions: TAURI_ACTIONS, targets: TAURI_TARGETS, video: 'mp4' };
     client = null;
     driverProcess = null;
     driverPort = null;
@@ -143,11 +173,17 @@ export class TauriWebDriver {
     unpacked = null;
     releaseBuild = null;
     display = null;
-    /** ref → WebDriver element id from the last snapshot. */
-    refElements = new Map();
+    /** The snapshot the page keeps (refs resolve only against it) and ref → its element's index there. */
+    snapshotId = null;
+    refIndexes = new Map();
     firstLaunchDone = false;
     actionsRun = 0;
     disposed = false;
+    recorder = null;
+    videoStopped = false;
+    videoPath;
+    /** When each step began (ms), in the order they ran; offsets count from the video's first frame. */
+    stepStarts = [];
     constructor(ctx, backend, deps = {}) {
         this.ctx = ctx;
         this.backend = backend;
@@ -227,8 +263,38 @@ export class TauriWebDriver {
             args = renderLaunchArgs(first.args, this.renderText, RESERVED_ARG);
             this.firstLaunchDone = true;
         }
+        await this.startRecording();
         await this.start(args);
     }
+    /** The screen the app runs on, as the recorder names it. */
+    screenOs() {
+        return this.backend.kind === 'macos-plugin' ? 'macos' : this.backend.os;
+    }
+    /**
+     * Records the whole screen (on Linux, the job's X display) from before the app starts until
+     * the job ends, across relaunches, when the job wants video. Without ffmpeg (none installed and
+     * none downloaded) or when recording cannot start, the job runs without a video.
+     */
+    async startRecording() {
+        if (this.ctx.video === 'off')
+            return;
+        const os = this.screenOs();
+        const display = os === 'linux' ? this.display?.env.DISPLAY || process.env.DISPLAY?.trim() || undefined : undefined;
+        if (os === 'linux' && !display) {
+            this.ctx.log.warn('video is not recorded: the job has no X display');
+            return;
+        }
+        const recorder = await (this.deps.recorder ?? ffmpegRecorder(this.paths, this.ctx.log))(os, display);
+        if (!recorder)
+            return;
+        try {
+            await recorder.start();
+            this.recorder = recorder;
+        }
+        catch (error) {
+            this.ctx.log.warn('screen recording could not start', { error: errorMessage(error) });
+        }
+    }
     async start(args) {
         const executable = this.executable;
         if (!executable)
@@ -301,6 +367,19 @@ export class TauriWebDriver {
             await this.closeApp();
             throw error;
         }
+        await this.startInMainWindow(this.client);
+    }
+    /**
+     * The plugin starts its session in whichever window its window map yields first, so an app
+     * that opens several at launch could start in any of them. Start in the `main` window when
+     * there is one, as tauri-driver starts in the app's first window.
+     */
+    async startInMainWindow(client) {
+        const handles = await client.getWindowHandles().catch(() => []);
+        if (handles.length < 2 || !handles.includes(MAIN_WINDOW_LABEL))
+            return;
+        if ((await client.getWindowHandle().catch(() => null)) !== MAIN_WINDOW_LABEL)
+            await client.switchToWindow(MAIN_WINDOW_LABEL);
     }
     /** Waits until the web view runs the runner's script (the page has loaded). */
     async waitForPage() {
@@ -354,43 +433,56 @@ export class TauriWebDriver {
             throw new Error('the app is not running; start it with launch');
         return this.client;
     }
-    /** The element a target names: a snapshot ref when it still exists, else the locator (waiting up to `timeoutMs`). */
-    async element(target, timeoutMs, visible = true) {
-        const client = this.requireClient();
+    /** The `dom-locate.js` request for the element a snapshot ref names, or null. */
+    refRequest(target) {
         const ref = domRefOf(target.locate);
-        const id = ref ? this.refElements.get(ref) : undefined;
-        if (id) {
-            const displayed = await client.isElementDisplayed(id).then((value) => ({ ok: true, value }), () => ({ ok: false, value: false }));
-            if (displayed.ok)
-                return { elementId: id, target, count: 1, visible: displayed.value };
+        const index = ref ? this.refIndexes.get(ref) : undefined;
+        return this.snapshotId && index !== undefined ? { ref: { snapshot: this.snapshotId, index } } : null;
+    }
+    /** One look for the target: its snapshot ref while that element is still in the page, else the locator. */
+    async locateOnce(target, want = {}) {
+        const client = this.requireClient();
+        const byRef = this.refRequest(target);
+        if (byRef) {
+            const found = await domQuery(client, byRef, 0, want);
+            if (found.count > 0)
+                return { target, count: 1, visible: found.visible[0] ?? false, elementId: found.elementId };
         }
         const { locate: _locate, ...plain } = target;
-        const found = await domLocate(client, plain, timeoutMs, { render: this.renderText, visible });
-        if (!found)
-            throw new NotFound(`${describeDomTarget(plain)} was not found within ${Math.round(timeoutMs / 100) / 10} s`);
-        return found;
+        return domLocateOnce(client, plain, this.renderText, want);
+    }
+    /** Looks for the target until it is there (visible and with an element id, as wanted) or the time is up. */
+    async locate(target, timeoutMs, want) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const found = await this.locateOnce(target, want);
+            if (found && (!want.visible || found.visible) && (!want.element || found.elementId))
+                return found;
+            if (Date.now() >= deadline) {
+                const { locate: _locate, ...plain } = target;
+                throw new NotFound(`${describeDomTarget(plain)} was not found within ${Math.round(timeoutMs / 100) / 10} s`);
+            }
+            await sleep(POLL_MS);
+        }
+    }
+    /** The WebDriver element id of what a target names, waiting up to `timeoutMs` (for it to be visible, unless `visible` is false). */
+    async element(target, timeoutMs, visible = true) {
+        const found = await this.locate(target, timeoutMs, { element: true, visible });
+        if (!found.elementId)
+            throw new NotFound(`${describeDomTarget(target)} was not found`);
+        return found.elementId;
     }
     /** Whether the target is on screen now (no waiting). */
     async visibleNow(target) {
-        const client = this.requireClient();
-        const ref = domRefOf(target.locate);
-        const id = ref ? this.refElements.get(ref) : undefined;
-        if (id) {
-            const displayed = await client.isElementDisplayed(id).catch(() => null);
-            if (displayed !== null)
-                return displayed;
-        }
-        const { locate: _locate, ...plain } = target;
-        const found = await domLocateOnce(client, plain, this.renderText);
-        return found?.visible ?? false;
+        return (await this.locateOnce(target))?.visible ?? false;
     }
     /** Retries an element command while the element is not interactable yet. */
     async retrying(timeoutMs, target, command) {
         const deadline = Date.now() + timeoutMs;
-        let found = await this.element(target, timeoutMs);
+        let id = await this.element(target, timeoutMs);
         for (;;) {
             try {
-                await command(found.elementId);
+                await command(id);
                 return;
             }
             catch (error) {
@@ -400,7 +492,7 @@ export class TauriWebDriver {
                 await sleep(200);
                 if (/stale element/i.test(message)) {
                     const { locate: _locate, ...plain } = target;
-                    found = await this.element(plain, Math.max(100, deadline - Date.now()));
+                    id = await this.element(plain, Math.max(100, deadline - Date.now()));
                 }
             }
         }
@@ -413,9 +505,9 @@ export class TauriWebDriver {
                 await this.retrying(timeout, requireTarget(action), (id) => client.elementClick(id));
                 return {};
             case 'hover': {
-                const found = await this.element(requireTarget(action), timeout);
+                const id = await this.element(requireTarget(action), timeout);
                 await client.performActions([
-                    { type: 'pointer', id: 'mouse', parameters: { pointerType: 'mouse' }, actions: [{ type: 'pointerMove', duration: 0, origin: elementRef(found.elementId), x: 0, y: 0 }] },
+                    { type: 'pointer', id: 'mouse', parameters: { pointerType: 'mouse' }, actions: [{ type: 'pointerMove', duration: 0, origin: elementRef(id), x: 0, y: 0 }] },
                 ]);
                 return {};
             }
@@ -423,11 +515,11 @@ export class TauriWebDriver {
             case 'uncheck': {
                 const wanted = action.type === 'check';
                 const target = requireTarget(action);
-                const found = await this.element(target, timeout);
-                if ((await client.isElementSelected(found.elementId)) !== wanted) {
-                    await this.retrying(timeout, target, (id) => client.elementClick(id));
+                const id = await this.element(target, timeout);
+                if ((await client.isElementSelected(id)) !== wanted) {
+                    await this.retrying(timeout, target, (elementId) => client.elementClick(elementId));
                 }
-                await expectWithin(Math.min(timeout, 2_000), async () => (await client.isElementSelected(found.elementId)) === wanted, `the element to be ${wanted ? 'checked' : 'unchecked'}`);
+                await expectWithin(Math.min(timeout, 2_000), async () => (await client.isElementSelected(id)) === wanted, `the element to be ${wanted ? 'checked' : 'unchecked'}`);
                 return {};
             }
             case 'fill': {
@@ -441,15 +533,22 @@ export class TauriWebDriver {
             }
             case 'select_option': {
                 const value = render(action.value, this.ctx.template);
-                const found = await this.element(requireTarget(action), timeout);
-                const options = await client.findElementsFromElement(found.elementId, 'css selector', 'option');
+                const id = await this.element(requireTarget(action), timeout);
+                const options = await client.findElementsFromElement(id, 'css selector', 'option');
                 const seen = [];
                 for (const option of options) {
-                    const id = elementIdOf(option);
-                    const [optionValue, text] = await Promise.all([client.getElementProperty(id, 'value'), client.getElementText(id)]);
+                    const optionId = elementIdOf(option);
+                    const [optionValue, text] = await Promise.all([client.getElementProperty(optionId, 'value'), client.getElementText(optionId)]);
                     seen.push(text.trim());
                     if (optionValue === value || text.trim() === value) {
-                        await client.elementClick(id);
+                        await client.elementClick(optionId);
+                        // W3C servers select an option they click; tauri-plugin-wdio-webdriver 1.4 only fires
+                        // a click event at it. Select it the way the click should have.
+                        if (!(await client.isElementSelected(optionId))) {
+                            await client.executeScript(domScript('dom-element'), [{ op: 'select' }, elementRef(optionId)]);
+                            if (!(await client.isElementSelected(optionId)))
+                                throw new Error(`the option "${clip(text.trim())}" could not be selected`);
+                        }
                         return {};
                     }
                 }
@@ -458,18 +557,16 @@ export class TauriWebDriver {
             case 'press': {
                 const keys = webdriverKeys(action.key ?? '');
                 if (action.target) {
-                    const found = await this.element(action.target, timeout);
-                    const chord = `${keys.modifiers.join('')}${keys.key}${keys.modifiers.length > 0 ? '' : ''}`;
-                    await client.elementSendKeys(found.elementId, chord);
-                }
-                else {
-                    await client.performActions(keyActions(keys));
-                    await client.releaseActions().catch(() => undefined);
+                    // Focus it, then press as without a target: Element Send Keys can type a named key into
+                    // the field as text (tauri-plugin-wdio-webdriver 1.4 only appends to the value).
+                    await this.retrying(timeout, action.target, (id) => client.executeScript(domScript('dom-element'), [{ op: 'focus' }, elementRef(id)]));
                 }
+                await client.performActions(keyActions(keys));
+                await client.releaseActions().catch(() => undefined);
                 return {};
             }
             case 'wait_for':
-                await this.element(requireTarget(action), timeout, true);
+                await this.locate(requireTarget(action), timeout, { visible: true });
                 return {};
             case 'wait':
                 await sleep(Math.min(action.ms ?? 0, 30_000));
@@ -489,8 +586,8 @@ export class TauriWebDriver {
                 const expected = render(action.value, this.ctx.template);
                 let actual = '';
                 await expectWithin(timeout, async () => {
-                    const found = await this.element(target, 0, false);
-                    actual = (await client.getElementText(found.elementId)).trim();
+                    const id = await this.element(target, 0, false);
+                    actual = (await client.getElementText(id)).trim();
                     return matches(actual, expected, action.match);
                 }, () => `text to ${verb(action.match)} "${expected}", found "${clip(actual)}"`);
                 return {};
@@ -515,10 +612,59 @@ export class TauriWebDriver {
             }
             case 'screenshot':
                 return { screenshot: await this.screenshot() };
+            case 'upload':
+                await this.upload(action, timeout);
+                return {};
+            case 'drop_files':
+                await this.dropFiles(action, timeout);
+                return {};
             default:
                 throw new Unsupported(`'${action.type}' is not a tauri action`);
         }
     }
+    /**
+     * Sets the files of an `<input type=file>` (or the one a label names) through Element Send Keys,
+     * which W3C drivers accept for file inputs without a dialog, hidden ones included. A native Open
+     * dialog the app opens itself is out of WebDriver's reach, so any other target is refused.
+     */
+    async upload(action, timeout) {
+        const client = this.requireClient();
+        const paths = resolveFileEntries(action.files, this.ctx.template).map((file) => file.path);
+        const id = await this.element(requireTarget(action), timeout, false);
+        const found = (await client.executeScript(FILE_INPUT_SCRIPT, [elementRef(id)]));
+        if (!found?.input) {
+            throw new Unsupported('the target is not a file input; tauri apps are driven over WebDriver, which cannot fill a native Open dialog. Target the <input type=file> or its label');
+        }
+        if (paths.length > 1 && !found.multiple)
+            throw new Error(`the file input takes one file, but the action hands over ${paths.length}`);
+        await this.setInputFiles(elementIdOf(found.input), paths);
+    }
+    /** Element Send Keys with the paths, one per line, then a check that the input holds them all. */
+    async setInputFiles(inputId, paths) {
+        const client = this.requireClient();
+        await client.elementSendKeys(inputId, paths.join('\n'));
+        const count = await client.executeScript('return arguments[0].files ? arguments[0].files.length : -1;', [elementRef(inputId)]);
+        if (count !== paths.length) {
+            throw new Unsupported(`this app's WebDriver did not set the files of the input (it holds ${String(count)} of ${paths.length}); it may not support file uploads`);
+        }
+    }
+    /** `drop_files` as on the web: the files go through a hidden input, then drag events carry them to the target. */
+    async dropFiles(action, timeout) {
+        const client = this.requireClient();
+        const paths = resolveFileEntries(action.files, this.ctx.template).map((file) => file.path);
+        const target = await this.element(requireTarget(action), timeout, false);
+        const source = elementIdOf(await client.executeScript(DROP_SOURCE_SCRIPT, []));
+        try {
+            await this.setInputFiles(source, paths);
+            const accepted = await client.executeScript(DROP_SCRIPT, [elementRef(target), elementRef(source)]);
+            if (accepted !== true) {
+                throw new Error('nothing in the app accepted the dropped files (no drag handler cancelled dragover or drop); target the drop zone itself');
+            }
+        }
+        finally {
+            await client.executeScript('arguments[0].remove();', [elementRef(source)]).catch(() => undefined);
+        }
+    }
     async focusWindow(action) {
         const client = this.requireClient();
         const timeout = action.timeout_ms ?? this.ctx.timeouts.actionMs;
@@ -550,29 +696,37 @@ export class TauriWebDriver {
         }, () => wanted === null
             ? `window ${action.index} to be open, found ${count} window(s)`
             : `a window whose title ${action.match === 'equals' ? 'equals' : 'contains'} "${wanted}", found ${titles.map((t) => `"${clip(t)}"`).join(', ') || 'none'}`);
-        this.refElements.clear();
+        this.forgetSnapshot();
+    }
+    /** The last snapshot's refs stop resolving (another window, or the app closed). */
+    forgetSnapshot() {
+        this.snapshotId = null;
+        this.refIndexes.clear();
     }
     async find(target) {
         validateDomTarget(target);
         const client = this.requireClient();
-        const byElement = new Map([...this.refElements].map(([ref, id]) => [id, ref]));
+        const refByIndex = new Map([...this.refIndexes].map(([ref, index]) => [index, ref]));
         for (const candidate of domCandidates(target)) {
-            const found = await domFindAll(client, candidate, this.renderText, 20);
-            if (found.count === 0)
-                continue;
             const nth = candidate.nth;
-            const ids = nth === undefined ? found.elementIds : found.elementIds.slice(nth, nth + 1);
-            const refs = ids.map((id) => byElement.get(id)).filter((ref) => ref !== undefined);
-            return { count: nth === undefined ? found.count : ids.length, refs };
+            const request = domLocateRequest(candidate, this.renderText, Math.max(FIND_LIMIT, (nth ?? 0) + 1));
+            const found = parseDomMatches(await client.executeScript(domScript('dom-locate'), [this.snapshotId ? { ...request, snapshot: this.snapshotId } : request]));
+            if (found.count <= (nth ?? 0))
+                continue;
+            const indexes = nth === undefined ? found.snapshotIndexes.slice(0, FIND_LIMIT) : found.snapshotIndexes.slice(nth, nth + 1);
+            const refs = indexes.map((index) => refByIndex.get(index)).filter((ref) => ref !== undefined);
+            return { count: nth === undefined ? found.count : 1, refs };
         }
         return { count: 0, refs: [] };
     }
     async snapshot(options = {}) {
         const client = this.requireClient();
+        const id = domToken();
         const raw = (await client.executeScript(domScript('dom-snapshot'), [
             {
                 ...(options.depth !== undefined ? { depth: options.depth } : {}),
                 ...(options.includeHidden !== undefined ? { includeHidden: options.includeHidden } : {}),
+                keep: id,
             },
         ]));
         const built = buildDomSnapshot(raw, {
@@ -580,7 +734,8 @@ export class TauriWebDriver {
             ...(options.maxChars !== undefined ? { maxChars: options.maxChars } : {}),
             appId: this.ctx.job.app?.id || null,
         });
-        this.refElements = built.elements;
+        this.snapshotId = id;
+        this.refIndexes = built.indexes;
         return built.snapshot;
     }
     async screen() {
@@ -616,18 +771,33 @@ export class TauriWebDriver {
     source() {
         return this.requireClient().getPageSource();
     }
-    beginStep(_index) { }
-    debug(_index) {
-        return undefined;
+    beginStep(index) {
+        this.stepStarts.push({ index, at: Date.now() });
+    }
+    /** While recording, where a step starts in the video (Tauri steps capture no logs); none for a step it does not show. */
+    debug(index) {
+        const offset = this.recorder ? stepStartOffset(this.recorder, this.stepStarts, index) : undefined;
+        return offset !== undefined ? { video_offset_secs: offset } : undefined;
     }
-    /** Tauri jobs record no video (contracts §L). */
     async stopRecording() {
-        return undefined;
+        if (!this.recorder || this.videoStopped)
+            return this.videoPath;
+        this.videoStopped = true;
+        this.videoPath = await this.recorder.stop();
+        if (!this.videoPath)
+            this.recorder.cleanup();
+        return this.videoPath;
     }
     async dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
+        if (this.recorder && !this.videoStopped) {
+            // Not fetched by the executor (the job ended early): discard it.
+            this.videoStopped = true;
+            await this.recorder.stop().catch(() => undefined);
+            this.recorder.cleanup();
+        }
         await this.closeApp();
         if (this.driverProcess)
             killProcessTree(this.driverProcess.child.pid);
@@ -640,7 +810,7 @@ export class TauriWebDriver {
     async closeApp() {
         const client = this.client;
         this.client = null;
-        this.refElements.clear();
+        this.forgetSnapshot();
         if (client)
             await Promise.race([client.deleteSession().catch(() => undefined), sleep(10_000)]);
         const app = this.app;