@leera.io/qa-runner 1.0.5 → 1.1.0

package/dist/src/capabilities.js

@@ -56,6 +56,8 @@ export function deriveLabels(devices) {
  * (contracts §H3). Web and Electron record webm (Playwright, contracts §K); mobile records mp4;
  * Tauri records no video and adds no feature beyond sessions (contracts §L). Native macOS and
  * Windows apps carry the Appium log on failed steps and record mp4 only with ffmpeg (contracts §M).
+ * `data_refs` = this runner fills test data, API URL and job placeholders on every platform
+ * (contracts §Q); the server gives such scripts only to runners labelled `data-refs`.
  */
 export function featuresFor(platforms, options = {}) {
     const features = [];
@@ -74,6 +76,7 @@ export function featuresFor(platforms, options = {}) {
         if (options.ffmpeg && !features.includes('video_mp4'))
             features.push('video_mp4');
     }
+    features.push('data_refs');
     return features;
 }
 export function buildCapabilities(devices, host, extraTools = {}, options = { ffmpeg: findFfmpeg() !== null }) {

package/dist/src/debug.js

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

package/dist/src/devices/android/adb.js

@@ -245,6 +245,10 @@ export class Adb {
     async pidof(serial, pkg) {
         return parsePidof(await this.shell(serial, ['pidof', assertPackage(pkg)], 10_000).catch(() => ''));
     }
+    /** Drops adb's connection to a device so it reconnects (the fix for one stuck `offline`). */
+    async reconnect(serial) {
+        await this.run(['-s', assertSerial(serial), 'reconnect'], 15_000).catch(() => undefined);
+    }
     async killEmulator(serial) {
         await this.run(['-s', assertSerial(serial), 'emu', 'kill'], 15_000).catch(() => undefined);
     }

package/dist/src/devices/android/emulator.js

@@ -140,6 +140,28 @@ export async function waitForBoot(adb, serial, timeoutMs, failed = () => null) {
         await sleep(2_000);
     }
 }
+/**
+ * Waits for a device adb lost for a moment (a busy emulator, a USB reconnect) to come back and
+ * finish booting. A device still `offline` after a few seconds gets its connection reset once.
+ */
+export async function waitForDeviceBack(adb, serial, { timeoutMs = 120_000, nudgeAfterMs = 10_000, intervalMs = 2_000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    const nudgeAt = Date.now() + nudgeAfterMs;
+    let nudged = false;
+    for (;;) {
+        const state = (await adb.devices().catch(() => [])).find((d) => d.serial === serial)?.state;
+        if (state === 'device' && (await adb.getprop(serial, 'sys.boot_completed').catch(() => '')) === '1')
+            return;
+        if (state === 'offline' && !nudged && Date.now() >= nudgeAt) {
+            nudged = true;
+            await adb.reconnect(serial);
+        }
+        if (Date.now() > deadline) {
+            throw new Error(`${serial} is ${state ?? 'not connected'} and did not come back within ${Math.round(timeoutMs / 1000)} s`);
+        }
+        await sleep(intervalMs);
+    }
+}
 export async function shutdownEmulator(adb, serial, timeoutMs = 60_000) {
     bootedHere.delete(serial);
     await adb.killEmulator(serial);

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

@@ -7,6 +7,7 @@ import { bundledDrivers } from '../appium/drivers.js';
 import { AppNotAvailable, resolveAppFile } from '../builds/install.js';
 import { androidInstallable } from '../builds/unpack.js';
 import { Adb, resolveAndroidSdk } from '../devices/android/adb.js';
+import { waitForDeviceBack } from '../devices/android/emulator.js';
 import { leaseAndroidDevice, listAndroidDevices } from '../devices/android/index.js';
 import { LogcatSink } from '../devices/android/logcat.js';
 import { dismissSystemErrorDialog } from '../devices/android/system-dialog.js';
@@ -33,6 +34,33 @@ export function appiumLogLines(text, redact) {
     });
     return { lines: kept, dropped: all.length - kept.length };
 }
+/** adb's words for a device it lost for the moment: `offline`, or missing from its list. */
+export function lostDevice(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /\bdevice offline\b|\bdevice ('[^']*' )?not found\b/i.test(message);
+}
+/**
+ * Opens the Appium session, and once more when adb lost the device while Appium set it up. A busy
+ * emulator or a USB reconnect drops the device for a few seconds, and Appium (which retries
+ * "not found" but not "offline") then fails the whole session. `recover` waits for the device;
+ * when it does not come back, the first error stands.
+ */
+export async function startSession(open, recover) {
+    try {
+        return await open();
+    }
+    catch (error) {
+        if (!lostDevice(error))
+            throw error;
+        try {
+            await recover();
+        }
+        catch {
+            throw error;
+        }
+        return open();
+    }
+}
 /** `android.sdk_path` from config.json, when the runner config has one. */
 export function configuredSdkPath(paths) {
     try {
@@ -191,14 +219,19 @@ export class AndroidAppiumDriver {
             const url = await this.appium.ensure();
             this.systemPort = await SYSTEM_PORTS.take();
             this.mjpegPort = await MJPEG_PORTS.take();
-            this.client = await openSession(url, uiautomator2Capabilities({
+            const capabilities = uiautomator2Capabilities({
                 serial,
                 appPackage: app.id,
                 appActivity: app.launch_activity,
                 systemPort: this.systemPort,
                 mjpegServerPort: this.mjpegPort,
                 newCommandTimeoutSecs: Math.max(300, Math.ceil((this.ctx.session?.idle_timeout_seconds ?? 0) + 60)),
-            }));
+            });
+            const adb = this.adb;
+            this.client = await startSession(() => openSession(url, capabilities), async () => {
+                this.ctx.log.warn('adb lost the device while Appium started the session; waiting for it to retry', { serial });
+                await waitForDeviceBack(adb, serial);
+            });
         }
         catch (error) {
             const log = this.appium.logSince(logOffset, 2_000).trim().split('\n').slice(-5).join(' | ');
@@ -423,16 +456,15 @@ export class AndroidAppiumDriver {
     debug(index, result) {
         const captured = this.logcat?.collector.for(index);
         const appium = result === 'failed' || result === 'blocked' ? this.appiumLogFor(index) : null;
-        if (!captured && !appium)
-            return undefined;
         const offset = this.offsets.get(index);
+        // While recording, the start time alone is kept: it is the step's place in the video.
         const debug = { ...captured, ...(offset !== undefined && this.recording ? { video_offset_secs: offset } : {}) };
         if (appium && appium.lines.length > 0) {
             debug.appium_log = appium.lines;
             if (appium.dropped > 0)
                 debug.dropped = { ...debug.dropped, appium_log: appium.dropped };
         }
-        return debug;
+        return Object.keys(debug).length > 0 ? debug : undefined;
     }
     /** The Appium log lines written from step `index`'s start to the next step's start (or now). */
     appiumLogFor(index) {

package/dist/src/drivers/common.js

@@ -1,5 +1,5 @@
 import { setTimeout as sleep } from 'node:timers/promises';
-import { renderTemplate } from '../template.js';
+import { renderTemplate, TemplateError } from '../template.js';
 export const POLL_MS = 200;
 /** Polls `check` until it holds or `timeout` passes, then fails with "expected …". */
 export async function expectWithin(timeout, check, expectation) {
@@ -21,8 +21,46 @@ export function requireTarget(action) {
 export function render(text, ctx) {
     return renderTemplate(text ?? '', ctx);
 }
+/** Schemes a rendered launch arg may not carry: they run code or read the runner's files. */
+const LOCAL_SCHEMES = /^(javascript|vbscript|file|data|blob)$/i;
+/**
+ * The scheme a URL parser would read from `text`. Parsers drop leading control characters and
+ * spaces, and tabs and line breaks anywhere, so `java<tab>script:` still counts as `javascript:`.
+ */
+function urlScheme(text) {
+    let start = 0;
+    while (start < text.length && text.charCodeAt(start) <= 0x20)
+        start += 1;
+    return /^([a-z][a-z0-9+.-]*):/i.exec(text.slice(start).replace(/[\t\n\r]/g, ''))?.[1];
+}
+/**
+ * Renders a `launch` action's args. An arg filled from a placeholder is checked once rendered,
+ * since a data value can hold anything: it must not become a URL (the whole arg, or the value of
+ * `--name=value`) with a scheme that runs code or reads local files, or a switch `reserved` names.
+ */
+export function renderLaunchArgs(args, renderText, reserved) {
+    return (args ?? []).map((arg, i) => {
+        const rendered = renderText(arg);
+        if (rendered === arg)
+            return rendered;
+        const value = /^-[^=\s]*=/.test(rendered) ? rendered.slice(rendered.indexOf('=') + 1) : rendered;
+        const scheme = urlScheme(value);
+        if (scheme && LOCAL_SCHEMES.test(scheme)) {
+            throw new TemplateError(`launch args[${i}] renders a ${scheme.toLowerCase()}: URL, which the runner does not pass to the app`);
+        }
+        if (reserved?.test(rendered))
+            throw new TemplateError(`launch args[${i}] renders '${rendered.split('=')[0]}', which is reserved for the runner`);
+        return rendered;
+    });
+}
+/**
+ * Compares visible text with what the script expects. Both sides are normalised to Unicode NFC,
+ * so an "é" typed as one character matches one the app renders as "e" plus a combining accent.
+ */
 export function matches(actual, expected, mode) {
-    return mode === 'equals' ? actual === expected : actual.includes(expected);
+    const have = actual.normalize('NFC');
+    const want = expected.normalize('NFC');
+    return mode === 'equals' ? have === want : have.includes(want);
 }
 export function verb(mode) {
     return mode === 'equals' ? 'equal' : 'contain';

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

@@ -6,7 +6,7 @@ import { findFfmpeg, ScreenRecorder } from '../devices/screen-record.js';
 import { homePaths } from '../home.js';
 import { renderTemplate } from '../template.js';
 import { APPIUM_LOG_MAX_BYTES, appiumLogLines, LOCAL_PATHS_REFUSED } from './android-appium.js';
-import { errorMessage } from './common.js';
+import { errorMessage, renderLaunchArgs } from './common.js';
 import { Blocked, LaunchRefused, NotFound, Unsupported } from './driver.js';
 import { runNativeAction } from './webdriver/native-actions.js';
 import { nativeFindAll, resolveNativeRef } from './webdriver/native-locate.js';
@@ -148,7 +148,7 @@ export class DesktopAppiumDriver {
             return [];
         validateNativeAction(this.platform, first);
         this.firstLaunchDone = true;
-        return (first.args ?? []).map(this.render);
+        return renderLaunchArgs(first.args, this.render);
     }
     /** Starts a whole-screen recording when the job wants video and ffmpeg is installed. */
     async startRecording() {
@@ -243,22 +243,21 @@ export class DesktopAppiumDriver {
         this.appiumLogOffsets.set(index, this.appium.logOffset());
     }
     debug(index, result) {
-        if (result !== 'failed' && result !== 'blocked')
-            return undefined;
-        const start = this.appiumLogOffsets.get(index);
-        if (start === undefined)
-            return undefined;
-        const later = [...this.appiumLogOffsets.entries()].filter(([i]) => i > index).map(([, offset]) => offset);
-        const end = later.length > 0 ? Math.min(...later) : undefined;
-        const appium = appiumLogLines(this.appium.logSince(start, APPIUM_LOG_MAX_BYTES, end), this.ctx.redact);
-        if (appium.lines.length === 0)
-            return undefined;
         const offset = this.offsets.get(index);
-        return {
-            appium_log: appium.lines,
-            ...(appium.dropped > 0 ? { dropped: { appium_log: appium.dropped } } : {}),
-            ...(offset !== undefined && this.recorder ? { video_offset_secs: offset } : {}),
-        };
+        // While recording, the start time alone is kept: it is the step's place in the video.
+        const debug = offset !== undefined && this.recorder ? { video_offset_secs: offset } : {};
+        const start = this.appiumLogOffsets.get(index);
+        if ((result === 'failed' || result === 'blocked') && start !== undefined) {
+            const later = [...this.appiumLogOffsets.entries()].filter(([i]) => i > index).map(([, at]) => at);
+            const end = later.length > 0 ? Math.min(...later) : undefined;
+            const appium = appiumLogLines(this.appium.logSince(start, APPIUM_LOG_MAX_BYTES, end), this.ctx.redact);
+            if (appium.lines.length > 0) {
+                debug.appium_log = appium.lines;
+                if (appium.dropped > 0)
+                    debug.dropped = { appium_log: appium.dropped };
+            }
+        }
+        return Object.keys(debug).length > 0 ? debug : undefined;
     }
     async stopRecording() {
         if (!this.recorder || this.videoStopped)

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

@@ -13,7 +13,7 @@ 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 } from './common.js';
+import { clip, errorMessage, expectWithin, firstLine, matches, render, renderLaunchArgs } 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';
@@ -26,9 +26,13 @@ export const MAX_WINDOW_INDEX = 100;
 export const INSTALLED_REFUSED = 'electron apps need an uploaded build or a path on the runner';
 const LAUNCH_TIMEOUT_MS = 60_000;
 const PAINT_TIMEOUT_MS = 15_000;
+/** How long the paint wait pauses before checking a window whose page navigated again. */
+const PAINT_RETRY_MS = 100;
+/** How long after the paint a launch waits for its video's first frame (held-back frames come within about 0.5 s). */
+const FIRST_FRAME_WAIT_MS = 1_500;
 const VIDEO_SIZE = { width: 1024, height: 576 };
 /** Switches the runner controls itself (debugging ports); a script cannot pass them. */
-const RESERVED_ARG = /^--(inspect|inspect-brk|inspect-port|remote-debugging-port|remote-debugging-pipe|remote-allow-origins)(=|$)/i;
+export const RESERVED_ARG = /^--(inspect|inspect-brk|inspect-port|remote-debugging-port|remote-debugging-pipe|remote-allow-origins)(=|$)/i;
 /** Runner secrets never reach the app's environment. */
 const SECRET_ENV = new Set(['RUNNER_TOKEN', 'LEERA_RUNNER_TOKEN', 'ELECTRON_RUN_AS_NODE', 'NODE_OPTIONS']);
 /** Checks an Electron-only action before it runs; throws what the step reports. */
@@ -106,6 +110,65 @@ function freePort() {
         });
     });
 }
+/**
+ * Starts a recording's clock. A video starts with its first frame, not with its window: often a
+ * blank frame while the app's script loads, a frame Chromium held back until there was content, or,
+ * for a window that shows nothing new, the first change. That frame's time stamp comes from
+ * Playwright's screencast of the page, the stream its recorder writes; the listener stops after it.
+ */
+function recordingOf(page, video, log) {
+    const recording = { video, page, openedAt: Date.now(), startedAt: null, started: Promise.resolve(), endedAt: null };
+    recording.started = new Promise((resolve) => {
+        let settled = false;
+        let listener = Promise.resolve(null);
+        const settle = (at) => {
+            if (settled)
+                return;
+            settled = true;
+            if (at !== null)
+                recording.startedAt = at;
+            resolve();
+            void listener.then((started) => started?.dispose()).catch(() => undefined);
+        };
+        page.once('close', () => settle(null));
+        listener = Promise.resolve()
+            .then(() => page.screencast.start({ onFrame: ({ timestamp }) => settle(timestamp) }))
+            .catch((error) => {
+            // Without the time stamp, the window's opening is the earliest the video can start.
+            log.warn("the app window's video start could not be read; step offsets count from the window's opening", { error: firstLine(error) });
+            settle(recording.openedAt);
+            return null;
+        });
+    });
+    return recording;
+}
+/** The paint check, run in the window: settles once it is visible and has run two animation frames. */
+function paintCheck() {
+    return new Promise((resolve) => {
+        const tick = () => {
+            if (document.visibilityState === 'visible')
+                requestAnimationFrame(() => requestAnimationFrame(() => resolve(true)));
+            else
+                setTimeout(tick, 250);
+        };
+        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;
@@ -121,7 +184,10 @@ export class ElectronPlaywrightDriver {
     page = null;
     collector = null;
     videoDir = null;
-    videos = [];
+    /** The recordings of the app instances that started, oldest first; the last one is returned (see stopRecording). */
+    recordings = [];
+    /** When each step began (ms), in the order they ran. */
+    stepStarts = [];
     videoPath;
     videoStopped = false;
     /** The script's first action is `launch`: `launch()` already started the app with its args. */
@@ -195,7 +261,7 @@ export class ElectronPlaywrightDriver {
     async launch() {
         this.executable = await this.resolveExecutable();
         try {
-            this.display = await ensureDisplay();
+            this.display = await (this.options.display ?? ensureDisplay)();
         }
         catch (error) {
             throw new Blocked(errorMessage(error));
@@ -206,17 +272,26 @@ export class ElectronPlaywrightDriver {
             else
                 this.videoDir = await mkdtemp(join(tmpdir(), 'qa-video-'));
         }
-        this.collector = new DebugCollector(Date.now(), this.ctx.redact);
         // A script that starts with `launch {args}` gets its arguments on the first start.
         const first = [...this.ctx.job.automation.steps].sort((a, b) => a.index - b.index)[0]?.actions[0];
         let args = [];
         if (first?.type === 'launch') {
             validateElectronAction(first);
-            args = (first.args ?? []).map((arg) => render(arg, this.ctx.template));
+            args = renderLaunchArgs(first.args, (arg) => render(arg, this.ctx.template), RESERVED_ARG);
             this.firstLaunchDone = true;
         }
-        await this.start(args);
+        const started = await this.start(args);
+        // Times count from where the first window's video starts (the web driver counts from its page).
+        // No step has begun yet, so nothing was filed before this. While a window is recorded, a step
+        // that captured nothing is still reported, so debug can give it its place in the video.
+        this.collector = new DebugCollector(started, this.ctx.redact, () => this.recordings.length > 0);
+        for (const page of this.windows)
+            this.collector.attach(page);
     }
+    /**
+     * Starts the app and waits for its first window to paint, and for its video's first frame when
+     * it is recorded. Returns where that video starts (ms), or now when there is none.
+     */
     async start(args) {
         const executable = this.executable;
         if (!executable)
@@ -226,7 +301,7 @@ export class ElectronPlaywrightDriver {
         try {
             if (this.options.launchVia === 'cdp')
                 throw new Error('the DevTools-port launch was requested');
-            const electron = await _electron.launch({
+            const electron = await (this.options.electron ?? _electron).launch({
                 executablePath: executable,
                 args,
                 env,
@@ -235,7 +310,7 @@ export class ElectronPlaywrightDriver {
                 acceptDownloads: false,
                 ...(this.videoDir ? { recordVideo: { dir: this.videoDir, size: VIDEO_SIZE } } : {}),
             });
-            this.adopt({ via: 'playwright', electron, browser: null, context: electron.context(), process: electron.process(), video: null, closed: false });
+            this.adopt({ via: 'playwright', electron, browser: null, context: electron.context(), process: electron.process(), recording: null, closed: false });
             electron.on('window', (page) => this.addWindow(page));
             for (const page of electron.windows())
                 this.addWindow(page);
@@ -259,6 +334,19 @@ export class ElectronPlaywrightDriver {
         this.page = page;
         await page.waitForLoadState('domcontentloaded', { timeout: LAUNCH_TIMEOUT_MS }).catch(() => undefined);
         await this.waitForPaint(page, 'launch');
+        const recording = this.instance?.recording;
+        if (!recording)
+            return Date.now();
+        this.recordings.push(recording);
+        // The first frame comes with the paint, or soon after it when Chromium held it back. A window
+        // that shows nothing new may send none until it changes: that frame still sets the video's
+        // start, only not the case clock, which cannot wait for it.
+        const timer = new AbortController();
+        const shown = await Promise.race([recording.started.then(() => true), sleep(FIRST_FRAME_WAIT_MS, false, { signal: timer.signal }).catch(() => false)]);
+        timer.abort();
+        if (!shown)
+            this.ctx.log.debug('no video frame yet after the app window painted; logged times may not match the video');
+        return recording.startedAt ?? Date.now();
     }
     /**
      * Waits until the window is visible and has painted (two animation frames). A loaded DOM is not
@@ -266,28 +354,81 @@ export class ElectronPlaywrightDriver {
      * VM under Xvfb), and Chromium's screenshot waits for a frame, so the first screenshot timed out
      * while actions on the DOM passed. Animation frames only run while frames are produced. Bounded;
      * a window that never paints is reported by the step that needs it, not here.
+     *
+     * A page that navigates meanwhile (index.html redirecting to a login page, or a loading page the
+     * app replaces with loadURL) fails the check: Playwright rejects it when the old page's context
+     * goes, or, for a navigation the app starts from its main process, as soon as that navigation
+     * starts. Until the same deadline, the wait then pauses, waits for domcontentloaded and checks
+     * again, as the launch does for the first page. Right after the rejection Playwright can still
+     * report the old page's load state, and a check made before the new page commits can fail at
+     * once: the pause keeps the loop from spinning until it does.
      */
     async waitForPaint(page, when) {
         const started = Date.now();
-        const frames = page
-            .evaluate(() => new Promise((resolve) => {
-            const tick = () => {
-                if (document.visibilityState === 'visible')
-                    requestAnimationFrame(() => requestAnimationFrame(() => resolve(true)));
-                else
-                    setTimeout(tick, 250);
-            };
-            tick();
-        }))
-            .catch(() => false);
+        const limitMs = this.options.paintTimeoutMs ?? PAINT_TIMEOUT_MS;
         const timer = new AbortController();
-        const painted = await Promise.race([frames, sleep(PAINT_TIMEOUT_MS, false, { signal: timer.signal }).catch(() => false)]);
-        timer.abort();
+        const after = (ms, value) => sleep(ms, value, { signal: timer.signal }).catch(() => value);
+        // A check can outlive its window: one waiting for a new page's context never settles.
+        let gone = () => undefined;
+        const ended = new Promise((resolve) => {
+            gone = resolve;
+        });
+        const onClose = () => gone('closed');
+        const onCrash = () => gone('crashed');
+        page.once('close', onClose);
+        page.once('crash', onCrash);
+        const stop = Promise.race([after(limitMs, 'timeout'), ended]);
+        let outcome;
+        let checks = 0;
+        let navigated = false;
+        try {
+            for (;;) {
+                checks += 1;
+                const check = page.evaluate(paintCheck).then(() => 'painted', (error) => (error instanceof Error ? error : new Error(String(error))));
+                outcome = await Promise.race([check, stop]);
+                if (!(outcome instanceof Error))
+                    break;
+                if (page.isClosed()) {
+                    outcome = 'closed';
+                    break;
+                }
+                // Anything but a lost context (a crash, a script error in the window) fails every check alike.
+                if (!/Execution context was destroyed/.test(outcome.message))
+                    break;
+                navigated = true;
+                const paused = await Promise.race([after(PAINT_RETRY_MS, 'next'), stop]);
+                if (paused !== 'next') {
+                    outcome = paused;
+                    break;
+                }
+                const timeout = Math.max(1, started + limitMs - Date.now());
+                const loaded = await Promise.race([page.waitForLoadState('domcontentloaded', { timeout }).then(() => 'next', () => 'next'), stop]);
+                if (loaded !== 'next') {
+                    outcome = loaded;
+                    break;
+                }
+            }
+        }
+        finally {
+            timer.abort();
+            page.off('close', onClose);
+            page.off('crash', onCrash);
+        }
+        if (navigated)
+            this.ctx.log.debug(`the app window's page navigated before it painted after ${when}`, { checks });
         const ms = Date.now() - started;
-        if (!painted)
-            this.ctx.log.warn(`the app window did not paint within ${Math.round(PAINT_TIMEOUT_MS / 1000)} s after ${when}`);
-        else if (ms > 2_000)
-            this.ctx.log.warn(`the app window took ${ms} ms to paint after ${when}`);
+        if (outcome === 'painted') {
+            if (ms > 2_000)
+                this.ctx.log.warn(`the app window took ${ms} ms to paint after ${when}`);
+        }
+        else if (outcome === 'timeout')
+            this.ctx.log.warn(`the app window did not paint within ${Math.round(limitMs / 1000)} s after ${when}`);
+        else if (outcome === 'closed')
+            this.ctx.log.info(`the app window closed before it painted after ${when}`);
+        else if (outcome === 'crashed')
+            this.ctx.log.warn(`the app window crashed before it painted after ${when}`);
+        else
+            this.ctx.log.warn(`the app window's paint could not be checked after ${when}`, { error: firstLine(outcome) });
     }
     /** Fallback for apps whose fuses block Playwright's launch: spawn with a DevTools port and connect over CDP. */
     async startOverCdp(executable, args, env, cwd) {
@@ -306,7 +447,7 @@ export class ElectronPlaywrightDriver {
         child.once('error', (error) => {
             exited = `the app could not start: ${error.message}`;
         });
-        const instance = { via: 'cdp', electron: null, browser: null, context: null, process: child, video: null, closed: false };
+        const instance = { via: 'cdp', electron: null, browser: null, context: null, process: child, recording: null, closed: false };
         try {
             const endpoint = `http://127.0.0.1:${port}`;
             const deadline = Date.now() + LAUNCH_TIMEOUT_MS;
@@ -320,7 +461,8 @@ export class ElectronPlaywrightDriver {
                     throw new Error(`no DevTools endpoint on port ${port} within ${LAUNCH_TIMEOUT_MS / 1000} s`);
                 await sleep(250);
             }
-            const browser = await chromium.connectOverCDP(endpoint, { timeout: LAUNCH_TIMEOUT_MS });
+            const connect = this.options.connectOverCDP ?? ((url, options) => chromium.connectOverCDP(url, options));
+            const browser = await connect(endpoint, { timeout: LAUNCH_TIMEOUT_MS });
             const context = browser.contexts()[0];
             if (!context)
                 throw new Error('the app exposes no browser context');
@@ -355,14 +497,15 @@ export class ElectronPlaywrightDriver {
         page.setDefaultNavigationTimeout(Math.max(this.ctx.timeouts.actionMs, 30_000));
         this.collector?.attach(page);
         const instance = this.instance;
-        if (instance && !instance.video && instance.via === 'playwright') {
+        if (instance && !instance.recording && instance.via === 'playwright') {
             const video = page.video();
-            if (video) {
-                instance.video = video;
-                this.videos.push(video);
-            }
+            if (video)
+                instance.recording = recordingOf(page, video, this.ctx.log);
         }
         page.once('close', () => {
+            const recording = instance?.recording;
+            if (recording?.page === page)
+                recording.endedAt ??= Date.now();
             this.windows = this.windows.filter((p) => p !== page);
             if (this.page === page)
                 this.page = this.windows[0] ?? null;
@@ -377,7 +520,7 @@ export class ElectronPlaywrightDriver {
                 if (first && this.firstLaunchDone)
                     return {};
                 await this.closeInstance();
-                await this.start((action.args ?? []).map((arg) => render(arg, this.ctx.template)));
+                await this.start(renderLaunchArgs(action.args, (arg) => render(arg, this.ctx.template), RESERVED_ARG));
                 return {};
             }
             case 'terminate':
@@ -461,27 +604,47 @@ export class ElectronPlaywrightDriver {
         return this.requirePage().content();
     }
     beginStep(index) {
+        this.stepStarts.push({ index, at: Date.now() });
         this.collector?.begin(index);
     }
+    /**
+     * The step's capture, with its place in the video stopRecording returns; a step that video does
+     * not show has no offset, and one that also captured nothing has no debug at all. Entry times
+     * (`at_secs`) count from the first window's first paint.
+     */
     debug(index) {
-        return this.collector?.for(index);
+        const captured = this.collector?.for(index);
+        if (!captured)
+            return undefined;
+        const { video_offset_secs: _sinceFirstPaint, ...debug } = captured;
+        const offset = this.videoOffset(index);
+        if (offset !== undefined)
+            return { ...debug, video_offset_secs: offset };
+        return Object.keys(debug).length > 0 ? debug : undefined;
+    }
+    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);
     }
-    /** Closes the app (a video is only complete then) and returns the longest recording. */
+    /**
+     * Closes the app (a video is only complete then) and returns the last recording. A relaunch
+     * (`launch` again, or `terminate` then `launch`) records the new instance in a video of its own;
+     * the last one shows how the case ended, a failure included. Steps that ended before it began
+     * get no offset (see debug), and if it has no file no video is returned rather than one the
+     * offsets do not describe. A relaunch over the DevTools port records nothing, so the video before
+     * it is the last one.
+     */
     async stopRecording() {
         if (this.videoStopped)
             return this.videoPath;
         this.videoStopped = true;
         await this.closeInstance();
-        let best = null;
-        for (const video of this.videos) {
-            const path = await video.path().catch(() => undefined);
-            if (!path)
-                continue;
-            const size = await stat(path).then((s) => s.size, () => 0);
-            if (size > 0 && (!best || size > best.size))
-                best = { path, size };
-        }
-        this.videoPath = best?.path;
+        const path = await this.recordings.at(-1)?.video.path().catch(() => undefined);
+        const size = path ? await stat(path).then((s) => s.size, () => 0) : 0;
+        this.videoPath = size > 0 ? path : undefined;
         if (!this.videoPath && this.videoDir) {
             await rm(this.videoDir, { recursive: true, force: true }).catch(() => undefined);
             this.videoDir = null;
@@ -510,6 +673,9 @@ export class ElectronPlaywrightDriver {
         if (!instance || instance.closed)
             return;
         instance.closed = true;
+        // Its video ends with it: a step that begins later is not in it.
+        if (instance.recording)
+            instance.recording.endedAt ??= Date.now();
         const pid = instance.process?.pid;
         const graceful = instance.electron
             ? instance.electron.close()
@@ -518,7 +684,10 @@ export class ElectronPlaywrightDriver {
                     await page.close({ runBeforeUnload: false }).catch(() => undefined);
                 await instance.browser?.close();
             })();
-        await Promise.race([graceful.catch(() => undefined), sleep(10_000)]);
+        // The timer is cancelled once the app has closed, so it does not keep the process alive.
+        const timer = new AbortController();
+        await Promise.race([graceful.catch(() => undefined), sleep(10_000, undefined, { signal: timer.signal }).catch(() => undefined)]);
+        timer.abort();
         killProcessTree(pid);
         await this.endLeftoverProcesses();
     }

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

@@ -427,16 +427,15 @@ export class IosAppiumDriver {
         this.simLog?.checkCrashes();
         const captured = this.collector?.for(index);
         const appium = result === 'failed' || result === 'blocked' ? this.appiumLogFor(index) : null;
-        if (!captured && !appium)
-            return undefined;
         const offset = this.offsets.get(index);
+        // While recording, the start time alone is kept: it is the step's place in the video.
         const debug = { ...captured, ...(offset !== undefined && this.recording ? { video_offset_secs: offset } : {}) };
         if (appium && appium.lines.length > 0) {
             debug.appium_log = appium.lines;
             if (appium.dropped > 0)
                 debug.dropped = { ...debug.dropped, appium_log: appium.dropped };
         }
-        return debug;
+        return Object.keys(debug).length > 0 ? debug : undefined;
     }
     appiumLogFor(index) {
         const start = this.appiumLogOffsets.get(index);

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

@@ -4,7 +4,7 @@ import { hostDevice } from '../devices/desktop.js';
 import { ACCESSIBILITY_BLOCKED, appBundleOf, BUNDLE_ID_RE, isAccessibilityError, MACOS_NEEDS_MAC, mac2Capabilities, macosReadiness, markAccessibilityBlocked, readBundleId, } from '../devices/macos.js';
 import { homePaths } from '../home.js';
 import { androidSdkFor, configuredSdkPath, sharedAppiumServer } from './android-appium.js';
-import { clip, errorMessage, expectWithin } from './common.js';
+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';
@@ -200,7 +200,7 @@ export class Mac2AppiumDriver extends DesktopAppiumDriver {
         try {
             switch (action.type) {
                 case 'launch':
-                    await this.start((action.args ?? []).map(this.render));
+                    await this.start(renderLaunchArgs(action.args, this.render));
                     return {};
                 case 'terminate':
                     await macos(this.requireClient(), 'terminateApp', { bundleId: this.bundleId });

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

@@ -9,9 +9,9 @@ import { ensureDisplay, hostDevice } from '../devices/desktop.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, requireTarget, verb } from './common.js';
+import { clip, errorMessage, expectWithin, matches, render, renderLaunchArgs, requireTarget, verb } from './common.js';
 import { Blocked, LaunchRefused, NotFound, Unsupported, } from './driver.js';
-import { ELECTRON_ACTIONS, electronEnv, killProcessTree, validateElectronAction } from './electron-playwright.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 { buildDomSnapshot, domRefOf, domScreen } from './webdriver/dom-tree.js';
 import { elementIdOf } from './webdriver/locate.js';
@@ -224,7 +224,7 @@ export class TauriWebDriver {
         let args = [];
         if (first?.type === 'launch') {
             validateTauriAction(first);
-            args = (first.args ?? []).map(this.renderText);
+            args = renderLaunchArgs(first.args, this.renderText, RESERVED_ARG);
             this.firstLaunchDone = true;
         }
         await this.start(args);
@@ -323,7 +323,7 @@ export class TauriWebDriver {
                     if (first && this.firstLaunchDone)
                         return {};
                     await this.closeApp();
-                    await this.start((action.args ?? []).map(this.renderText));
+                    await this.start(renderLaunchArgs(action.args, this.renderText, RESERVED_ARG));
                     return {};
                 case 'terminate':
                     await this.closeApp();

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

@@ -138,9 +138,9 @@ export class WebPlaywrightDriver {
         const page = await this.context.newPage();
         this.page = page;
         // The video starts with the page, so step offsets are measured from here.
-        this.collector = new DebugCollector(Date.now(), this.ctx.redact);
-        this.collector.attach(page);
         this.video = page.video();
+        this.collector = new DebugCollector(Date.now(), this.ctx.redact, () => this.video !== null);
+        this.collector.attach(page);
         page.setDefaultTimeout(this.ctx.timeouts.actionMs);
         page.setDefaultNavigationTimeout(Math.max(this.ctx.timeouts.actionMs, NAVIGATION_TIMEOUT_MS));
     }
@@ -260,12 +260,30 @@ export async function findOnPage(page, target, ctx, snapshotTaken) {
     await page.ariaSnapshot({ mode: 'ai' }).catch(() => undefined);
     return { count, refs };
 }
+/**
+ * The URL a `goto` opens, checked after rendering and resolving: only http(s). The server checks
+ * the script, but a URL that starts with a data value or the API base URL can render any scheme.
+ */
+export function checkGotoUrl(url) {
+    let protocol;
+    try {
+        protocol = new URL(url).protocol;
+    }
+    catch {
+        throw new Blocked(`'${clip(url)}' is not a URL the browser can open; use http(s)://, or a path on an environment with a base URL`);
+    }
+    if (protocol !== 'http:' && protocol !== 'https:') {
+        throw new Blocked(`only http(s) URLs can be opened; '${clip(url)}' uses ${protocol}`);
+    }
+    return url;
+}
 /** Performs one web DSL action on a page (shared by the web and Electron drivers). */
 export async function runWebAction(page, action, ctx, defaultTimeout) {
     const timeout = action.timeout_ms ?? defaultTimeout;
     switch (action.type) {
         case 'goto': {
-            const url = resolveUrl(render(action.url, ctx), ctx.baseUrl);
+            // Trimmed as the server reads it, so a path with a stray leading space still opens on the environment.
+            const url = checkGotoUrl(resolveUrl(render(action.url, ctx).trim(), ctx.baseUrl));
             try {
                 await page.goto(url, { waitUntil: 'load', timeout: Math.max(timeout, NAVIGATION_TIMEOUT_MS) });
             }

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

@@ -1,6 +1,6 @@
 import { setTimeout as sleep } from 'node:timers/promises';
 import { clip, expectWithin, matches, verb } from '../common.js';
-import { NotFound, Unsupported } from '../driver.js';
+import { Blocked, NotFound, Unsupported } from '../driver.js';
 import { describeAndroidTarget, findAll, locate } from './locate.js';
 import { mobile, webdriverMessage } from './session.js';
 /** Named android keys (plan §3) → Android key codes. */
@@ -68,13 +68,17 @@ export const ANDROID_ACTIONS = [
     'expect_hidden',
     'expect_text',
 ];
-/** Deep link schemes a script may open (plan §3); the server validates too. */
+/**
+ * Deep link schemes a script may open (plan §3), checked on the rendered URL (android and ios):
+ * the server checks the script, but a link that starts with a data value can render any scheme.
+ * A refused link blocks the step.
+ */
 export function checkDeepLink(url) {
     const match = /^([a-z][a-z0-9+.-]{1,63}):\/\//i.exec(url);
     if (!match)
-        throw new Error(`deep link '${clip(url)}' must start with a scheme such as https:// or myapp://`);
+        throw new Blocked(`deep link '${clip(url)}' must start with a scheme such as https:// or myapp://`);
     if (/^(javascript|file|data|blob|content|intent)$/i.test(match[1]))
-        throw new Error(`deep links with the ${match[1]} scheme are not allowed`);
+        throw new Blocked(`deep links with the ${match[1]} scheme are not allowed`);
     return url;
 }
 function requireTarget(action) {

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

@@ -13,8 +13,10 @@
   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 };
 
+  /** Collapses whitespace and composes accents (NFC), so the target and the page compare alike. */
   function normalize(value) {
     return String(value == null ? '' : value)
+      .normalize('NFC')
       .replace(/\s+/g, ' ')
       .trim();
   }

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

@@ -5,7 +5,7 @@ import { hostDevice } from '../devices/desktop.js';
 import { installedWindowsApp, loadWindowsSettings, sharedWinAppDriver, WINAPPDRIVER_VERSION, WINDOWS_NEEDS_WINDOWS, windowsCapabilities, windowsReadiness, } from '../devices/windows.js';
 import { homePaths } from '../home.js';
 import { androidSdkFor, configuredSdkPath, sharedAppiumServer } from './android-appium.js';
-import { clip, errorMessage, expectWithin, matches } from './common.js';
+import { clip, errorMessage, expectWithin, matches, renderLaunchArgs } from './common.js';
 import { DesktopAppiumDriver, validateNativeAction } from './desktop-appium.js';
 import { Blocked, LaunchRefused, } from './driver.js';
 import { emptyScreen } from './snapshot/format.js';
@@ -185,7 +185,7 @@ export class WindowsAppiumDriver extends DesktopAppiumDriver {
             switch (action.type) {
                 case 'launch':
                     await this.closeApp();
-                    await this.start((action.args ?? []).map(this.render));
+                    await this.start(renderLaunchArgs(action.args, this.render));
                     return {};
                 case 'terminate':
                     await this.closeApp();

package/dist/src/executor.js

@@ -11,10 +11,17 @@ export { launchBrowser } from './drivers/web-playwright.js';
 export function templateContextFor(job) {
     return {
         baseUrl: job.environment.base_url ?? '',
+        apiBaseUrl: job.environment.api_base_url ?? null,
+        randomEmailDomain: job.environment.random_email_domain ?? null,
         username: job.credential?.username ?? null,
         password: job.credential?.password ?? null,
         runId: job.run.id,
         appId: job.app?.id ?? null,
+        data: job.data?.refs ?? {},
+        tag: job.data?.tag ?? null,
+        itemId: job.item.id,
+        jobId: job.job.id,
+        attempt: job.job.attempt,
         random: new Map(),
     };
 }
@@ -48,6 +55,7 @@ export function jobContext(job, options) {
 /**
  * A driver context for a device session. Drivers read the app, device and environment
  * from `ctx.job`, so the session is also presented as a job with no steps (id 0, run 0).
+ * Its placeholders know they belong to a session: job values and test data are refused.
  */
 export function sessionContext(session, options) {
     if (!isPlatform(session.platform))
@@ -66,7 +74,8 @@ export function sessionContext(session, options) {
         automation: platform === 'web' ? { version: 1, steps: [] } : { version: 2, platform, steps: [] },
         capture: { video: 'off' },
     };
-    return { ...jobContext(job, options), session };
+    const ctx = jobContext(job, options);
+    return { ...ctx, template: { ...ctx.template, session: true }, session };
 }
 /** Creates the driver for a context through the registry; a platform without a factory is blocked. */
 export async function createDriver(registry, ctx, shared) {
@@ -114,9 +123,10 @@ export async function executeSteps(driver, script, options, shouldStop, redact)
             await driver.launch();
         }
         catch (error) {
-            // A launch this runner refuses as configured blocks the case; other launch errors fail the job (and may be retried).
+            // A launch this runner refuses as configured, or launch args it cannot fill, block the case;
+            // other launch errors fail the job (and may be retried).
             const first = ordered[0];
-            if (!(error instanceof LaunchRefused) || !first)
+            if (!(error instanceof LaunchRefused || error instanceof TemplateError) || !first)
                 throw error;
             const outcome = { index: first.index, result: 'blocked', note: redact(errorMessage(error)), screenshots: [] };
             return { steps: [outcome], elapsedSecs: Math.max(1, Math.round((Date.now() - started) / 1000)), stopped: false };

package/dist/src/template.js

@@ -1,7 +1,10 @@
 import { randomBytes, randomInt } from 'node:crypto';
 export class TemplateError extends Error {
 }
-const PLACEHOLDER = /\{\{\s*([a-z_.]+)\s*\}\}/g;
+const PLACEHOLDER = /\{\{\s*([a-z][a-z0-9_.]*)\s*\}\}/g;
+/** The field a bare `{{data.<ref>}}` reads. */
+export const DEFAULT_DATA_FIELD = 'value';
+/** Fills every placeholder in one pass: a value that itself contains `{{…}}` is inserted as it is. */
 export function renderTemplate(text, ctx) {
     return text.replace(PLACEHOLDER, (_match, name) => placeholderValue(name, ctx));
 }
@@ -29,29 +32,81 @@ export function redactDeep(value, redact) {
     return value;
 }
 function placeholderValue(name, ctx) {
+    if (name.startsWith('data.'))
+        return dataValue(name, ctx);
     switch (name) {
         case 'env.base_url':
             return trimSlash(ctx.baseUrl);
+        case 'env.api_base_url': {
+            const apiBaseUrl = ctx.apiBaseUrl?.trim();
+            if (!apiBaseUrl)
+                throw new TemplateError(`the script uses {{${name}}} but the environment has no API base URL`);
+            return trimSlash(apiBaseUrl);
+        }
         case 'credential.username':
             return present(ctx.username, name);
         case 'credential.password':
             return present(ctx.password, name);
         case 'run.id':
             return String(ctx.runId);
+        case 'item.id':
+            return jobValue(ctx, name, ctx.itemId);
+        case 'job.id':
+            return jobValue(ctx, name, ctx.jobId);
+        case 'job.attempt':
+            return jobValue(ctx, name, ctx.attempt);
+        case 'job.tag':
+            return jobValue(ctx, name, ctx.tag);
         case 'app.id':
             if (!ctx.appId)
                 throw new TemplateError('the script uses {{app.id}} but the job has no app');
             return ctx.appId;
         case 'random.email':
-            return remembered(ctx, name, () => `qa.${token(10)}@example.com`);
+            return remembered(ctx, name, () => `qa.${token(10)}@${emailDomain(ctx)}`);
         case 'random.string':
             return remembered(ctx, name, () => token(12));
         case 'random.number':
             return remembered(ctx, name, () => String(randomInt(100_000, 1_000_000)));
+        case 'now.iso':
+            return now(ctx);
+        case 'date.today':
+            // Taken from the same remembered instant as {{now.iso}}, so the two always agree (UTC).
+            return now(ctx).slice(0, 10);
         default:
             throw new TemplateError(`unknown placeholder {{${name}}}`);
     }
 }
+/** `{{data.<ref>}}` (field `value`) or `{{data.<ref>.<field>}}`; a missing value is an error, never empty text. */
+function dataValue(name, ctx) {
+    const rest = name.slice('data.'.length);
+    const dot = rest.indexOf('.');
+    const reference = dot === -1 ? rest : rest.slice(0, dot);
+    const field = dot === -1 ? DEFAULT_DATA_FIELD : rest.slice(dot + 1);
+    if (!reference || !field)
+        throw new TemplateError(`unknown placeholder {{${name}}}`);
+    if (ctx.session)
+        throw new TemplateError(`only a queued job has test data; a device session cannot fill {{${name}}}`);
+    const refs = ctx.data ?? {};
+    const fields = Object.hasOwn(refs, reference) ? refs[reference] : undefined;
+    // The server sends a reference it found no value for as an empty map.
+    if (!fields || typeof fields !== 'object' || Object.keys(fields).length === 0) {
+        throw new TemplateError(`the script uses {{${name}}} but the job has no value for the test data reference ${reference}`);
+    }
+    const value = Object.hasOwn(fields, field) ? fields[field] : undefined;
+    if (typeof value !== 'string') {
+        throw new TemplateError(`the script uses {{${name}}} but the value of the test data reference ${reference} has no field ${field}`);
+    }
+    return value;
+}
+/** A value only a queued job has: device sessions refuse it, and older servers may not send it. */
+function jobValue(ctx, name, value) {
+    if (ctx.session)
+        throw new TemplateError(`only a queued job has {{${name}}}`);
+    if (value === null || value === undefined || value === '') {
+        throw new TemplateError(`the script uses {{${name}}} but the server did not send it with this job`);
+    }
+    return String(value);
+}
 function present(value, name) {
     if (value === null)
         throw new TemplateError(`the script uses {{${name}}} but the job has no credential`);
@@ -65,6 +120,12 @@ function remembered(ctx, name, make) {
     }
     return value;
 }
+function now(ctx) {
+    return remembered(ctx, 'now.iso', () => new Date().toISOString());
+}
+function emailDomain(ctx) {
+    return ctx.randomEmailDomain?.trim() || 'example.com';
+}
 function token(length) {
     return randomBytes(length).toString('hex').slice(0, length);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leera.io/qa-runner",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Runs recorded QA test scripts on your own machines and reports results back to your workspace.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",