@leera.io/qa-runner 1.2.0 → 1.4.0

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

@@ -13,10 +13,11 @@ import { ensureDisplay, hostDevice } from '../devices/desktop.js';
 import { homePaths } from '../home.js';
 import { playwrightVersion } from '../version.js';
 import { LOCAL_PATHS_REFUSED } from './android-appium.js';
-import { clip, errorMessage, expectWithin, firstLine, matches, render, renderLaunchArgs } from './common.js';
+import { clip, errorMessage, expectWithin, firstLine, matches, render, renderLaunchArgs, stepStartOffset } from './common.js';
 import { Blocked, LaunchRefused, Unsupported, } from './driver.js';
 import { webSnapshot } from './snapshot/aria.js';
-import { findOnPage, NO_FFMPEG_VIDEO, playwrightFfmpeg, runWebAction, WEB_ACTIONS } from './web-playwright.js';
+import { resolveFileEntries } from '../template.js';
+import { fileInputOf, findOnPage, locateAction, NO_FFMPEG_VIDEO, playwrightFfmpeg, runWebAction, uploadFiles, WEB_ACTIONS, } from './web-playwright.js';
 /** Electron DSL (contracts §K): web actions minus `goto`, plus launch, terminate and focus_window. */
 export const ELECTRON_ACTIONS = [...WEB_ACTIONS.filter((action) => action !== 'goto'), 'launch', 'terminate', 'focus_window'];
 export const ELECTRON_TARGETS = ['role', 'label', 'placeholder', 'text', 'test_id', 'css'];
@@ -142,6 +143,47 @@ function recordingOf(page, video, log) {
     });
     return recording;
 }
