@sifurai/cli 0.1.0 → 0.1.2

package/dist/apply.js

@@ -0,0 +1,143 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { ApiError, CliError } from './api.js';
+import { parseTicketRef, resolveTicket } from './resolve.js';
+import { APPLIED, pruneTicketDir, ticketDir } from './store.js';
+import { defaultWorkdirFor, gitTopLevel } from './workspace.js';
+const INDEX = 'checkouts.json';
+function git(dir, args, input) {
+    const result = spawnSync('git', args, { cwd: dir, input, encoding: 'utf8', maxBuffer: 1024 * 1024 * 1024 });
+    if (result.error)
+        throw new CliError(`Couldn't run git in ${dir}: ${result.error.message}`);
+    return { ok: result.status === 0, stdout: result.stdout ?? '', stderr: (result.stderr ?? '').trim() };
+}
+const patchFile = (repository) => `${repository.replace(/[^A-Za-z0-9_.-]/g, '_')}.patch`;
+function filesIn(dir, patch) {
+    const numstat = git(dir, ['apply', '--numstat'], patch);
+    return numstat.ok ? numstat.stdout.split('\n').filter(Boolean).length : 0;
+}
+async function readIndex(dir) {
+    try {
+        return JSON.parse(await readFile(join(dir, INDEX), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** A key names its folder; a uuid is looked for among the tickets with applied changes. */
+async function findAppliedDir(store, ref) {
+    const direct = join(ticketDir(store, ref.toUpperCase()), APPLIED);
+    if (await readIndex(direct))
+        return direct;
+    let entries;
+    try {
+        entries = await readdir(store);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        const dir = join(store, entry, APPLIED);
+        if ((await readIndex(dir))?.ticketUuid === ref.toLowerCase())
+            return dir;
+    }
+    return null;
+}
+/**
+ * Puts Sifur's unpushed work for a ticket in the engineer's checkouts, uncommitted, so they can deploy it.
+ * Every checkout is checked before any patch is applied.
+ */
+export async function applyChanges(api, ref, options, io) {
+    const { ticketUuid, key, organization } = await resolveTicket(api, ref);
+    let patches;
+    try {
+        patches = (await api.request(`tickets/${ticketUuid}/changes/patch`, { organization: organization.uuid })) ?? [];
+    }
+    catch (error) {
+        if (error instanceof ApiError && [404, 409].includes(error.status))
+            throw new CliError(`Sifur has no changes for ${ref} to apply: ${error.message}`);
+        throw error;
+    }
+    if (patches.length === 0)
+        io.out(`${ref}: nothing to apply.`);
+    const withChanges = patches.filter((p) => p.patch.trim() !== '');
+    for (const p of patches)
+        if (!withChanges.includes(p))
+            io.out(`${p.repository}: nothing to apply.`);
+    if (withChanges.length === 0)
+        return;
+    const appliedDir = join(ticketDir(options.store, key ?? ('uuid' in parseTicketRef(ref) ? ref : ref.toUpperCase())), APPLIED);
+    const index = (await readIndex(appliedDir)) ?? { ticketUuid, checkouts: {} };
+    let workdirs = options.workdirs ?? {};
+    const named = new Set(patches.map((p) => p.repository));
+    const top = gitTopLevel(options.cwd);
+    for (const p of withChanges) {
+        const picked = defaultWorkdirFor(named, [p.repository], workdirs, top);
+        if (picked.chosen)
+            io.out(`Applying ${picked.chosen.repository}'s changes in ${picked.chosen.dir} (the checkout you're in).`);
+        workdirs = picked.workdirs;
+    }
+    const plan = [];
+    for (const p of withChanges) {
+        const given = workdirs[p.repository];
+        if (!given)
+            throw new CliError(`No checkout of ${p.repository}: run this from inside it, or pass --workdir ${p.repository}=<dir>.`);
+        const dir = resolve(given);
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            throw new CliError(`--workdir ${p.repository}=${given}: no such directory.`);
+        const saved = join(appliedDir, patchFile(p.repository));
+        if (existsSync(saved)) {
+            throw new CliError(`Sifur's changes to ${p.repository} are already applied. Run \`sifur apply ${key ?? ref} --revert\` first, or delete ${saved} if you've taken them out yourself.`);
+        }
+        const status = git(dir, ['status', '--porcelain', '--untracked-files=no']);
+        if (!status.ok)
+            throw new CliError(`${dir} isn't a git checkout: ${status.stderr}`);
+        if (status.stdout.trim())
+            throw new CliError(`${dir} has uncommitted changes. Commit or stash them, then run this again.`);
+        if (!git(dir, ['cat-file', '-e', `${p.base}^{commit}`]).ok) {
+            throw new CliError(`${dir} doesn't have ${p.base.slice(0, 12)}, the commit Sifur's changes to ${p.repository} start from. Run \`git fetch\` and check out ${p.branch} first.`);
+        }
+        plan.push({ patch: p, dir });
+    }
+    await mkdir(appliedDir, { recursive: true });
+    for (const { patch, dir } of plan) {
+        const applied = git(dir, ['apply', '--3way', '--whitespace=nowarn'], patch.patch);
+        if (!applied.ok) {
+            throw new CliError(`Couldn't apply Sifur's changes to ${patch.repository} in ${dir} cleanly:\n${applied.stderr}\nSee \`git status\` there: resolve the conflicts, or put the checkout back as it was with \`git reset --hard\`.`);
+        }
+        await writeFile(join(appliedDir, patchFile(patch.repository)), patch.patch);
+        index.checkouts[patch.repository] = dir;
+        await writeFile(join(appliedDir, INDEX), `${JSON.stringify(index, null, 2)}\n`);
+        const count = filesIn(dir, patch.patch);
+        io.out(`${patch.repository}: applied Sifur's changes to ${count} file${count === 1 ? '' : 's'} in ${dir} (${patch.head.slice(0, 7)} on ${patch.branch}). Nothing was committed.`);
+    }
+}
+/** Takes back out what `applyChanges` put in, from the patches it saved. Needs no connection to Sifur. */
+export async function revertChanges(ref, options, io) {
+    const appliedDir = await findAppliedDir(options.store, ref);
+    const index = appliedDir ? await readIndex(appliedDir) : null;
+    const repositories = Object.keys(index?.checkouts ?? {}).filter((r) => existsSync(join(appliedDir, patchFile(r))));
+    if (!appliedDir || !index || repositories.length === 0) {
+        io.out(`Nothing from ${ref} is applied.`);
+        return;
+    }
+    for (const repository of repositories) {
+        const dir = resolve(options.workdirs?.[repository] ?? index.checkouts[repository]);
+        const saved = join(appliedDir, patchFile(repository));
+        const patch = await readFile(saved, 'utf8');
+        const reverted = git(dir, ['apply', '-R', '--3way', '--whitespace=nowarn'], patch);
+        if (!reverted.ok) {
+            throw new CliError(`Couldn't take Sifur's changes to ${repository} back out of ${dir}:\n${reverted.stderr}\nThe patch is kept in ${saved}.`);
+        }
+        await rm(saved);
+        delete index.checkouts[repository];
+        await writeFile(join(appliedDir, INDEX), `${JSON.stringify(index, null, 2)}\n`);
+        io.out(`${repository}: took Sifur's changes back out of ${dir}.`);
+    }
+    if (Object.keys(index.checkouts).length === 0) {
+        await rm(appliedDir, { recursive: true, force: true });
+        await pruneTicketDir(options.store, dirname(appliedDir));
+    }
+}

package/dist/automated.js

@@ -22,7 +22,42 @@ export function runAutomated(command, cwd, options = {}) {
                 status: code === 0 ? 'passed' : 'failed',
                 note: `\`${command}\` ${ended}.${tail ? `\n${tail}` : ''}`,
                 output,
+                exitCode: code,
             });
         });
     });
 }
