agent-device-lab 0.0.0-stage → 0.3.1

package/dist/core/steps.js

@@ -0,0 +1,80 @@
+/** Resolve a step's role/name targets against the latest observation (never guessed) into a request. */
+export function stepRequest(lab, step) {
+    const hasTarget = step.name !== undefined || step.nameContains !== undefined;
+    const ref = hasTarget ? lab.findRef({ role: step.role, name: step.name, nameContains: step.nameContains }) : undefined;
+    const toRef = step.to ? lab.findRef(step.to) : undefined;
+    const { do: action, value, key, values, direction, amount, dx, dy, files, tab, path } = step;
+    return Object.fromEntries(Object.entries({ action, ref, value, key, values, direction, amount, toRef, dx, dy, files, tab, path })
+        .filter(([, v]) => v !== undefined));
+}
+/** A step aimed at a field with one of these words in its name or role carries a secret: its value is never shown. */
+export const SECRET_FIELD = /pass|secret|token|otp|pin|cvv|cvc/i;
+export const isSecretStep = (s) => SECRET_FIELD.test(`${s.name ?? ''} ${s.nameContains ?? ''} ${s.role ?? ''}`);
+export function describeStep(step) {
+    if (!step.do)
+        return 'check';
+    const has = step.name !== undefined || step.nameContains !== undefined;
+    const target = has ? `${step.role ?? 'control'} ${step.name !== undefined ? JSON.stringify(step.name) : `containing ${JSON.stringify(step.nameContains)}`}` : '';
+    switch (step.do) {
+        // The label is printed before the lab sees the field, so it cannot know a password field by its type:
+        // a fill's value never appears here. The action line that follows shows it when the field is not secret.
+        case 'fill': return `fill ${target}`;
+        // A single character may be part of a password: only named keys (Enter, Tab, Control+a) are shown.
+        case 'press': return `press ${step.key && [...step.key].length === 1 ? 'a character' : step.key}${target ? ` in ${target}` : ''}`;
+        case 'select': return `select ${(step.values ?? []).join(', ')} in ${target}`;
+        case 'scroll':
+        case 'swipe': return `${step.do} ${step.direction ?? 'to'}${target ? ` ${target}` : ''}`;
+        case 'upload': return `upload ${(step.files ?? []).join(', ')} to ${target}`;
+        case 'drag': return `drag ${target} ${step.to ? `onto ${step.to.name}` : `by (${step.dx ?? 0}, ${step.dy ?? 0})`}`;
+        case 'open_tab': return `open tab at ${step.path}`;
+        case 'switch_tab':
+        case 'close_tab': return `${step.do} ${step.tab ?? ''}`.trim();
+        default: return `${step.do}${target ? ` ${target}` : ''}`;
+    }
+}
+const matches = (o, q) => o.controls.filter((c) => (!q.role || c.role === q.role) && (q.name === undefined || c.name === q.name) && (q.nameContains === undefined || c.name.includes(q.nameContains)));
+/** Evaluate expectations against the latest observation and action. Exported for tests. */
+export function check(e, o, action, findings = []) {
+    const checks = [];
+    const add = (ok, text) => checks.push({ ok, text });
+    if (e.route !== undefined)
+        add(o.route === e.route, `route is ${e.route} (got ${o.route})`);
+    if (e.heading !== undefined)
+        add(o.headings.some((h) => h.replace(/^h\d /, '') === e.heading), `heading "${e.heading}" (got ${o.headings.join(' | ') || 'none'})`);
+    if (e.dialog !== undefined) {
+        add(e.dialog === null ? o.dialog === undefined : o.dialog === e.dialog, e.dialog === null ? `no dialog open (got ${o.dialog ?? 'none'})` : `dialog "${e.dialog}" open (got ${o.dialog ?? 'none'})`);
+    }
+    if (e.message !== undefined)
+        add(o.messages.some((m) => m.text.includes(e.message)), `message containing "${e.message}" (got ${o.messages.map((m) => m.text).join(' | ') || 'none'})`);
+    if (e.control) {
+        const { disabled, invalid, ...q } = e.control;
+        const found = matches(o, q).filter((c) => (disabled === undefined || !!c.disabled === disabled) && (invalid === undefined || !!c.invalid === invalid));
+        add(found.length > 0, `control ${JSON.stringify(e.control)} present`);
+    }
+    if (e.noControl)
+        add(matches(o, e.noControl).length === 0, `no control ${JSON.stringify(e.noControl)}`);
+    if (e.layout === 'clean')
+        add(o.layout.length === 0, `no layout flags (got ${o.layout.map((f) => f.kind).join(', ') || 'none'})`);
+    else if (Array.isArray(e.layout)) {
+        for (const want of e.layout) {
+            const hit = o.layout.some((f) => f.kind === want.kind && (!want.name || (!!f.ref && o.controls.some((c) => c.ref === f.ref && c.name === want.name))));
+            add(hit, `layout flag ${want.kind}${want.name ? ` on "${want.name}"` : ''} reported`);
+        }
+    }
+    if (e.note !== undefined)
+        add(!!action?.notes.some((n) => n.includes(e.note)), `action note containing "${e.note}"`);
+    if (e.navigated !== undefined)
+        add(action?.navigated === e.navigated, `navigated is ${e.navigated}`);
+    if (e.tab !== undefined)
+        add((o.tab ?? 't1') === e.tab, `active tab is ${e.tab} (got ${o.tab ?? 't1'})`);
+    if (e.findings === 'none')
+        add(findings.length === 0, `no findings in session (got ${findings.map((f) => `${f.id} ${f.kind}`).join(', ') || 'none'})`);
+    else if (Array.isArray(e.findings)) {
+        for (const want of e.findings) {
+            const hit = findings.find((f) => f.kind === want.kind && (!want.name || f.target?.name === want.name) && (!want.severity || f.severity === want.severity));
+            add(!!hit, `finding ${want.kind}${want.name ? ` on "${want.name}"` : ''}${want.severity ? ` (${want.severity})` : ''} recorded${hit ? ` as ${hit.id}` : ''}`);
+        }
+    }
+    return checks;
+}
+//# sourceMappingURL=steps.js.map

