@leera.io/qa-runner 1.0.6 → 1.2.0

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/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,18 @@ 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,
+        otp: job.credential?.otp ?? 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 +56,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 +75,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 +124,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/home.js

@@ -16,6 +16,7 @@ export function homePaths(env = process.env) {
         browsers: join(root, 'browsers'),
         jobs: join(root, 'jobs'),
         versions: join(root, 'versions'),
+        ffmpeg: join(root, 'ffmpeg'),
     };
 }
 const isWindows = process.platform === 'win32';

package/dist/src/runner.js

@@ -12,7 +12,7 @@ import { createDriver, executeClaimedJob, jobContext, sessionContext } from './e
 import { HealthMonitor, healthReport } from './health.js';
 import { homePaths, readJsonFile, writePrivateFile } from './home.js';
 import { progressReporter } from './progress.js';
-import { redactor } from './template.js';
+import { credentialSecrets, redactor } from './template.js';
 import { runSession } from './session/loop.js';
 import { isSessionClaim } from './types.js';
 import { localDay } from './update/check.js';
@@ -221,7 +221,7 @@ export class Runner {
                     jobTimeoutMs: config.jobTimeoutMs,
                     headless: config.headless,
                     ...(config.proxy ? { proxy: config.proxy } : {}),
-                    redact: redactor([session.credential?.password]),
+                    redact: redactor(credentialSecrets(session.credential)),
                     log,
                 });
                 return createDriver(registry, ctx, shared);
@@ -314,7 +314,7 @@ export class Runner {
         const jobId = job.job.id;
         const attempt = job.job.attempt;
         const platform = lease.device.platform;
-        const redact = redactor([job.credential?.password]);
+        const redact = redactor(credentialSecrets(job.credential));
         let cancelled = false;
         this.running.set(jobId, { id: jobId, kind: 'test', platform, device_id: lease.device.id, started_at: new Date().toISOString() });
         this.writeState();

package/dist/src/session/loop.js

@@ -1,6 +1,6 @@
 import { setTimeout as sleep } from 'node:timers/promises';
 import { ApiError } from '../client.js';
-import { redactor } from '../template.js';
+import { credentialSecrets, redactor } from '../template.js';
 import { DEFAULT_COMMAND_TIMEOUT_MS } from './commands.js';
 import { SessionExecutor } from './execute.js';
 /** The long-poll never asks for more than the server allows (plan §4). */
@@ -16,7 +16,7 @@ export async function runSession(session, deps) {
     const { client, log } = deps;
     const now = deps.now ?? Date.now;
     const retryDelayMs = deps.retryDelayMs ?? 2_000;
-    const redact = redactor([session.credential?.password]);
+    const redact = redactor(credentialSecrets(session.credential));
     const started = now();
     const idleMs = Math.max(1, session.idle_timeout_seconds) * 1_000;
     const maxMs = Math.max(1, session.max_seconds) * 1_000;

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));
 }
@@ -10,6 +13,10 @@ export function resolveUrl(url, baseUrl) {
         return trimSlash(baseUrl) + url;
     return url;
 }
+/** The values of a credential that must never appear in logs, reports or debug output. */
+export function credentialSecrets(credential) {
+    return [credential?.password, credential?.otp];
+}
 /** Replaces every secret in `text`; secrets under 4 characters are skipped because they would mangle ordinary words. */
 export function redactor(secrets) {
     const values = secrets
@@ -29,29 +36,86 @@ 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 'credential.otp':
+            present(ctx.password, name);
+            if (!ctx.otp)
+                throw new TemplateError(`the script uses {{${name}}} but the account has no one-time code`);
+            return ctx.otp;
         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 +129,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.6",
+  "version": "1.2.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",
@@ -16,7 +16,7 @@
     "node": ">=22.12"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && node -e \"for (const f of ['dom-locate.js', 'dom-snapshot.js']) require('node:fs').copyFileSync('src/drivers/webdriver/' + f, 'dist/src/drivers/webdriver/' + f)\"",
+    "build": "tsc -p tsconfig.json && node -e \"for (const f of ['dom-locate.js', 'dom-snapshot.js', 'dom-element.js']) require('node:fs').copyFileSync('src/drivers/webdriver/' + f, 'dist/src/drivers/webdriver/' + f)\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "biome lint --error-on-warnings src test packaging",
     "test": "npm run build && node --test \"dist/test/unit/**/*.test.js\"",