+/** The shell's "command not found" and "not executable": the checkout can't run the test, which says nothing about the ticket. */
+export const COULD_NOT_RUN = new Set([126, 127]);
+/** The program a command runs: its first word, past any `cd … &&` and VAR=value prefixes. */
+export function programOf(command) {
+    const segment = command.split(/&&|\|\||;/).map((s) => s.trim()).find((s) => s && !/^cd(\s|$)/.test(s)) ?? command.trim();
+    const words = segment.split(/\s+/).filter((w) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w));
+    return words[0] ?? segment;
+}
+/** The program the shell said it couldn't find, as in `sh: mocha: command not found`. */
+export function notFoundIn(output) {
+    const match = /(?:^|\n)[^\n:]*?:\s*(?:line \d+:\s*)?([^\s:]+):\s*(?:command )?not found/.exec(output);
+    return match?.[1] ?? null;
+}
+const SCRIPT_RUNNERS = new Set(['npm', 'yarn', 'pnpm']);
+export function missingProgram(command, exitCode, workdir, output = '') {
+    const program = programOf(command);
+    const words = command.trim().split(/\s+/);
+    // `npm run x` ran: what's missing is the tool its script calls, installed by `npm install`.
+    const reported = notFoundIn(output);
+    if (reported && reported !== program && SCRIPT_RUNNERS.has(program)) {
+        return `\`${reported}\` isn't installed in ${workdir}: run \`${program} install\`?`;
+    }
+    if (program === 'npx') {
+        const runs = words.slice(words.indexOf('npx') + 1).find((w) => !w.startsWith('-')) ?? 'its package';
+        return `\`npx\` couldn't run ${runs} in ${workdir}: run \`npm install\`?`;
+    }
+    const where = program.includes('/') ? `in ${workdir}` : 'on your PATH';
+    let message = exitCode === 126 ? `\`${program}\` isn't executable ${where}` : `\`${program}\` isn't ${where}`;
+    if (/(^|\/)vendor\/bin\//.test(program))
+        message += ': run `composer install`?';
+    else if (/(^|\/)node_modules\/\.bin\//.test(program))
+        message += ': run `npm install`?';
+    return message;
+}

package/dist/cli.js

@@ -1,14 +1,19 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { accept } from './accept.js';
 import { Api, ApiError, CliError, DEFAULT_API, normalizeApi } from './api.js';
-import { loadCredentials } from './config.js';
+import { applyChanges, revertChanges } from './apply.js';
+import { cacheDir, loadCredentials } from './config.js';
 import { login, logout } from './login.js';
+import { LEGACY_STORE } from './store.js';
 const USAGE = `Usage:
   sifur login [--api <url>]
   sifur logout
-  sifur accept <KEY|uuid> --url <test url> [--headed] [--workdir <repo>=<dir> …]
-  sifur accept <KEY|uuid> --download
+  sifur apply <KEY|uuid> [--workdir <repo>=<dir> …]
+  sifur apply <KEY|uuid> --revert
+  sifur accept <KEY|uuid> --url <test url> [--apply] [--headed] [--workdir <repo>=<dir> …]
+  sifur accept <KEY|uuid> --download [--apply]
   sifur accept <KEY|uuid> --run --url <test url> [--headed] [--workdir <repo>=<dir> …]
   sifur accept <KEY|uuid> --upload
 
@@ -16,8 +21,12 @@ Options:
   --api <url>              Sifur's API (default ${DEFAULT_API}, or SIFUR_API_URL)
   --url <url>              Your test server, where the ticket's branch is deployed
   --headed                 Show the browser while the cases run
-  --workdir <repo>=<dir>   Run that repository's automated cases in <dir>; repeatable
-  --download               Save the cases to ./.sifur/<KEY>/ (before a full-tunnel VPN is up)
+  --timeout <seconds>      How long each browser step may take (default 60; raise it for a slow VPN)
+  --apply                  Put Sifur's changes in your checkouts first, uncommitted, as \`sifur apply\` does
+  --revert                 Take the changes \`sifur apply\` put in back out
+  --workdir <repo>=<dir>   Run that repository's automated cases in <dir>; repeatable. Without it,
+                           the git checkout you're in, when it's that repository's
+  --download               Save the cases to ${cacheDir()}/<KEY>/ (before a full-tunnel VPN is up)
   --run                    Run the saved cases and save the results (no connection to Sifur)
   --upload                 Send the saved results (after the VPN is down)
 
@@ -42,6 +51,15 @@ export function parseWorkdirs(values) {
     }
     return workdirs;
 }
+const DEFAULT_TIMEOUT_SECONDS = 60;
+export function timeoutSeconds(value) {
+    if (value === undefined)
+        return DEFAULT_TIMEOUT_SECONDS;
+    const seconds = Number(value);
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        throw new CliError(`--timeout ${value}: expected a number of seconds.`);
+    return seconds;
+}
 export async function main(argv, io, env = process.env, cwd = process.cwd()) {
     const { values, positionals } = parseArgs({
         args: argv,
@@ -50,10 +68,13 @@ export async function main(argv, io, env = process.env, cwd = process.cwd()) {
             api: { type: 'string' },
             url: { type: 'string' },
             headed: { type: 'boolean', default: false },
+            timeout: { type: 'string' },
             workdir: { type: 'string', multiple: true, default: [] },
             download: { type: 'boolean', default: false },
             run: { type: 'boolean', default: false },
             upload: { type: 'boolean', default: false },
+            apply: { type: 'boolean', default: false },
+            revert: { type: 'boolean', default: false },
             help: { type: 'boolean', short: 'h', default: false },
             version: { type: 'boolean', short: 'v', default: false },
         },
@@ -69,6 +90,9 @@ export async function main(argv, io, env = process.env, cwd = process.cwd()) {
     }
     const explicitApi = values.api ?? env.SIFUR_API_URL;
     const userAgent = `sifur-cli/${version()} node/${process.versions.node}`;
+    if ((command === 'accept' || command === 'apply') && existsSync(join(cwd, LEGACY_STORE))) {
+        io.out(`${join(cwd, LEGACY_STORE)} is left over from sifur 0.1.0, which kept its files there; nothing uses it now, so it can be deleted.`);
+    }
     switch (command) {
         case 'login': {
             const api = new Api(explicitApi ?? DEFAULT_API, null, userAgent);
@@ -78,6 +102,18 @@ export async function main(argv, io, env = process.env, cwd = process.cwd()) {
         case 'logout':
             await logout(io, env);
             return 0;
+        case 'apply': {
+            const ref = rest[0];
+            if (!ref || rest.length > 1)
+                throw new CliError('Usage: sifur apply <KEY|uuid> [--workdir <repo>=<dir> …]');
+            const options = { workdirs: parseWorkdirs(values.workdir ?? []), cwd, store: cacheDir(env) };
+            if (values.revert) {
+                await revertChanges(ref, options, io);
+                return 0;
+            }
+            await applyChanges(signedIn(await loadCredentials(env), explicitApi, userAgent), ref, options, io);
+            return 0;
+        }
         case 'accept': {
             const ref = rest[0];
             if (!ref || rest.length > 1)
@@ -87,15 +123,7 @@ export async function main(argv, io, env = process.env, cwd = process.cwd()) {
                 throw new CliError('Use one of --download, --run and --upload at a time.');
             const mode = modes[0] ?? 'full';
             const credentials = await loadCredentials(env);
-            let api = null;
-            if (mode !== 'run') {
-                if (!credentials)
-                    throw new CliError('Not signed in. Run `sifur login` first.');
-                if (explicitApi && normalizeApi(explicitApi) !== normalizeApi(credentials.api)) {
-                    throw new CliError(`You're signed in to ${credentials.api}, not ${explicitApi}. Run \`sifur login --api ${explicitApi}\`.`);
-                }
-                api = new Api(credentials.api, credentials.token, userAgent);
-            }
+            const api = mode !== 'run' || values.apply ? signedIn(credentials, explicitApi, userAgent) : null;
             return accept(api, {
                 ref,
                 mode,
@@ -103,18 +131,28 @@ export async function main(argv, io, env = process.env, cwd = process.cwd()) {
                 headed: values.headed,
                 workdirs: parseWorkdirs(values.workdir ?? []),
                 cwd,
+                store: cacheDir(env),
+                apply: values.apply,
                 consoleOrigin: env.SIFUR_CONSOLE_URL ?? credentials?.console ?? null,
-            }, { io, env });
+            }, { io, env, timeoutMs: timeoutSeconds(values.timeout) * 1000 });
         }
         default:
             throw new CliError(`Unknown command "${command}".\n\n${USAGE}`);
     }
 }
