@leera.io/qa-runner 1.1.0 → 1.4.0

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/dom-element.js

@@ -0,0 +1,47 @@
+/*
+ * Runner-owned script for element operations WebDriver servers disagree on (Tauri, contracts §L).
+ * Executed with W3C `execute/sync` as `return (<this file>).apply(null, arguments);`, never
+ * with user-provided script. The element comes in as a W3C element reference (the second
+ * argument), which every server resolves; nothing but plain JSON goes back.
+ *
+ * request: { op: 'focus' }    focuses the element, so key actions reach it; a text field that
+ *                             gains focus gets the caret at its end, as Element Send Keys does
+ *          { op: 'select' }   selects an <option> and fires input and change at its list, as an
+ *                             option click does (tauri-plugin-wdio-webdriver 1.4's click does not)
+ * returns: { focused: boolean } | { selected: boolean }
+ * throws:  Error('element not interactable: …') when the element cannot take it
+ */
+(function domElement(request, element) {
+  if (element?.nodeType !== 1 || !element.isConnected) throw new Error('stale element reference: the element is not in the page');
+  const op = request?.op;
+
+  if (op === 'focus') {
+    const page = element.ownerDocument;
+    if (page.activeElement !== element) {
+      if (typeof element.focus === 'function') element.focus();
+      if ((element.tagName === 'INPUT' || element.tagName === 'TEXTAREA') && typeof element.value === 'string') {
+        try {
+          element.setSelectionRange(element.value.length, element.value.length);
+        } catch {
+          // Inputs such as email and number have no caret to place.
+        }
+      }
+    }
+    if (page.activeElement !== element) throw new Error('element not interactable: it cannot take keyboard focus');
+    return { focused: true };
+  }
+
+  if (op === 'select') {
+    if (element.tagName !== 'OPTION') throw new Error('the element is not an option');
+    const list = element.closest('select');
+    if (!list) throw new Error('the option is not in a select list');
+    if (element.matches(':disabled') || list.matches(':disabled')) throw new Error('element not interactable: the option is disabled');
+    const before = element.selected;
+    element.selected = true;
+    list.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+    if (!before) list.dispatchEvent(new Event('change', { bubbles: true }));
+    return { selected: element.selected };
+  }
+
+  throw new Error(`unknown element operation '${op}'`);
+})

package/dist/src/drivers/webdriver/dom-locate.js