package/dist/core/sweep.js

@@ -0,0 +1,138 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { redactUrlSecrets } from './url-redact.js';
+import { join, relative } from 'node:path';
+import { getDevice } from './devices.js';
+import { measureState } from './checks.js';
+import { installNavTracking, installTimerTracking, waitForDomQuiet } from './extract.js';
+import { settleCauseText } from './format.js';
+import { LabError, SCHEMA_VERSION } from './schema.js';
+export async function runSweep(env, opts) {
+    const devices = opts.devices.map((id) => getDevice(id, env.devices));
+    if (!opts.route.startsWith('/'))
+        throw new LabError('invalid_request', `sweep route must be a path starting with "/", got "${opts.route}"`);
+    const dir = join(env.runDir, 'sweeps', opts.id);
+    mkdirSync(dir, { recursive: true });
+    const t0 = Date.now();
+    const startedAt = new Date().toISOString();
+    env.emit({ kind: 'sweep', phase: 'start', id: opts.id, route: redactUrlSecrets(opts.route), devices: devices.map((d) => ({ id: d.id, width: d.viewport.width, height: d.viewport.height })) });
+    const results = [];
+    let interrupted;
+    for (const [i, device] of devices.entries()) {
+        const stop = env.checkpoint?.();
+        if (stop) {
+            interrupted = { ...stop, skipped: devices.slice(i).map((d) => d.id) };
+            break;
+        }
+        env.emit({ kind: 'sweep', phase: 'device-start', id: opts.id, device: device.id });
+        const r = await sweepDevice(env, opts, device, dir);
+        results.push(r);
+        env.emit({ kind: 'sweep', phase: 'device-done', id: opts.id, result: r });
+    }
+    const ids = new Set(results.flatMap((r) => r.findings));
+    const findings = env.store.list().filter((f) => ids.has(f.id));
+    const report = join(dir, 'report.md');
+    const result = {
+        schemaVersion: SCHEMA_VERSION, id: opts.id, route: redactUrlSecrets(opts.route), startedAt, ms: Date.now() - t0, devices: results, findings, report,
+        ...(interrupted ? { interrupted } : {}),
+    };
+    writeFileSync(report, sweepReportMarkdown(result, dir));
+    writeFileSync(join(dir, 'result.json'), JSON.stringify(result, null, 2));
+    env.emit({ kind: 'sweep', phase: 'done', id: opts.id, result });
+    return result;
+}
+async function sweepDevice(env, opts, device, dir) {
+    const t0 = Date.now();
+    const url = env.origin + opts.route;
+    const base = {
+        device: device.id, label: device.label, width: device.viewport.width, height: device.viewport.height, route: redactUrlSecrets(opts.route),
+        status: 'ok', ms: 0, settled: 'quiet', documentWidth: 0, controls: 0, reachChecked: 0, findings: [],
+    };
+    const context = await env.browser.newContext({
+        viewport: device.viewport, deviceScaleFactor: device.deviceScaleFactor, isMobile: device.isMobile, hasTouch: device.hasTouch,
+        userAgent: device.userAgent, storageState: env.storageState,
+    });
+    let unwatch;
+    try {
+        if (env.settle.timerMaxMs > 0)
+            await context.addInitScript(installTimerTracking);
+        await context.addInitScript(installNavTracking);
+        const page = await context.newPage();
+        unwatch = await env.watch?.(page, device.viewport);
+        const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+        // A scan fails a load error with its HTTP status; a sweep does the same instead of measuring an error page.
+        if (response)
+            base.httpStatus = response.status();
+        if (response && response.status() >= 400) {
+            throw new LabError('http_status', `GET ${redactUrlSecrets(opts.route)} answered HTTP ${response.status()} at ${device.id}; the page was not measured`, {
+                hint: 'Check the route, or that the app serves it when signed in with the session\'s state.', details: { status: response.status(), route: redactUrlSecrets(opts.route) },
+            });
+        }
+        await page.waitForLoadState('load', { timeout: env.settle.maxMs }).catch(() => undefined);
+        base.settled = await page.evaluate(waitForDomQuiet, { quietMs: env.settle.quietMs, maxMs: env.settle.maxMs, timerMaxMs: env.settle.timerMaxMs })
+            .catch(() => 'timeout');
+        if (base.settled !== 'quiet')
+            base.settleCause = base.settled === 'timeout' ? 'dom' : base.settled;
+        const open = `sweep ${opts.id}: open ${redactUrlSecrets(url)} in a new ${device.id} context (${device.viewport.width}x${device.viewport.height}) with the session's cookies and storage`;
+        // The same engine as a scan: the observation's flags, the layout detectors and the reach check.
+        const m = await measureState(page, {
+            store: env.store, sessionId: env.sessionId, gen: env.gen, ctx: { device: device.id }, reproduction: [...env.history, open],
+            detectors: env.detectors, reachLimit: opts.reachLimit ?? 40,
+            frameFile: (suffix) => join(dir, suffix === 'state' ? `${device.id}.jpg` : `${device.id}-${suffix}.jpg`),
+            onFindings: (findings, frame) => env.emit({ kind: 'findings', findings, ...(frame ? { frame } : {}) }),
+        });
+        base.route = m.observation.route;
+        base.documentWidth = m.observation.documentWidth;
+        base.controls = m.observation.controls.length;
+        base.reachChecked = m.reachChecked;
+        if (m.frame)
+            base.frame = m.frame;
+        base.findings = m.findings;
+    }
+    catch (err) {
+        base.status = 'error';
+        base.error = LabError.from(err).toJSON();
+    }
+    finally {
+        await unwatch?.().catch(() => undefined);
+        await context.close().catch(() => undefined);
+    }
+    base.ms = Date.now() - t0;
+    return base;
+}
+const cell = (s) => s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+/** Compact Markdown report: one section per width, confirmed obstructions apart from heuristic warnings. */
+export function sweepReportMarkdown(r, dir) {
+    const byId = new Map(r.findings.map((f) => [f.id, f]));
+    const lines = [
+        `# Responsive sweep ${r.id}: ${r.route}`,
+        '',
+        `${r.startedAt} · ${r.devices.length} widths, serial, one isolated browser context each · ${r.ms} ms`,
+        '',
+        '**Confirmed** findings were measured by the reach check (a sideways pan was needed, or the centre is covered after scrolling into view). **Heuristic** findings are layout warnings that often, but not always, hurt a person.',
+        '',
+        '| device | width | status | document width | controls | confirmed | heuristic | frame |',
+        '| --- | --- | --- | --- | --- | --- | --- | --- |',
+    ];
+    for (const d of r.devices) {
+        const fs = d.findings.map((id) => byId.get(id)).filter((f) => !!f);
+        const confirmed = fs.filter((f) => f.confidence === 'confirmed').length;
+        lines.push(`| ${d.device} | ${d.width} | ${d.status === 'ok' ? `ok (${d.settled === 'quiet' ? 'quiet' : cell(`settle timed out: ${settleCauseText(d.settleCause ?? 'dom')}`)})` : `error: ${cell(`${d.error?.code ?? ''} ${d.error?.message ?? ''}`.trim())}`} | ${d.documentWidth} | ${d.controls} (${d.reachChecked} reach-checked) | ${confirmed} | ${fs.length - confirmed} | ${d.frame ? `[${d.device}.jpg](${relative(dir, d.frame)})` : '–'} |`);
+    }
+    for (const d of r.devices) {
+        const fs = d.findings.map((id) => byId.get(id)).filter((f) => !!f);
+        lines.push('', `## ${d.device} (${d.width}×${d.height}) · ${d.route}`, '');
+        if (!fs.length) {
+            lines.push('No findings.');
+            continue;
+        }
+        lines.push('| id | confidence | severity | finding | measurements | reproduction |', '| --- | --- | --- | --- | --- | --- |');
+        for (const f of [...fs].sort((a, b) => (a.confidence === b.confidence ? 0 : a.confidence === 'confirmed' ? -1 : 1))) {
+            const evidence = Object.entries(f.evidence).map(([k, v]) => `${k}=${v}`).join(', ');
+            const repro = f.reproduction.slice(-3).map((s, i, a) => `${f.reproduction.length - a.length + i + 1}. ${s}`).join('<br>');
+            lines.push(`| ${f.id} | ${f.confidence} | ${f.severity} | ${cell(`${f.kind}: ${f.message}`)} | ${cell(evidence)} | ${cell(repro)} |`);
+        }
+    }
+    lines.push('', 'Full reproduction steps and evidence frames: `result.json` and the `.jpg` files next to this report.');
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=sweep.js.map