+function signedIn(credentials, explicitApi, userAgent) {
+    if (!credentials)
+        throw new CliError('Not signed in. Run `sifur login` first.');
+    if (explicitApi && normalizeApi(explicitApi) !== normalizeApi(credentials.api)) {
+        throw new CliError(`You're signed in to ${credentials.api}, not ${explicitApi}. Run \`sifur login --api ${explicitApi}\`.`);
+    }
+    return new Api(credentials.api, credentials.token, userAgent);
+}
 export function describeError(error) {
     if (error instanceof ApiError && error.status === 401)
         return 'Your sign-in has expired or was revoked. Run `sifur login` again.';
     if (error instanceof ApiError)
-        return `Sifur answered ${error.status}: ${error.message}`;
+        return error.fromSifur ? `Sifur answered ${error.status}: ${error.message}` : error.message;
     if (error instanceof CliError)
         return error.message;
     if (error instanceof TypeError && error.code?.startsWith('ERR_PARSE_ARGS'))

package/dist/config.js

@@ -8,6 +8,12 @@ export function configDir(env = process.env, platform = process.platform) {
         return join(env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'sifur');
     return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'sifur');
 }
+/** Where downloaded cases, results and screenshots are kept: outside the engineer's checkout. */
+export function cacheDir(env = process.env, platform = process.platform) {
+    if (platform === 'win32')
+        return join(env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'sifur');
+    return join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'sifur');
+}
 export function credentialsPath(env = process.env) {
     return join(configDir(env), 'credentials.json');
 }