@@ -1,14 +1,24 @@
 /*
  * Runner-owned locator script for WebDriver-backed web views (Tauri, contracts §L).
  * Executed with W3C `execute/sync` as `return (<this file>).apply(null, arguments);`, never
- * with user-provided script. It takes one request object and returns plain JSON plus DOM
- * elements, which WebDriver serializes as element references.
+ * with user-provided script. It returns plain JSON only, never DOM elements: WebDriver servers
+ * disagree on those (tauri-plugin-wdio-webdriver 1.4 returns each as null). The element the
+ * runner needs a reference for is tagged `data-qa-runner-mark="<token>"` instead, for W3C Find
+ * Elements to return; the runner then removes the tag with `{ unmark: true }`.
  *
- * request: { target: { css | text | test_id | xpath, exact? }, limit? }
- * returns: { count, elements: Element[] (at most `limit`), visible: boolean[] }
- * throws:  Error('invalid css selector: …' | 'invalid xpath: …' | 'the target names no locator')
+ * request, one of:
+ *   { target: { css | text | test_id | xpath, exact? }, limit?, mark?, snapshot? }
+ *   { ref: { snapshot, index }, mark? }   the element a snapshot kept (dom-snapshot.js `keep`)
+ *   { unmark: true }                      removes every tag
+ * mark:     { token, nth, visible? }   tags match `nth` (with `visible: true`, only when visible)
+ * snapshot: the id of the snapshot kept in the page; each returned match gets its index there
+ * returns:  { count, visible: boolean[] (at most `limit`), marked, snapshot_indexes? } |
+ *           { unmarked }
+ * throws:   Error('invalid css selector: …' | 'invalid xpath: …' | 'the target names no locator')
  */
 (function domLocate(request) {
+  const MARK = 'data-qa-runner-mark';
+  const KEPT = Symbol.for('qa-runner.snapshot');
   const target = (request?.target) || {};
   const limit = Math.max(1, Math.min(1000, Number((request?.limit) || 50)));
   const SKIP = { SCRIPT: 1, STYLE: 1, NOSCRIPT: 1, TEMPLATE: 1, HEAD: 1, META: 1, LINK: 1, TITLE: 1 };
@@ -101,8 +111,24 @@
     return out;
   }
 
+  /** The element a snapshot kept at `index`, while it is still in the page. */
+  function byRef(ref) {
+    const kept = window[KEPT];
+    const element = kept && kept.id === ref.snapshot ? kept.elements[Number(ref.index)] : null;
+    return element?.isConnected ? [element] : [];
+  }
+
+  function clearMarks() {
+    const marked = document.querySelectorAll(`[${MARK}]`);
+    for (let i = 0; i < marked.length; i += 1) marked[i].removeAttribute(MARK);
+    return marked.length;
+  }
+
+  if (request?.unmark) return { unmarked: clearMarks() };
+
   let found;
-  if (typeof target.css === 'string') found = byCss(target.css);
+  if (request?.ref) found = byRef(request.ref);
+  else if (typeof target.css === 'string') found = byCss(target.css);
   else if (typeof target.text === 'string') found = byText(target.text, target.exact === true);
   else if (typeof target.test_id === 'string') found = byTestId(target.test_id);
   else if (typeof target.xpath === 'string') found = byXpath(target.xpath);
@@ -111,5 +137,24 @@
   const elements = found.slice(0, limit);
   const visible = [];
   for (let j = 0; j < elements.length; j += 1) visible.push(isVisible(elements[j]));
-  return { count: found.length, elements: elements, visible: visible };
+  const result = { count: found.length, visible: visible, marked: false };
+
+  const mark = request?.mark;
+  if (mark && typeof mark.token === 'string') {
+    // A tag left behind by an interrupted call must not be found instead.
+    clearMarks();
+    const nth = Math.max(0, Number(mark.nth) || 0);
+    const element = found[nth];
+    if (element && (mark.visible !== true || (nth < visible.length ? visible[nth] : isVisible(element)))) {
+      element.setAttribute(MARK, mark.token);
+      result.marked = true;
+    }
+  }
+
+  if (typeof request?.snapshot === 'string') {
+    const kept = window[KEPT];
+    const list = kept && kept.id === request.snapshot ? kept.elements : [];
+    result.snapshot_indexes = elements.map((element) => list.indexOf(element));
+  }
+  return result;
 })

package/dist/src/drivers/webdriver/dom-snapshot.js

@@ -5,13 +5,14 @@
  * into a session snapshot (plan §7.3): role from ARIA or the tag, accessible name, text
  * (≤80 characters), data-testid, id, bounds and state. Invisible elements are dropped unless
  * `includeHidden`; layout-only elements are hoisted; depth and node count are capped.
+ * It returns plain JSON only (see dom-locate.js): with `keep`, the nodes' elements stay in the
+ * page under that id, for dom-locate.js to resolve a ref (`{ ref: { snapshot, index: i } }`).
  *
