@leera.io/qa-runner 1.1.0 → 1.2.0

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 { ensureFfmpeg } from '../devices/ffmpeg.js';
+import { ScreenRecorder } from '../devices/screen-record.js';
 import { loadTauriSettings, MACOS_PLUGIN_BLOCKED, tauriBackend, tauriCapabilities, tauriDriverArgv, } from '../devices/tauri.js';
 import { homePaths } from '../home.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, 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')
@@ -134,7 +140,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 +149,18 @@ 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 the recording started; each step's offset into the video counts from it. */
+    startedAt = Date.now();
+    offsets = new Map();
     constructor(ctx, backend, deps = {}) {
         this.ctx = ctx;
         this.backend = backend;
@@ -227,8 +240,40 @@ 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() {
+        this.startedAt = Date.now();
+        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 ?? defaultRecorder(this.paths, this.ctx.log))(os, display);
+        if (!recorder)
+            return;
+        this.startedAt = Date.now();
+        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 +346,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 +412,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 +471,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 +484,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 +494,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 +512,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 +536,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 +565,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 {};
@@ -550,29 +626,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 +664,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 +701,33 @@ export class TauriWebDriver {
     source() {
         return this.requireClient().getPageSource();
     }
-    beginStep(_index) { }
-    debug(_index) {
-        return undefined;
+    beginStep(index) {
+        this.offsets.set(index, Math.round((Date.now() - this.startedAt) / 100) / 10);
+    }
+    /** While recording, a step's start time in the video (Tauri steps capture no logs). */
+    debug(index) {
+        const offset = this.offsets.get(index);
+        return offset !== undefined && this.recorder ? { 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 +740,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;
@@ -649,6 +749,13 @@ 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/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. */