@leera.io/qa-runner 1.1.0 → 1.2.0

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/executor.js

@@ -15,6 +15,7 @@ export function templateContextFor(job) {
         randomEmailDomain: job.environment.random_email_domain ?? null,
         username: job.credential?.username ?? null,
         password: job.credential?.password ?? null,
+        otp: job.credential?.otp ?? null,
         runId: job.run.id,
         appId: job.app?.id ?? null,
         data: job.data?.refs ?? {},

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

@@ -13,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
@@ -47,6 +51,11 @@ function placeholderValue(name, ctx) {
             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':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leera.io/qa-runner",
-  "version": "1.1.0",
+  "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\"",