- * request: { depth?, includeHidden?, maxNodes?, viewportOnly? }
- * returns: { viewport: {width, height, scale}, url, title, truncated, count,
- *            nodes: RawNode[], elements: Element[] }
+ * request: { depth?, includeHidden?, maxNodes?, viewportOnly?, keep? }
+ * returns: { viewport: {width, height, scale}, url, title, truncated, count, nodes: RawNode[] }
  * RawNode: { i, role, name?, text?, test_id?, id?, bounds?, state?, xpath,
  *            test_id_count?, test_id_index?, id_selector?, id_count?, text_key?, text_count?, text_index?,
- *            children? }  (`i` indexes `elements`)
+ *            children? }  (`i` indexes the kept elements)
  */
 (function domSnapshot(request) {
   const options = request || {};
@@ -372,5 +373,7 @@
   if (nodes.length === 1 && elements[nodes[0].i] === document.body && nodes[0].role === 'generic' && !nodes[0].name) {
     nodes = nodes[0].children || [];
   }
-  return { viewport: viewport, url: String(location.href), title: document.title, truncated: truncated, count: count, nodes: nodes, elements: elements };
+  // One snapshot is kept at a time: a new one (or a page load) makes the previous refs stale.
+  if (typeof options.keep === 'string') window[Symbol.for('qa-runner.snapshot')] = { id: options.keep, elements: elements };
+  return { viewport: viewport, url: String(location.href), title: document.title, truncated: truncated, count: count, nodes: nodes };
 })

package/dist/src/drivers/webdriver/dom-tree.js

@@ -1,6 +1,5 @@
 import { clampMaxChars, clipText, renderSnapshotText, } from '../snapshot/format.js';
 import { MAX_XPATH_CHARS } from './dom.js';
