ea428d3c98
app/tool/capture: one Chrome DevTools capture CLI over the full-app fixture (serve build or URL, private headless Chrome or --cdp attach, label/key/xy clicks via Flutter semantics, type, press, scroll, screenshots, filmed clicks with a canvas contact sheet, cleanup on exit/signal), README recipes and an example script. The fixture entry gains ?theme=light|dark. app/tool/memwatch: run.sh/full.sh watchdog moved from /tmp (output dir created if missing, exit status propagated) plus install.sh for the legacy /tmp/memwatch shims. app/AGENTS.md points tests at full.sh and UI review at the capture kit.
143 lines
6.9 KiB
JavaScript
143 lines
6.9 KiB
JavaScript
#!/usr/bin/env node
|
|
// Generic browser capture kit for the Flutter app. See README.md beside this file.
|
|
//
|
|
// node tool/capture/capture.mjs --build build/probe-app --out /tmp/shots \
|
|
// open=/runs/7 shot=summary click=Artifacts shot=artifacts
|
|
//
|
|
// Serves a build (or takes --url), launches private headless Chrome (or
|
|
// attaches with --cdp), runs the steps, writes NN-<name>.png files plus
|
|
// report.json into --out, and always removes Chrome, its profile and the server.
|
|
import { mkdir, readFile, writeFile } from 'node:fs/promises';
|
|
import { join, resolve } from 'node:path';
|
|
import { setTimeout as delay } from 'node:timers/promises';
|
|
import { openBrowser } from './browser.mjs';
|
|
import { serveBuild } from './serve.mjs';
|
|
import { contactSheet, pickFrames } from './sheet.mjs';
|
|
import { describe, flutterPage, parseTarget } from './page.mjs';
|
|
|
|
const USAGE = `usage: capture.mjs (--build <dir> | --url <url>) --out <dir> [options] [steps...]
|
|
options: --script <steps.json> --size WxH (880x1000) --platform material|cupertino
|
|
--theme light|dark --q <search> --wait <ms after actions, 1000>
|
|
--film-ms <ms, 900> --cdp http://127.0.0.1:<port> --probe true|false
|
|
steps: open=<route>[@WxH] wait=<ms> shot=<name> click=<target> waitfor=<target>
|
|
type=<text> press=<Enter|Escape|Tab|...> scroll=<dy> size=WxH
|
|
film=<target> labels=<name>
|
|
target: <label> | label:<label> | key:<semantics identifier> | x,y`;
|
|
|
|
const opts = { size: '880x1000', wait: '1000', 'film-ms': '900' };
|
|
const cliSteps = [];
|
|
const argv = process.argv.slice(2);
|
|
for (let i = 0; i < argv.length; i++) {
|
|
if (argv[i] === '-h' || argv[i] === '--help') { console.log(USAGE); process.exit(0); }
|
|
if (argv[i].startsWith('--')) opts[argv[i].slice(2)] = argv[++i];
|
|
else {
|
|
const at = argv[i].indexOf('=');
|
|
if (at < 1) { console.error(`bad step ${JSON.stringify(argv[i])}\n${USAGE}`); process.exit(2); }
|
|
cliSteps.push({ [argv[i].slice(0, at)]: argv[i].slice(at + 1) });
|
|
}
|
|
}
|
|
if (!opts.out || (!opts.build && !opts.url)) { console.error(USAGE); process.exit(2); }
|
|
|
|
let steps = cliSteps;
|
|
if (opts.script) {
|
|
const script = JSON.parse(await readFile(opts.script, 'utf8'));
|
|
const list = Array.isArray(script) ? script : script.steps;
|
|
if (!Array.isArray(script)) for (const k of ['size', 'platform', 'theme', 'q']) if (script[k] && !opts[k]) opts[k] = script[k];
|
|
steps = [...list, ...cliSteps];
|
|
}
|
|
const out = resolve(opts.out);
|
|
await mkdir(out, { recursive: true });
|
|
const probe = opts.probe ? opts.probe === 'true' : Boolean(opts.build);
|
|
const settle = Number(opts.wait);
|
|
const size = (s) => { const [w, h] = String(s).split('x').map(Number); if (!w || !h) throw new Error(`bad size ${s}`); return { width: w, height: h }; };
|
|
const log = (line) => console.log(line);
|
|
|
|
let server, browser;
|
|
let cleaning;
|
|
const cleanup = () => cleaning ??= (async () => {
|
|
await browser?.close().catch((e) => log(`chrome cleanup: ${e.message}`));
|
|
await server?.close().catch(() => {});
|
|
})();
|
|
for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => cleanup().then(() => process.exit(130)));
|
|
|
|
const report = { started: new Date().toISOString(), steps: [], files: [], errors: [] };
|
|
let n = 0;
|
|
const file = (name, ext = 'png') => join(out, `${String(++n).padStart(2, '0')}-${name.replace(/[^\w.-]+/g, '_')}.${ext}`);
|
|
const save = async (path, data) => { await writeFile(path, data); report.files.push(path); log(` wrote ${path}`); return path; };
|
|
|
|
function routeUrl(step, base) {
|
|
const route = step.open;
|
|
const params = { platform: step.platform ?? opts.platform, theme: step.theme ?? opts.theme, q: step.q ?? opts.q };
|
|
let url;
|
|
if (/^https?:/.test(route)) url = new URL(route);
|
|
else if (probe) { url = new URL('/', base); url.searchParams.set('route', route); }
|
|
else url = new URL(route, base);
|
|
for (const [k, v] of Object.entries(params)) if (v) url.searchParams.set(k, v);
|
|
return url.href;
|
|
}
|
|
|
|
let page;
|
|
let exitCode = 0;
|
|
try {
|
|
const base = opts.build ? (server = await serveBuild(opts.build)).origin : opts.url;
|
|
browser = await openBrowser({ cdp: opts.cdp });
|
|
page = flutterPage(browser, log);
|
|
for (const step of steps) {
|
|
const [verb] = Object.keys(step);
|
|
const value = step[verb];
|
|
log(`${verb} ${typeof value === 'object' ? JSON.stringify(value) : value}`);
|
|
report.steps.push(step);
|
|
switch (verb) {
|
|
case 'open': {
|
|
const [route, at] = String(value).split('@');
|
|
const { width, height } = size(step.size ?? at ?? opts.size);
|
|
const url = routeUrl({ ...step, open: route }, base);
|
|
log(` ${url} at ${width}x${height}`);
|
|
await page.open(url, { width, height, theme: step.theme ?? opts.theme });
|
|
break;
|
|
}
|
|
case 'size': await page.resize(size(value).width, size(value).height); await delay(settle); break;
|
|
case 'wait': await delay(Number(value)); break;
|
|
case 'shot': await save(file(value || 'shot'), await page.shot()); break;
|
|
case 'click': {
|
|
const hit = await page.click(value, step.timeout);
|
|
log(` clicked ${describe(parseTarget(value))} at ${Math.round(hit.x)},${Math.round(hit.y)} ${hit.text ? JSON.stringify(hit.text) : ''}`);
|
|
await delay(step.wait ?? settle);
|
|
break;
|
|
}
|
|
case 'waitfor': await page.waitFor(value, step.timeout ?? 10000); break;
|
|
case 'type': await page.type(String(value)); await delay(step.wait ?? settle); break;
|
|
case 'press': await page.press(String(value)); await delay(step.wait ?? settle); break;
|
|
case 'scroll': await page.scroll(Number(value), step.at); await delay(step.wait ?? settle); break;
|
|
case 'labels': await save(file(value || 'labels', 'json'), JSON.stringify(await page.labels(), null, 2)); break;
|
|
case 'film': {
|
|
const name = step.name ?? `film-${describe(parseTarget(value)).replace(/\W+/g, '-').replace(/^-|-$/g, '')}`;
|
|
const frames = await page.film(value, Number(step.ms ?? opts['film-ms']));
|
|
const dir = join(out, name.replace(/[^\w.-]+/g, '_'));
|
|
await mkdir(dir, { recursive: true });
|
|
for (const [i, f] of frames.entries()) {
|
|
await writeFile(join(dir, `f${String(i).padStart(3, '0')}_${f.ms}ms.png`), Buffer.from(f.data, 'base64'));
|
|
}
|
|
log(` ${frames.length} frames in ${dir}`);
|
|
if (frames.length) {
|
|
const picks = pickFrames(frames, Number(step.frames ?? 6)).map((f) => ({ data: f.data, label: `${f.ms} ms` }));
|
|
await save(file(`${name}-sheet`), await contactSheet(browser, picks));
|
|
}
|
|
break;
|
|
}
|
|
default: throw new Error(`unknown step ${verb}\n${USAGE}`);
|
|
}
|
|
}
|
|
} catch (error) {
|
|
exitCode = 1;
|
|
log(`FAILED: ${error.message}`);
|
|
report.failure = error.message;
|
|
if (page) await save(file('FAILED'), await page.shot()).catch(() => {});
|
|
} finally {
|
|
report.errors = page?.errors ?? [];
|
|
if (report.errors.length) log(`page errors:\n ${report.errors.join('\n ')}`);
|
|
await writeFile(join(out, 'report.json'), JSON.stringify(report, null, 2));
|
|
await cleanup();
|
|
}
|
|
process.exit(exitCode);
|