+/**
+ * Runs in the app's main process: the next Open dialog answers with `paths` instead of opening,
+ * once, then the real dialog is back. Self-contained, since Playwright sends its source.
+ */
+export function answerOpenDialog(electron, paths) {
+    const { dialog } = electron;
+    const holder = globalThis;
+    holder.__qaOpenDialog ??= {
+        showOpenDialog: dialog.showOpenDialog,
+        showOpenDialogSync: dialog.showOpenDialogSync,
+        answered: false,
+    };
+    const state = holder.__qaOpenDialog;
+    state.answered = false;
+    const restore = () => {
+        dialog.showOpenDialog = state.showOpenDialog;
+        dialog.showOpenDialogSync = state.showOpenDialogSync;
+    };
+    dialog.showOpenDialog = async () => {
+        state.answered = true;
+        restore();
+        return { canceled: false, filePaths: paths };
+    };
+    dialog.showOpenDialogSync = () => {
+        state.answered = true;
+        restore();
+        return paths;
+    };
+}
+/** Runs in the main process: whether the swapped dialog answered. */
+export function openDialogAnswered() {
+    return globalThis.__qaOpenDialog?.answered === true;
+}
+/** Runs in the main process: puts the real Open dialog back. */
+export function restoreOpenDialog(electron) {
+    const state = globalThis.__qaOpenDialog;
+    if (!state)
+        return;
+    electron.dialog.showOpenDialog = state.showOpenDialog;
+    electron.dialog.showOpenDialogSync = state.showOpenDialogSync;
+}
 /** The paint check, run in the window: settles once it is visible and has run two animation frames. */
 function paintCheck() {
     return new Promise((resolve) => {
@@ -154,21 +196,6 @@ function paintCheck() {
         tick();
     });
 }
-/**
- * Where a step starts in a recording, in seconds, or undefined when the recording does not show
- * it: the step ended before the recording's first frame, or began after the recording ended. A
- * step already running when the recording started (the one that relaunched the app) starts at 0.
- */
-export function stepVideoOffset(recording, begun, ended) {
-    // No frame yet: a window that never painted records only a closing frame, which shows no step.
-    if (recording.startedAt === null)
-        return undefined;
-    if (recording.endedAt !== null && begun >= recording.endedAt)
-        return undefined;
-    if (ended !== null && ended <= recording.startedAt)
-        return undefined;
-    return Math.max(0, Math.round((begun - recording.startedAt) / 100) / 10);
-}
 export class ElectronPlaywrightDriver {
     ctx;
     options;
@@ -529,10 +556,54 @@ export class ElectronPlaywrightDriver {
             case 'focus_window':
                 await this.focusWindow(action);
                 return {};
+            case 'upload':
+                await this.upload(action);
+                return {};
             default:
                 return runWebAction(this.requirePage(), action, this.ctx.template, this.ctx.timeouts.actionMs);
         }
     }
+    /**
+     * `upload` as on the web, and also through the app's own Open dialog: before the click, the main
+     * process's `dialog.showOpenDialog` and `showOpenDialogSync` are swapped for ones that answer with
+     * the files, then put back. Apps started over CDP have no main process to reach, so they only get
+     * the web way.
+     */
+    async upload(action) {
+        const page = this.requirePage();
+        const timeout = action.timeout_ms ?? this.ctx.timeouts.actionMs;
+        const paths = resolveFileEntries(action.files, this.ctx.template).map((file) => file.path);
+        const locator = await locateAction(page, action, this.ctx.template, timeout);
+        const electron = this.instance?.electron ?? null;
+        if (!electron || (await fileInputOf(locator, timeout)).input) {
+            await uploadFiles(page, locator, paths, timeout);
+            return;
+        }
+        await electron.evaluate(answerOpenDialog, paths);
+        try {
+            const chooser = page.waitForEvent('filechooser', { timeout }).catch(() => null);
+            await locator.click({ timeout });
+            const deadline = Date.now() + timeout;
+            for (;;) {
+                if (await electron.evaluate(openDialogAnswered).catch(() => false))
+                    return;
+                const opened = await Promise.race([chooser, sleep(200).then(() => undefined)]);
+                if (opened) {
+                    if (paths.length > 1 && !opened.isMultiple()) {
+                        throw new Error(`the file input takes one file, but the action hands over ${paths.length}`);
+                    }
+                    await opened.setFiles(paths, { timeout });
+                    return;
+                }
+                if (opened === null || Date.now() > deadline)
+                    break;
+            }
+            throw new Error("clicking the element opened neither a file chooser nor the app's Open dialog; target the <input type=file> or the button that opens the dialog");
+        }
+        finally {
+            await electron.evaluate(restoreOpenDialog).catch(() => undefined);
+        }
+    }
     async focusWindow(action) {
         if (!this.instance)
             throw new Error('the app is not running; start it with launch');
@@ -624,10 +695,7 @@ export class ElectronPlaywrightDriver {
     }
     videoOffset(index) {
         const recording = this.recordings.at(-1);
-        const i = this.stepStarts.findLastIndex((step) => step.index === index);
-        if (!recording || i < 0)
-            return undefined;
-        return stepVideoOffset(recording, this.stepStarts[i].at, this.stepStarts[i + 1]?.at ?? null);
+        return recording ? stepStartOffset(recording, this.stepStarts, index) : undefined;
     }
     /**
      * Closes the app (a video is only complete then) and returns the last recording. A relaunch

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,14 +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';
@@ -294,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);
@@ -302,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,12 +6,12 @@ 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 { ensureFfmpeg } from '../devices/ffmpeg.js';
-import { ScreenRecorder } from '../devices/screen-record.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, POLL_MS, 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, domLocateOnce, domLocateRequest, domQuery, domScript, domToken, elementRef, keyActions, parseDomMatches, validateDomTarget, webdriverKeys, } from './webdriver/dom.js';
@@ -42,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();
@@ -158,9 +182,8 @@ export class TauriWebDriver {
     recorder = null;
     videoStopped = false;
     videoPath;
-    /** When the recording started; each step's offset into the video counts from it. */
-    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 = [];
     constructor(ctx, backend, deps = {}) {
         this.ctx = ctx;
         this.backend = backend;
@@ -253,7 +276,6 @@ export class TauriWebDriver {
      * none downloaded) or when recording cannot start, the job runs without a video.
      */
     async startRecording() {
-        this.startedAt = Date.now();
         if (this.ctx.video === 'off')
             return;
         const os = this.screenOs();
@@ -262,10 +284,9 @@ export class TauriWebDriver {
             this.ctx.log.warn('video is not recorded: the job has no X display');
             return;
         }
-        const recorder = await (this.deps.recorder ?? defaultRecorder(this.paths, this.ctx.log))(os, display);
+        const recorder = await (this.deps.recorder ?? ffmpegRecorder(this.paths, this.ctx.log))(os, display);
         if (!recorder)
             return;
-        this.startedAt = Date.now();
         try {
             await recorder.start();
             this.recorder = recorder;
@@ -591,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;
@@ -702,12 +772,12 @@ export class TauriWebDriver {
         return this.requireClient().getPageSource();
     }
     beginStep(index) {
-        this.offsets.set(index, Math.round((Date.now() - this.startedAt) / 100) / 10);
+        this.stepStarts.push({ index, at: Date.now() });
     }
-    /** While recording, a step's start time in the video (Tauri steps capture no logs). */
+    /** 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.offsets.get(index);
-        return offset !== undefined && this.recorder ? { video_offset_secs: offset } : undefined;
+        const offset = this.recorder ? stepStartOffset(this.recorder, this.stepStarts, index) : undefined;
+        return offset !== undefined ? { video_offset_secs: offset } : undefined;
     }
     async stopRecording() {
         if (!this.recorder || this.videoStopped)
@@ -749,13 +819,6 @@ export class TauriWebDriver {
             killProcessTree(app.child.pid);
     }
 }
-/** ScreenRecorder with the ffmpeg on PATH or in the runner home (downloaded now when missing). */
-function defaultRecorder(paths, log) {
-    return async (os, display) => {
-        const ffmpeg = await ensureFfmpeg({ paths, log });
-        return ffmpeg ? new ScreenRecorder(ffmpeg, os, display ? { display } : {}) : null;
-    };
-}
 function nodePlatform(os) {
     if (os === 'macos')
         return 'darwin';

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

@@ -7,7 +7,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { chromium } from 'playwright-core';
 import { DebugCollector } from '../debug.js';
 import { BROWSER_DEVICE_ID } from '../devices/types.js';
-import { resolveUrl } from '../template.js';
+import { resolveFileEntries, resolveUrl } from '../template.js';
 import { clip, errorMessage, expectWithin, firstLine, matches, POLL_MS, render, requireTarget, verb, } from './common.js';
 import { Blocked, Unsupported, } from './driver.js';
 import { ariaRefSelector, refFromElementSnapshot, webScreen, webSnapshot } from './snapshot/aria.js';
@@ -31,6 +31,8 @@ export const WEB_ACTIONS = [
     'expect_url',
     'expect_title',
     'screenshot',
+    'upload',
+    'drop_files',
 ];
 export function launchBrowser(options) {
     return chromium.launch({
@@ -363,10 +365,107 @@ export async function runWebAction(page, action, ctx, defaultTimeout) {
         }
         case 'screenshot':
             return { screenshot: await page.screenshot({ type: 'png' }) };
+        case 'upload': {
+            const paths = resolveFileEntries(action.files, ctx).map((file) => file.path);
+            await uploadFiles(page, await find(page, action, ctx, timeout), paths, timeout);
+            return {};
+        }
+        case 'drop_files': {
+            const paths = resolveFileEntries(action.files, ctx).map((file) => file.path);
+            await dropFiles(page, await find(page, action, ctx, timeout), paths, timeout);
+            return {};
+        }
         default:
             throw new Error(`unsupported action '${action.type}'`);
     }
 }
+/** Whether a target is a file input (or a label for one), and whether it takes several files. */
+export async function fileInputOf(locator, timeout) {
+    return locator.evaluate((element) => {
+        const control = element instanceof HTMLLabelElement ? element.control : element;
+        const input = control instanceof HTMLInputElement && control.type === 'file';
+        return { input, multiple: input && control.multiple };
+    }, undefined, { timeout });
+}
+function tooMany(count) {
+    return new Error(`the file input takes one file, but the action hands over ${count}`);
+}
+/**
+ * Hands files to the app the way a person picking them would, without a dialog: straight into a
+ * file input (or the one a label names), else by clicking the target and answering the file
+ * chooser it opens.
+ */
+export async function uploadFiles(page, locator, paths, timeout) {
+    const target = await fileInputOf(locator, timeout);
+    if (target.input) {
+        if (paths.length > 1 && !target.multiple)
+            throw tooMany(paths.length);
+        await locator.setInputFiles(paths, { timeout });
+        return;
+    }
+    const chooser = page.waitForEvent('filechooser', { timeout }).catch(() => null);
+    await locator.click({ timeout });
+    const opened = await chooser;
+    if (!opened) {
+        throw new Error('clicking the element opened no file chooser; target the <input type=file>, its label, or the button that opens the chooser');
+    }
+    if (paths.length > 1 && !opened.isMultiple())
+        throw tooMany(paths.length);
+    await opened.setFiles(paths, { timeout });
+}
+/**
+ * Drops files onto a drop zone as if dragged from the desktop: the files go through a hidden file
+ * input (so Playwright reads them from disk, however large), then `dragenter`, `dragover` and
+ * `drop` carry them to the target. Fails when nothing on the page accepted the drop.
+ */
+export async function dropFiles(page, locator, paths, timeout) {
+    await locator.waitFor({ state: 'attached', timeout });
+    const source = await page.evaluateHandle(() => {
+        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;
+    });
+    try {
+        const input = source.asElement();
+        if (!input)
+            throw new Error('the page refused a file input for the drop');
+        await input.setInputFiles(paths, { timeout });
+        const accepted = await locator.evaluate((target, from) => {
+            const transfer = new DataTransfer();
+            for (const file of Array.from(from.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));
+            // A browser only drops where a handler cancelled dragover (or the drop itself).
+            const over = !target.dispatchEvent(new DragEvent('dragover', init));
+            const dropped = !target.dispatchEvent(new DragEvent('drop', init));
+            return over || dropped;
+        }, source, { timeout });
+        if (!accepted) {
+            throw new Error('nothing on the page accepted the dropped files (no drag handler cancelled dragover or drop); target the drop zone itself');
+        }
+    }
+    finally {
+        await source.evaluate((input) => input.remove()).catch(() => undefined);
+        await source.dispose().catch(() => undefined);
+    }
+}
+/** The element an action targets: its target, or the first fallback that appears in time. */
+export function locateAction(page, action, ctx, timeout) {
+    return find(page, action, ctx, timeout);
+}
 /** The primary target, or the first fallback that appears on the page before the timeout. */
 async function find(page, action, ctx, timeout) {
     const target = requireTarget(action);

package/dist/src/drivers/webdriver/actions.js

@@ -67,6 +67,7 @@ export const ANDROID_ACTIONS = [
     'expect_visible',
     'expect_hidden',
     'expect_text',
+    'add_files',
 ];
 /**
  * Deep link schemes a script may open (plan §3), checked on the rendered URL (android and ios):

package/dist/src/drivers/webdriver/desktop-keys.js

@@ -139,3 +139,30 @@ export function windowsKeyActions(chord) {
         ...[...mods].reverse().map((virtualKeyCode) => ({ virtualKeyCode, down: false })),
     ];
 }
+// ---------------------------------------------------------------------------------------------
+// The system Open dialog (`upload` on native apps)
+// ---------------------------------------------------------------------------------------------
+/**
+ * What to type into a Windows Open dialog's File name box, entry by entry (each followed by
+ * Enter): the file's full path for one file; for several, the folder (Enter shows it), then the
+ * names quoted, which is how the dialog takes a multiple selection.
+ */
+export function windowsOpenDialogEntries(folder, names, separator = '\\') {
+    if (names.length === 1)
+        return [`${folder.replace(/[\\/]+$/, '')}${separator}${names[0]}`];
+    return [folder, names.map((name) => `"${name}"`).join(' ')];
+}
+/**
+ * The chords that pick files in a macOS Open panel once the folder's path is on the pasteboard:
+ * Go to Folder (cmd+shift+g), paste, show the folder; then select its only file (down) or all of
+ * them (cmd+a), and open.
+ */
+export function macOpenDialogChords(count) {
+    return [
+        [{ modifiers: ['cmd', 'shift'], key: 'g' }],
+        [{ modifiers: ['cmd'], key: 'v' }],
+        [{ modifiers: [], key: 'return' }],
+        [count > 1 ? { modifiers: ['cmd'], key: 'a' } : { modifiers: [], key: 'down' }],
+        [{ modifiers: [], key: 'return' }],
+    ];
+}

package/dist/src/drivers/webdriver/ios-actions.js

@@ -49,6 +49,7 @@ export const IOS_ACTIONS = [
     'expect_visible',
     'expect_hidden',
     'expect_text',
+    'add_files',
 ];
 function requireTarget(action) {
     if (!action.target)

package/dist/src/drivers/webdriver/native-actions.js

@@ -28,6 +28,7 @@ export const NATIVE_DESKTOP_ACTIONS = [
     'expect_visible',
     'expect_hidden',
     'expect_text',
+    'upload',
 ];
 function requireTarget(action) {
     if (!action.target)