@leera.io/qa-runner 1.0.1 → 1.0.3

package/dist/src/cli/commands/ci.js

@@ -4,7 +4,7 @@ import { splitList } from '../../config.js';
 import { formatDoctor, runDoctor } from '../../doctor.js';
 import { shutdownEmulatorsBootedHere } from '../../devices/android/emulator.js';
 import { stopSharedAppiumServer } from '../../drivers/android-appium.js';
-import { createRegistry } from '../../drivers/registry.js';
+import { createRegistry, defaultFactories } from '../../drivers/registry.js';
 import { BrowserPool } from '../../drivers/web-playwright.js';
 import { homePaths } from '../../home.js';
 import { createLogger } from '../../log.js';
@@ -115,7 +115,7 @@ export const command = {
         const paths = homePaths(io.env);
         // CI logs are read by people: readable lines, not JSON.
         const log = createLogger({ console: 'pretty' });
-        const registry = createRegistry();
+        const registry = createRegistry(defaultFactories(io.env));
         const shared = { browsers: new BrowserPool({ headless: true }) };
         const interrupt = new AbortController();
         let signals = 0;

package/dist/src/client.js

@@ -24,6 +24,7 @@ export class RunnerClient {
             runner_id: runnerId,
             ...(options.runId != null ? { run_id: options.runId } : {}),
             ...(options.accept ? { accept: options.accept } : {}),
+            ...(options.busyDevices?.length ? { busy_devices: options.busyDevices } : {}),
         });
     }
     /**
@@ -49,16 +50,20 @@ export class RunnerClient {
             return { result: 'unexpected', status: error.status, message: error.message };
         }
     }
-    async heartbeat(jobId) {
-        const response = await this.json('/api/v1/qa/runner/heartbeat', { job_id: jobId });
+    async heartbeat(jobId, progress, attempt) {
+        const response = await this.json('/api/v1/qa/runner/heartbeat', {
+            job_id: jobId,
+            ...(attempt ? { attempt } : {}),
+            ...(progress ? { progress } : {}),
+        });
         return response?.continue ?? false;
     }
-    async uploadEvidence(jobId, name, bytes, contentType = 'image/png') {
+    async uploadEvidence(jobId, name, bytes, contentType = 'image/png', attempt) {
         const form = new FormData();
         form.append('file', new Blob([new Uint8Array(bytes)], { type: contentType }), name);
         // A video can take a while to send over a slow uplink.
         const timeoutMs = contentType.startsWith('video/') ? 10 * 60_000 : 60_000;
-        return this.expect(await this.request(`/api/v1/qa/runner/evidence?job_id=${jobId}`, { method: 'POST', body: form }, timeoutMs));
+        return this.expect(await this.request(`/api/v1/qa/runner/evidence?job_id=${jobId}${attempt ? `&attempt=${attempt}` : ''}`, { method: 'POST', body: form }, timeoutMs));
     }
     async complete(body) {
         return this.expect(await this.json('/api/v1/qa/runner/complete', body));

package/dist/src/debug.js

@@ -133,5 +133,18 @@ export function maskUrl(raw) {
         if (SENSITIVE_PARAM.test(name))
             url.searchParams.set(name, '***');
     }
+    // OAuth implicit and magic-link flows put tokens in the fragment (`#access_token=…`).
+    if (url.hash.includes('=')) {
+        const fragment = new URLSearchParams(url.hash.slice(1));
+        let changed = false;
+        for (const name of [...fragment.keys()]) {
+            if (SENSITIVE_PARAM.test(name)) {
+                fragment.set(name, '***');
+                changed = true;
+            }
+        }
+        if (changed)
+            url.hash = fragment.toString();
+    }
     return url.toString();
 }

package/dist/src/devices/manager.js

@@ -146,6 +146,24 @@ export class DeviceManager {
             },
         };
     }
+    /**
+     * Devices with no free slot, under every id their leases carry (an emulator is leased as
+     * `avd:<name>` and runs as `emulator-5554`). Sent with each claim so the server does not
+     * hand out a device this runner is still releasing — a cancelled job's, for instance.
+     */
+    full() {
+        const ids = new Set();
+        for (const slot of this.slots.values()) {
+            if (this.used(slot.device.id) >= slot.capacity)
+                ids.add(slot.device.id);
+        }
+        for (const record of this.leases.values()) {
+            if (record.platform !== 'web')
+                for (const id of record.ids)
+                    ids.add(id);
+        }
+        return [...ids];
+    }
     busy() {
         return [...this.slots.values()].map((slot) => {
             const holders = this.holdersOf(slot.device.id);

package/dist/src/executor.js

@@ -76,9 +76,9 @@ export async function createDriver(registry, ctx, shared) {
     return factory.create(ctx, shared);
 }
 /** Runs a claimed job's script on the driver its platform maps to (web, android, …). */
-export async function executeClaimedJob(registry, ctx, shared, shouldStop) {
+export async function executeClaimedJob(registry, ctx, shared, shouldStop, onProgress) {
     const driver = await createDriver(registry, ctx, shared);
-    return executeSteps(driver, ctx.job.automation, { jobTimeoutMs: ctx.timeouts.jobMs }, shouldStop, ctx.redact);
+    return executeSteps(driver, ctx.job.automation, { jobTimeoutMs: ctx.timeouts.jobMs, ...(onProgress ? { onProgress } : {}) }, shouldStop, ctx.redact);
 }
 /**
  * Runs a script's steps in index order on a driver: stops at the first failed or
@@ -93,6 +93,23 @@ export async function executeSteps(driver, script, options, shouldStop, redact)
     let videoPath;
     try {
         const ordered = [...script.steps].sort((a, b) => a.index - b.index);
+        const report = (progress) => {
+            if (!options.onProgress)
+                return;
+            const passed = steps.filter((outcome) => outcome.result === 'passed').length;
+            try {
+                options.onProgress({
+                    ...progress,
+                    step_count: ordered.length,
+                    steps_passed: passed,
+                    steps_failed: steps.length - passed,
+                });
+            }
+            catch {
+                // Progress is a courtesy to whoever is watching; it never fails the job.
+            }
+        };
+        report({ phase: 'launching' });
         try {
             await driver.launch();
         }
@@ -104,8 +121,9 @@ export async function executeSteps(driver, script, options, shouldStop, redact)
             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 };
         }
-        for (const step of ordered) {
+        for (const [position, step] of ordered.entries()) {
             const outcome = { index: step.index, result: 'passed', screenshots: [] };
+            report({ phase: 'running', step_index: step.index, step_number: position + 1 });
             driver.beginStep(step.index);
             try {
                 for (const action of step.actions) {

package/dist/src/index.js

@@ -1,6 +1,6 @@
 // Docker entry: starts the runner from the environment (RUNNER_URL, RUNNER_TOKEN, …).
 import { stopSharedAppiumServer } from './drivers/android-appium.js';
-import { messageOf } from './errors.js';
+import { ExitCode, ExitError, messageOf } from './errors.js';
 import { createLogger } from './log.js';
 import { createRunner } from './runner.js';
 const log = createLogger({ console: 'json' });
@@ -16,7 +16,12 @@ async function main() {
         await stopSharedAppiumServer();
     }
 }
+function exitCodeFor(error) {
+    // The same codes as the CLI (3: token rejected, 5: server needs a newer runner), so a
+    // container's exit status says why it stopped, as docs/test-runners.md promises.
+    return error instanceof ExitError ? error.code : ExitCode.error;
+}
 main().catch((error) => {
     log.error('runner stopped', { error: messageOf(error) });
-    process.exitCode = 1;
+    process.exitCode = exitCodeFor(error);
 });

package/dist/src/progress.js

@@ -0,0 +1,32 @@
+/**
+ * Sends progress one request at a time, keeping only the newest update while one
+ * is in flight: a script with fast steps must not queue a request per step, and
+ * the run page only needs where the job is now, not every place it has been.
+ */
+export function progressReporter(send) {
+    let pending;
+    let inFlight = false;
+    let stopped = false;
+    const pump = async () => {
+        inFlight = true;
+        while (pending && !stopped) {
+            const next = pending;
+            pending = undefined;
+            await send(next).catch(() => undefined);
+        }
+        inFlight = false;
+    };
+    return {
+        report(progress) {
+            if (stopped)
+                return;
+            pending = progress;
+            if (!inFlight)
+                void pump();
+        },
+        stop() {
+            stopped = true;
+            pending = undefined;
+        },
+    };
+}

package/dist/src/runner.js

@@ -5,12 +5,13 @@ import { ApiError, RunnerClient } from './client.js';
 import { loadFileConfig, resolveConfig } from './config.js';
 import { DeviceManager, INVENTORY_REFRESH_MS } from './devices/manager.js';
 import { BROWSER_DEVICE_ID, isPlatform } from './devices/types.js';
-import { createRegistry } from './drivers/registry.js';
+import { createRegistry, defaultFactories } from './drivers/registry.js';
 import { BrowserPool } from './drivers/web-playwright.js';
 import { ExitCode, ExitError, messageOf } from './errors.js';
 import { createDriver, executeClaimedJob, jobContext, sessionContext } from './executor.js';
 import { HealthMonitor, healthReport } from './health.js';
 import { homePaths, readJsonFile, writePrivateFile } from './home.js';
+import { progressReporter } from './progress.js';
 import { redactor } from './template.js';
 import { runSession } from './session/loop.js';
 import { isSessionClaim } from './types.js';
@@ -114,7 +115,7 @@ export class Runner {
                 }
                 let claim;
                 try {
-                    claim = await client.claim(registration.runner_id, { accept, runId: this.config.runId });
+                    claim = await client.claim(registration.runner_id, { accept, runId: this.config.runId, busyDevices: devices.full() });
                 }
                 catch (error) {
                     if (error instanceof ApiError && (error.status === 401 || error.status === 403))
@@ -173,7 +174,7 @@ export class Runner {
         if (!lease) {
             void this.deps.health?.refresh('job_failed');
             await client
-                .complete({ job_id: job.job.id, error: `this runner has no free ${platform} device for the job` })
+                .complete({ job_id: job.job.id, attempt: job.job.attempt, error: `this runner has no free ${platform} device for the job` })
                 .catch((error) => log.error('could not report the failure', { job_id: job.job.id, error: messageOf(error) }));
             return null;
         }
@@ -311,6 +312,7 @@ export class Runner {
         const { client, log, registry, shared } = this.deps;
         const config = this.config;
         const jobId = job.job.id;
+        const attempt = job.job.attempt;
         const platform = lease.device.platform;
         const redact = redactor([job.credential?.password]);
         let cancelled = false;
@@ -319,13 +321,23 @@ export class Runner {
         log.info('job started', { job_id: jobId, item_id: job.item.id, attempt: job.job.attempt, platform, device: lease.device.id });
         const heartbeat = setInterval(() => {
             client
-                .heartbeat(jobId)
+                .heartbeat(jobId, undefined, attempt)
                 .then((keepGoing) => {
                 if (!keepGoing)
                     cancelled = true;
             })
                 .catch((error) => log.warn('heartbeat failed', { job_id: jobId, error: redact(messageOf(error)) }));
         }, job.job.heartbeat_seconds * 1_000);
+        const progress = progressReporter(async (update) => {
+            try {
+                if (!(await client.heartbeat(jobId, update, attempt)))
+                    cancelled = true;
+            }
+            catch (error) {
+                // An older server refuses the extra field or the network blipped; the timed heartbeat keeps the lease.
+                log.debug('progress report failed', { job_id: jobId, error: redact(messageOf(error)) });
+            }
+        });
         let videoPath;
         try {
             const ctx = jobContext(job, {
@@ -339,7 +351,7 @@ export class Runner {
                 redact,
                 log,
             });
-            const report = await executeClaimedJob(registry, ctx, shared, () => cancelled || this.stopping);
+            const report = await executeClaimedJob(registry, ctx, shared, () => cancelled || this.stopping, progress.report);
             videoPath = report.videoPath;
             if (cancelled) {
                 log.info('job cancelled', { job_id: jobId });
@@ -347,18 +359,27 @@ export class Runner {
                 return;
             }
             if (report.stopped) {
-                await client.complete({ job_id: jobId, error: 'the runner shut down before the job finished' });
+                await client.complete({ job_id: jobId, attempt, error: 'the runner shut down before the job finished' });
                 this.jobFinished(job, 'error', 'the runner shut down before the job finished', [], report.elapsedSecs);
                 return;
             }
+            const passedSteps = report.steps.filter((step) => step.result === 'passed').length;
+            progress.report({
+                phase: 'uploading',
+                step_count: Math.max(job.item.steps.length, report.steps.length),
+                steps_passed: passedSteps,
+                steps_failed: report.steps.length - passedSteps,
+            });
             const stepResults = [];
+            let lostScreenshots = 0;
             for (const step of report.steps) {
                 const attachments = [];
                 for (const shot of step.screenshots) {
                     try {
-                        attachments.push(await client.uploadEvidence(jobId, shot.name, shot.png));
+                        attachments.push(await client.uploadEvidence(jobId, shot.name, shot.png, 'image/png', attempt));
                     }
                     catch (error) {
+                        lostScreenshots++;
                         log.warn('evidence upload failed', { job_id: jobId, error: redact(messageOf(error)) });
                     }
                 }
@@ -374,6 +395,9 @@ export class Runner {
             const notes = [
                 `Automated run on ${job.environment.name} by runner ${config.name}: ${passed} of ${job.item.steps.length} steps passed.`,
             ];
+            if (lostScreenshots > 0) {
+                notes.push(`${lostScreenshots} screenshot${lostScreenshots === 1 ? '' : 's'} could not be uploaded.`);
+            }
             const evidence = [];
             const mode = job.capture?.video ?? 'off';
             const troubled = report.steps.some((step) => step.result !== 'passed');
@@ -385,7 +409,7 @@ export class Runner {
                 else {
                     try {
                         const mp4 = videoPath.toLowerCase().endsWith('.mp4');
-                        evidence.push(await client.uploadEvidence(jobId, mp4 ? 'case-video.mp4' : 'case-video.webm', await readFile(videoPath), mp4 ? 'video/mp4' : 'video/webm'));
+                        evidence.push(await client.uploadEvidence(jobId, mp4 ? 'case-video.mp4' : 'case-video.webm', await readFile(videoPath), mp4 ? 'video/mp4' : 'video/webm', attempt));
                     }
                     catch (error) {
                         log.warn('video upload failed', { job_id: jobId, error: redact(messageOf(error)) });
@@ -395,6 +419,7 @@ export class Runner {
             }
             const outcome = await client.complete({
                 job_id: jobId,
+                attempt,
                 step_results: stepResults,
                 elapsed_secs: report.elapsedSecs,
                 notes: notes.join(' '),
@@ -410,12 +435,13 @@ export class Runner {
             // device, a permission); refresh the report so the runners page says what broke.
             void this.deps.health?.refresh('job_failed');
             await client
-                .complete({ job_id: jobId, error: reason })
+                .complete({ job_id: jobId, attempt, error: reason })
                 .catch((e) => log.error('could not report the failure', { job_id: jobId, error: redact(messageOf(e)) }));
             this.jobFinished(job, 'error', reason, [reason], 0);
         }
         finally {
             clearInterval(heartbeat);
+            progress.stop();
             this.running.delete(jobId);
             // Each job records into its own temporary directory.
             if (videoPath)
@@ -478,7 +504,8 @@ export async function createRunner(options) {
     const home = options.useHome === false ? { file: null, token: null, fixedPermissions: false } : loadFileConfig(paths);
     if (home.fixedPermissions)
         options.log.warn('the token file was readable by others; its permissions were set to 0600', { path: paths.token });
-    const registry = options.registry ?? createRegistry();
+    // The factories follow the runner's environment (not the process's): `RUNNER_DOCKER=1` is web-only.
+    const registry = options.registry ?? createRegistry(defaultFactories(env));
     const host = hostInfo();
     const detection = await detect(registry, host);
     for (const [platform, reasons] of Object.entries(detection.unavailable)) {

package/dist/src/session/execute.js

@@ -1,6 +1,6 @@
 import { Blocked, NotFound, Unsupported } from '../drivers/driver.js';
 import { clampMaxChars, emptyScreen, toSnapshotResult } from '../drivers/snapshot/format.js';
-import { TemplateError } from '../template.js';
+import { redactDeep, TemplateError } from '../template.js';
 import { actionTimeoutMs, CommandError, DEFAULT_COMMAND_TIMEOUT_MS, hardTimeoutMs, validateCommand, } from './commands.js';
 export const MAX_LOG_LINES = 50;
 export const MAX_LOG_CHARS = 500;
@@ -66,7 +66,9 @@ export class SessionExecutor {
         result.logs = this.logs();
         const screenshot = wantsScreenshot ? await this.driver.screenshot().catch(() => null) : null;
         result.duration_ms = Date.now() - started;
-        return { result, screenshot, end };
+        // Everything a session sends is read by an agent and stored; a password shown on the
+        // page can reach any field (element refs, suggestions, the page title), not only the text.
+        return { result: redactDeep(result, this.redact), screenshot, end };
     }
     async perform(command, result) {
         const actions = this.driver.capabilities.actions;

package/dist/src/template.js

@@ -17,6 +17,17 @@ export function redactor(secrets) {
         .sort((a, b) => b.length - a.length);
     return (text) => values.reduce((out, secret) => out.split(secret).join('[redacted]'), text);
 }
+/** Applies `redact` to every string inside `value` (object keys included), leaving its shape alone. */
+export function redactDeep(value, redact) {
+    if (typeof value === 'string')
+        return redact(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactDeep(item, redact));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [redact(k), redactDeep(v, redact)]));
+    }
+    return value;
+}
 function placeholderValue(name, ctx) {
     switch (name) {
         case 'env.base_url':

package/package.json

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