-import { elementIdOf } from './locate.js';
 /** The screen a DOM snapshot (or its viewport-only form) describes. */
 export function domScreen(raw, appId = null) {
     const width = numberOrNull(raw.viewport?.width);
@@ -48,23 +47,16 @@ export function suggestFor(node) {
         suggest.fallbacks = [next.count > 1 ? { ...next.target, nth: next.index } : next.target];
     return { suggest, alternatives, fragile: true };
 }
-/** Builds the snapshot and the ref → element map from the script's result. */
+/** Builds the snapshot and the ref → element index map from the script's result. */
 export function buildDomSnapshot(raw, options = {}) {
-    const rawElements = Array.isArray(raw.elements) ? raw.elements : [];
-    const elements = new Map();
+    const indexes = new Map();
     const sources = new Map();
     let next = 1;
     const convert = (node) => {
         const ref = `e${next++}`;
-        const reference = rawElements[node.i];
-        if (reference !== undefined) {
-            try {
-                elements.set(ref, elementIdOf(reference));
-            }
-            catch {
-                // Not an element reference: the node stays in the tree without a ref target.
-            }
-        }
+        // A node without an element index stays in the tree without a ref target.
+        if (Number.isInteger(node.i) && node.i >= 0)
+            indexes.set(ref, node.i);
         sources.set(ref, node);
         const out = { ref, role: String(node.role || 'generic') };
         if (node.name)
@@ -92,7 +84,7 @@ export function buildDomSnapshot(raw, options = {}) {
     const rendered = renderSnapshotText(root, clampMaxChars(options.maxChars));
     const refs = {};
     for (const [ref, node] of sources) {
-        if (!rendered.refs.has(ref) || !elements.has(ref))
+        if (!rendered.refs.has(ref) || !indexes.has(ref))
             continue;
         refs[ref] = { locate: { dom_ref: ref }, ...suggestFor(node), bounds: node.bounds ?? null };
     }
@@ -108,7 +100,7 @@ export function buildDomSnapshot(raw, options = {}) {
             element_count: typeof raw.count === 'number' ? raw.count : sources.size,
             truncated: raw.truncated === true || rendered.truncated,
         },
-        elements,
+        indexes,
     };
 }
 /** The ref a `locate` from a DOM snapshot names, or null. */

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

@@ -1,15 +1,23 @@
+import { randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { setTimeout as sleep } from 'node:timers/promises';
 import { Unsupported } from '../driver.js';
 import { elementIdOf } from './locate.js';
 /**
  * Locators for WebDriver-backed web views (Tauri, contracts §L). Elements are found by the
- * runner-owned `dom-locate.js`, executed with W3C `execute/sync`; no other script is ever run.
+ * runner-owned `dom-locate.js`, executed with W3C `execute/sync`; the only other scripts ever
+ * run are the runner-owned `dom-snapshot.js` and `dom-element.js`.
+ *
+ * The scripts return plain JSON, never DOM elements. W3C serializes a script's elements as
+ * element references, but tauri-plugin-wdio-webdriver (the macOS path) returns each as null.
+ * So the element the runner acts on is tagged by `dom-locate.js` and fetched with W3C Find
+ * Elements, which every server implements, and the tag is removed straight after.
  */
 export const DOM_LOCATORS = ['css', 'text', 'test_id', 'xpath'];
 export const MAX_XPATH_CHARS = 500;
-/** Elements one locate call returns (a `nth` beyond it is fetched on demand). */
+/** Matches one locate call reports visibility for (raised for a larger `nth`). */
 export const DOM_LOCATE_LIMIT = 50;
+/** The attribute `dom-locate.js` tags an element with, for Find Elements to return it. */
+export const MARK_ATTRIBUTE = 'data-qa-runner-mark';
 const scripts = new Map();
 /** The file as shipped next to this module (copied into dist by the build). */
 export function domScriptSource(name) {
@@ -84,12 +92,13 @@ export function parseDomMatches(raw) {
     if (!raw || typeof raw !== 'object')
         throw new Error('the locator script returned nothing');
     const value = raw;
-    const elements = Array.isArray(value.elements) ? value.elements : [];
     const visible = Array.isArray(value.visible) ? value.visible.map((v) => v === true) : [];
+    const indexes = Array.isArray(value.snapshot_indexes) ? value.snapshot_indexes : [];
     return {
-        count: typeof value.count === 'number' ? value.count : elements.length,
-        elementIds: elements.map(elementIdOf),
+        count: typeof value.count === 'number' ? value.count : visible.length,
         visible,
+        marked: value.marked === true,
+        snapshotIndexes: indexes.map((index) => (Number.isInteger(index) ? index : -1)),
     };
 }
 /** Candidates in order: the target itself, then its fallbacks. */
@@ -97,34 +106,38 @@ export function domCandidates(target) {
     const { fallbacks, locate: _locate, ...primary } = target;
     return [primary, ...(fallbacks ?? []).map(({ fallbacks: _nested, locate: _l, ...rest }) => rest)];
 }
-/** All matches of one target (no fallbacks). */
-export async function domFindAll(client, target, render, limit) {
-    const raw = await client.executeScript(domScript('dom-locate'), [domLocateRequest(target, render, limit ?? Math.max(DOM_LOCATE_LIMIT, (target.nth ?? 0) + 1))]);
-    return parseDomMatches(raw);
+/** A random token for a tag or a kept snapshot. */
+export function domToken() {
+    return randomBytes(8).toString('hex');
+}
+/**
+ * Runs one `dom-locate.js` request. For an element, match `nth` is tagged, fetched with W3C Find
+ * Elements and untagged again; it stays null when the match went away in between.
+ */
+export async function domQuery(client, request, nth, want = {}) {
+    const token = want.element ? domToken() : null;
+    const mark = token ? { mark: { token, nth, visible: want.visible === true } } : {};
+    const matches = parseDomMatches(await client.executeScript(domScript('dom-locate'), [{ ...request, ...mark }]));
+    if (!token || !matches.marked)
+        return { ...matches, elementId: null };
+    try {
+        const found = await client.findElements('css selector', `[${MARK_ATTRIBUTE}="${token}"]`);
+        return { ...matches, elementId: found.length > 0 ? elementIdOf(found[0]) : null };
+    }
+    finally {
+        await client.executeScript(domScript('dom-locate'), [{ unmark: true }]).catch(() => undefined);
+    }
 }
 /** One pass over the target and its fallbacks; null when nothing matches at `nth`. */
-export async function domLocateOnce(client, target, render) {
+export async function domLocateOnce(client, target, render, want = {}) {
     for (const candidate of domCandidates(target)) {
-        const found = await domFindAll(client, candidate, render);
         const nth = candidate.nth ?? 0;
-        const elementId = found.elementIds[nth];
-        if (elementId)
-            return { elementId, target: candidate, count: found.count, visible: found.visible[nth] ?? false };
+        const found = await domQuery(client, domLocateRequest(candidate, render, Math.max(DOM_LOCATE_LIMIT, nth + 1)), nth, want);
+        if (found.count > nth)
+            return { target: candidate, count: found.count, visible: found.visible[nth] ?? false, elementId: found.elementId };
     }
     return null;
 }
-/** Polls until the target (or a fallback) matches (and is visible, when asked) or the time is up. */
-export async function domLocate(client, target, timeoutMs, options = {}) {
-    const deadline = Date.now() + timeoutMs;
-    for (;;) {
-        const found = await domLocateOnce(client, target, options.render);
-        if (found && (!options.visible || found.visible))
-            return found;
-        if (Date.now() >= deadline)
-            return options.visible ? null : found;
-        await sleep(options.pollMs ?? 200);
-    }
-}
 export function describeDomTarget(target) {
     if (target.test_id !== undefined)
         return `test id "${target.test_id}"`;

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)

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

@@ -9,12 +9,41 @@ import { clip, errorMessage, expectWithin, matches, renderLaunchArgs } from './c
 import { DesktopAppiumDriver, validateNativeAction } from './desktop-appium.js';
 import { Blocked, LaunchRefused, } from './driver.js';
 import { emptyScreen } from './snapshot/format.js';
-import { windowsKeyActions } from './webdriver/desktop-keys.js';
+import { windowsKeyActions, windowsOpenDialogEntries } from './webdriver/desktop-keys.js';
 import { elementIdOf } from './webdriver/locate.js';
 import { NATIVE_DESKTOP_ACTIONS } from './webdriver/native-actions.js';
-import { describeWindowsTarget, WINDOWS_LOCATORS, windowsSelectors, xpathLiteral } from './webdriver/native-locate.js';
+import { describeWindowsTarget, nativeLocate, WINDOWS_LOCATORS, windowsSelectors, xpathLiteral } from './webdriver/native-locate.js';
 import { openSession, webdriverMessage } from './webdriver/session.js';
 import { windowsSnapshotFromXml } from './webdriver/xml-tree-desktop.js';
+/** The AutomationId of the File name box of the common Open dialog. */
+export const OPEN_DIALOG_FILE_NAME_BOX = '1148';
+/**
+ * Picks files in the common Open dialog: each entry goes into its File name box (replacing what
+ * is there) followed by Enter; the dialog must be gone afterwards, or it refused the files.
+ */
+export async function fillWindowsOpenDialog(client, folder, names, timeoutMs, pauseMs = 500) {
+    const box = await nativeLocate(client, windowsSelectors, { automation_id: OPEN_DIALOG_FILE_NAME_BOX }, timeoutMs);
+    if (!box) {
+        throw new Error('no Open dialog appeared after the click (its File name box was not found); target the control that opens the dialog');
+    }
+    const selectAll = windowsKeyActions({ modifiers: ['ctrl'], key: 'a' });
+    const enter = windowsKeyActions({ modifiers: [], key: 'enter' });
+    for (const entry of windowsOpenDialogEntries(folder, names)) {
+        await client.elementClick(box.elementId).catch(() => undefined);
+        await windowsCommand(client, 'keys', { actions: [...selectAll, { text: entry }, ...enter] });
+        await sleep(pauseMs);
+    }
+    const deadline = Date.now() + Math.max(timeoutMs, 1_000);
+    for (;;) {
+        const open = await client.isElementDisplayed(box.elementId).catch(() => false);
+        if (!open)
+            return;
+        if (Date.now() >= deadline) {
+            throw new Error(`the Open dialog did not accept the files (${names.join(', ')}); it is still open`);
+        }
+        await sleep(300);
+    }
+}
 /** Runs an Appium Windows driver `windows:` extension command. */
 export function windowsCommand(client, command, args = {}) {
     if (!/^[a-zA-Z]+$/.test(command))
@@ -106,7 +135,7 @@ export class WindowsAppiumDriver extends DesktopAppiumDriver {
     wadUrl = null;
     disposed = false;
     constructor(ctx, appium, deps = {}) {
-        super(ctx, appium);
+        super(ctx, appium, deps.recorder);
         this.deps = deps;
     }
     get ops() {
@@ -193,6 +222,9 @@ export class WindowsAppiumDriver extends DesktopAppiumDriver {
                 case 'focus_window':
                     await this.focusWindow(action);
                     return {};
+                case 'upload':
+                    await this.upload(action);
+                    return {};
                 default:
                     return await this.runShared(action);
             }
@@ -201,6 +233,9 @@ export class WindowsAppiumDriver extends DesktopAppiumDriver {
             throw this.translate(error);
         }
     }
+    pickInOpenDialog(folder, names, timeoutMs) {
+        return fillWindowsOpenDialog(this.requireClient(), folder, names, timeoutMs);
+    }
     /**
      * Switches to the app window with that title; a window the app's session does not list (a
      * dialog of another process) is attached to through a desktop session and `appTopLevelWindow`.

package/dist/src/executor.js

@@ -1,5 +1,6 @@
 import { setTimeout as sleep } from 'node:timers/promises';
 import { describe, errorMessage, firstLine, screenshotName } from './drivers/common.js';
+import { mp4Seconds } from './devices/mp4.js';
 import { isPlatform } from './devices/types.js';
 import { Blocked, LaunchRefused } from './drivers/driver.js';
 import { BrowserPool, webPlaywrightFactory } from './drivers/web-playwright.js';
@@ -15,6 +16,7 @@ export function templateContextFor(job) {
         randomEmailDomain: job.environment.random_email_domain ?? null,
         username: job.credential?.username ?? null,
         password: job.credential?.password ?? null,
+        otp: job.credential?.otp ?? null,
         runId: job.run.id,
         appId: job.app?.id ?? null,
         data: job.data?.refs ?? {},
@@ -36,12 +38,15 @@ export function jobPlatform(job) {
     return platform;
 }
 export function jobContext(job, options) {
+    const template = templateContextFor(job);
+    if (options.files)
+        template.files = options.files.files;
     return {
         jobId: job.job.id,
         platform: jobPlatform(job),
         lease: options.lease,
         job,
-        template: templateContextFor(job),
+        template,
         timeouts: { actionMs: options.actionTimeoutMs, jobMs: options.jobTimeoutMs },
         headless: options.headless,
         ...(options.proxy ? { proxy: options.proxy } : {}),
@@ -50,6 +55,7 @@ export function jobContext(job, options) {
         log: options.log,
         ...(options.app ?? {}),
         ...(options.buildDownloadUrl ? { buildDownloadUrl: options.buildDownloadUrl } : {}),
+        ...(options.files ? { files: options.files } : {}),
     };
 }
 /**
@@ -178,6 +184,8 @@ export async function executeSteps(driver, script, options, shouldStop, redact)
         videoPath = await driver.stopRecording().catch(() => undefined);
         await driver.dispose().catch(() => undefined);
     }
+    if (videoPath)
+        keepOffsetsInVideo(steps, mp4Seconds(videoPath));
     return {
         steps,
         elapsedSecs: Math.max(1, Math.round((Date.now() - started) / 1000)),
@@ -185,6 +193,20 @@ export async function executeSteps(driver, script, options, shouldStop, redact)
         ...(videoPath ? { videoPath } : {}),
     };
 }
+/**
+ * Places no step past the end of the video (`seconds` long, null when unknown): a video can end a
+ * moment before a step that began just before it stopped, and that step is then shown at its end.
+ */
+export function keepOffsetsInVideo(steps, seconds) {
+    if (seconds === null)
+        return;
+    const end = Math.floor(seconds * 10) / 10;
+    for (const step of steps) {
+        const offset = step.debug?.video_offset_secs;
+        if (offset !== undefined && offset > end)
+            step.debug = { ...step.debug, video_offset_secs: end };
+    }
+}
 /** Prefixes the action's description; template problems block the step rather than fail it. */
 async function runAction(driver, action) {
     try {