package/dist/login.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { hostname, userInfo } from 'node:os';
-import { Api, ApiError, CliError } from './api.js';
+import { Api, ApiError, CliError, DEFAULT_API } from './api.js';
 import { deleteCredentials, loadCredentials, saveCredentials } from './config.js';
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export function openInBrowser(url) {
@@ -43,10 +43,21 @@ export async function login(api, deps) {
     const { io } = deps;
     const sleep = deps.sleep ?? wait;
     const now = deps.now ?? Date.now;
-    const start = await api.request('auth/device', {
-        method: 'POST',
-        body: { clientName: (deps.clientName ?? defaultClientName()).slice(0, 100) },
-    });
+    const notSifur = new CliError(`${api.base} isn't Sifur's API. --api is Sifur's address (for example ${DEFAULT_API}); your test server goes in \`accept --url\`.`);
+    let start;
+    try {
+        start = await api.request('auth/device', {
+            method: 'POST',
+            body: { clientName: (deps.clientName ?? defaultClientName()).slice(0, 100) },
+        });
+    }
+    catch (error) {
+        if (error instanceof ApiError && (!error.json || [404, 405, 419].includes(error.status)))
+            throw notSifur;
+        throw error;
+    }
+    if (!start?.deviceCode || !start.userCode || !start.verificationUrl)
+        throw notSifur;
     const url = withCode(start.verificationUrl, start.userCode);
     io.out(`Your code: ${start.userCode}`);
     io.out(`Approve it at ${url}`);

package/dist/resolve.js

@@ -23,7 +23,8 @@ export async function resolveTicket(api, ref) {
             const ticket = await api.request(path, { organization: organization.uuid });
             if (!ticket?.uuid)
                 throw new CliError(`Sifur found ${ref} but didn't say which ticket it is.`);
-            return { ticketUuid: ticket.uuid, organization };
+            const key = ticket.key ?? ('projectKey' in parsed ? `${parsed.projectKey}-${parsed.number}` : null);
+            return { ticketUuid: ticket.uuid, key, organization };
         }
         catch (error) {
             if (error instanceof ApiError && [403, 404].includes(error.status))

package/dist/results.js

@@ -25,8 +25,12 @@ export function combine(statuses) {
         return 'failed';
     if (statuses.includes('blocked'))
         return 'blocked';
+    if (statuses.length > 0 && statuses.every((status) => status === 'skipped'))
+        return 'skipped';
     return 'passed';
 }
+/** Judged on the cases that ran, as Sifur judges it: a run where nothing ran proves nothing. */
 export function outcome(results) {
-    return combine(results.map((result) => result.status));
+    const ran = results.filter((result) => result.status !== 'skipped');
+    return ran.length === 0 ? 'skipped' : combine(ran.map((result) => result.status));
 }

package/dist/runner.js

@@ -1,8 +1,8 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { redact, withSecrets } from './secrets.js';
+import { newRunToken, redact, resolveStep } from './secrets.js';
 const ASSERTIONS = new Set(['expectText', 'expectVisible', 'expectUrl']);
-const TIMEOUT = 15_000;
+const TIMEOUT = 60_000;
 // An assertion after an action waits for the page to settle, as Playwright's own do: a
 // response that lands half a second later still counts.
 export async function eventually(check, timeoutMs = 10_000) {
@@ -18,46 +18,81 @@ export async function eventually(check, timeoutMs = 10_000) {
         }
     }
 }
-function first(page, selector) {
+/**
+ * The first visible match in the page or any of its frames: older apps put whole screens in
+ * iframes, where the top page's locator never looks.
+ */
+async function find(page, selector, timeoutMs) {
     if (!selector)
         throw new Error('the step has no selector');
-    return page.locator(selector).first();
+    return eventually(async () => {
+        for (const frame of page.frames()) {
+            const match = frame.locator(selector).first();
+            if ((await match.count()) > 0 && (await match.isVisible().catch(() => false)))
+                return match;
+        }
+        throw new Error(`nothing visible matches ${selector}, in the page or its frames`);
+    }, timeoutMs);
+}
+/** The text of every frame's body: what a person reading the screen sees. */
+async function screenText(page) {
+    const texts = await Promise.all(page.frames().map((frame) => frame.locator('body').innerText().catch(() => '')));
+    return texts.join('\n');
 }
-async function perform(page, step, baseUrl, secrets, settleMs) {
-    const url = step.url ? new URL(step.url, baseUrl).toString() : null;
+/**
+ * A case's path under `--url`, which may be the app's folder rather than the site's root
+ * (`https://test.example/team/app/`): `/login.php`, `login.php` and `#list` all open under it.
+ * A full URL is used as is.
+ */
+export function caseUrl(path, baseUrl) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(path))
+        return path;
+    const base = new URL(baseUrl);
+    base.search = '';
+    base.hash = '';
+    // `…/app/login.php` is a page in the app's folder; `…/app` is the folder itself.
+    if (!base.pathname.endsWith('/')) {
+        base.pathname = /\.[a-z0-9]+$/i.test(base.pathname)
+            ? base.pathname.replace(/[^/]*$/, '')
+            : `${base.pathname}/`;
+    }
+    return new URL(path.replace(/^\/+/, ''), base).toString();
+}
+async function perform(page, step, baseUrl, settleMs) {
+    const url = step.url ? caseUrl(step.url, baseUrl) : null;
     switch (step.action) {
         case 'goto':
             if (!url)
                 throw new Error('the step has no url');
-            await page.goto(url, { waitUntil: 'networkidle' });
+            // `load`, not `networkidle`: an app that polls never goes quiet, least of all over a VPN.
+            await page.goto(url, { waitUntil: 'load' });
             break;
         case 'click':
-            await first(page, step.selector).click();
+            await (await find(page, step.selector, settleMs)).click();
             break;
         case 'fill':
-            await first(page, step.selector).fill(withSecrets(String(step.value ?? ''), secrets));
+            await (await find(page, step.selector, settleMs)).fill(String(step.value ?? ''));
             break;
         case 'press':
-            await first(page, step.selector).press(String(step.value));
+            await (await find(page, step.selector, settleMs)).press(String(step.value));
             break;
         case 'select':
-            await first(page, step.selector).selectOption(String(step.value));
+            await (await find(page, step.selector, settleMs)).selectOption(String(step.value));
             break;
         case 'wait':
             await page.waitForTimeout(Math.min(Number(step.value ?? 500), 10_000));
             break;
         case 'expectText': {
-            const target = step.selector ? page.locator(step.selector).first() : page.locator('body');
-            await target.waitFor();
+            const selector = step.selector;
             await eventually(async () => {
-                const text = await target.innerText();
+                const text = selector ? await (await find(page, selector, 0)).innerText() : await screenText(page);
                 if (!text.includes(String(step.text)))
-                    throw new Error(`expected "${step.text}" in ${step.selector ?? 'the page'}`);
+                    throw new Error(`expected "${step.text}" in ${selector ?? 'the page'}`);
             }, settleMs);
             break;
         }
         case 'expectVisible':
-            await first(page, step.selector).waitFor({ state: 'visible' });
+            await find(page, step.selector, settleMs);
             break;
         case 'expectUrl':
             await eventually(async () => {
@@ -72,9 +107,38 @@ async function perform(page, step, baseUrl, secrets, settleMs) {
             throw new Error(`unknown action ${step.action}`);
     }
 }
+/** What a step does, for one with no caption: a screenshot labeled "expectText" says nothing. */
+export function describe(step) {
+    const target = step.selector ?? '';
+    switch (step.action) {
+        case 'goto':
+            return `Open ${step.url ?? ''}`.trim();
+        case 'click':
+            return `Click ${target}`.trim();
+        case 'fill':
+            return `Type into ${target}`.trim();
+        case 'press':
+            return `Press ${step.value ?? ''} in ${target}`.trim();
+        case 'select':
+            return `Choose ${step.value ?? ''} in ${target}`.trim();
+        case 'wait':
+            return `Wait ${Number(step.value ?? 500) / 1000}s`;
+        case 'expectText':
+            return `Expect "${step.text ?? ''}"${target ? ` in ${target}` : ''}`;
+        case 'expectVisible':
+            return `Expect ${target} to show`;
+        case 'expectUrl':
+            return `Expect the address to contain "${step.text ?? ''}"`;
+        case 'judge':
+            return 'Check the screen';
+        default:
+            return step.action;
+    }
+}
 /** One case's UI script, as the sandbox's runner plays it: a screenshot after every step, stopping at the first failure. */
 export async function runUiCase(browser, testCase, options) {
     const secrets = options.secrets ?? {};
+    const runToken = options.runToken ?? newRunToken();
     const dir = join(options.outDir, testCase.id);
     await mkdir(dir, { recursive: true });
     // Light, always: an app that follows the system theme is judged in one, the same every run.
@@ -87,11 +151,12 @@ export async function runUiCase(browser, testCase, options) {
     try {
         for (const [index, step] of (testCase.uiScript ?? []).entries()) {
             const n = index + 1;
-            const caption = step.caption ?? step.action;
+            const caption = redact(step.caption ?? describe(step), secrets);
             let ok = true;
             let error = null;
+            options.onStep?.(n, caption);
             try {
-                await perform(page, step, options.baseUrl, secrets, Math.min(10_000, options.timeoutMs ?? 10_000));
+                await perform(page, resolveStep(step, secrets, runToken), options.baseUrl, options.timeoutMs ?? TIMEOUT);
             }
             catch (caught) {
                 ok = false;