Merge: capture kit and repo memory watchdog

This commit is contained in:
2026-11-01 21:29:47 +00:00
12 changed files with 754 additions and 6 deletions
+2 -1
View File
@@ -18,8 +18,9 @@
- Tests mirror directories under `test/`; tests use local fixtures/fake gateways, never mutate production. Put item evidence in `notes/<item>.md`, not shared queue.
## Tools and verification
Flutter: `/Users/alan/development/flutter/bin/flutter`; Dart beside it. Run pub get per worktree; never upgrade shared SDK. Focused `flutter test test/<area>` while editing, `flutter analyze` and `flutter build web` for integrated acceptance. No Go/legacy client checks needed for app-only changes.
Flutter: `/Users/alan/development/flutter/bin/flutter`; Dart beside it. Run pub get per worktree; never upgrade shared SDK. Run tests only through the memory watchdog, from `app/`: `tool/memwatch/full.sh test` (or a focused `tool/memwatch/full.sh test/<area>` while editing). Never run a bare `flutter test`, because a runaway test has crashed the Mac. `tool/memwatch/install.sh` restores the legacy `/tmp/memwatch` shims. Use `flutter analyze` and `flutter build web` for integrated acceptance. No Go/legacy client checks needed for app-only changes.
Rendered changes require real browser interaction/captures; widget tests alone are not browser evidence. Use isolated loopback servers and OS-assigned ports. Browser automation may use Chrome DevTools, with independent scripts under `app/tool/`; do not modify legacy browser drivers. Never disable authentication on exposed services.
UI capture and review: use `tool/capture/` (see its README). It is one generic Chrome DevTools kit over the full-app fixture `tool/search_selection_probe_entry.dart`. It opens any route at a given size, platform and theme, clicks by semantics label, identifier or point, types text, takes screenshots and films transitions. If a feature's legacy `tool/*_probe.mjs` driver is stale (missing labels, outdated status text), capture with this kit; a stale driver is not a reason to report blocked. Inspect every PNG you cite.
Keep commits referenced; do not discard unrelated work or delete branches. Deploy only when requested by the user; preserve existing public URLs unless a cutover is part of that request. Land candidates per selected pipeline; manager verifies actual ancestry and records source, checks, landing and deployment separately.
## Device testing
+107
View File
@@ -0,0 +1,107 @@
# Capture kit
One generic browser driver for UI review. It works on the whole app, not one
feature, so a renamed label never makes it go stale. Use it instead of writing
new capture code, and instead of a per-feature `tool/*_probe.mjs` driver that
no longer matches the app.
- `capture.mjs`: the CLI. It serves a build on an OS-assigned loopback port
(`--build`) or takes `--url`. It starts private headless Chrome (fresh
profile, debugging port chosen by the OS) or attaches to one with
`--cdp http://127.0.0.1:<port>`. Then it runs the steps and writes
`NN-<name>.png` and `report.json` to `--out`. On exit, Ctrl-C or failure it
removes Chrome, the profile and the server.
- It needs no npm packages: Node 22+ (global `WebSocket` and `fetch`) and
Google Chrome (`CHROME_PATH` overrides the macOS default).
## The fixture app
`tool/search_selection_probe_entry.dart` is the real `PipelinesApp` running on
an in-process fixture channel. It never contacts a server. It has run 7 (three
visits plus the artifact `release-report.txt`), run 6, pipelines 24 and 22, and
search hits for `release`. Build it once per change, from `app/`:
```sh
/Users/alan/development/flutter/bin/flutter build web \
--target tool/search_selection_probe_entry.dart --output build/probe-app
```
URL parameters (the kit sets them from `open=` and the options):
`route=<app route>`, `q=<search>`, `platform=material|cupertino`,
`theme=light|dark`. Without `theme`, the app follows the browser's colour
scheme. `--theme` also sets that colour scheme through Chrome emulation.
## Steps
You can pass steps on the command line as `verb=value`. With `--script`, they
go in a JSON array or in `{ "size", "platform", "theme", "q", "steps": [...] }`.
In JSON, a step can also set `wait` (ms), `timeout`, `name`, `ms` and `frames`.
| step | effect |
| --- | --- |
| `open=/runs/7[@WxH]` | load a route at a size (default `--size`, 880x1000) and turn on Flutter semantics |
| `shot=name` | take a screenshot |
| `click=<target>` | click the centre of the target, then wait `--wait` ms (default 1000) |
| `waitfor=<target>` | wait up to 10 s for the target to appear |
| `type=text` | type into the focused field (or the first visible one) |
| `press=Enter` | press a key: Enter, Escape, Tab, Backspace, ArrowUp or ArrowDown |
| `scroll=600` | scroll with the mouse wheel at the centre (JSON `at` sets a target) |
| `size=WxH` | resize without reloading |
| `labels=name` | write the visible semantics labels, keys and rects to JSON |
| `film=<target>` | screencast a click for `--film-ms` (900) and write the frames plus a contact sheet |
| `wait=ms` | sleep |
Targets:
- A bare `Artifacts` or `label:Artifacts` is a semantics label (`aria-label` or
the node's text). An exact match beats a prefix match, and then the smallest
visible node wins.
- `key:list-detail-body` is a `Semantics(identifier:)`. A Flutter `Key` is not
visible in the DOM.
- `120,340` or `xy:120,340` is a point in CSS pixels.
When a target is missing, the step fails. The kit lists the visible labels,
saves `NN-FAILED.png` and exits with status 1.
## Recipes (run from `app/` after building `build/probe-app`)
Capture a page at phone and fold widths, in Material and in Cupertino. Use 560
for phone: headless Chrome misrenders Flutter below about 500 px.
```sh
for platform in material cupertino; do
for size in 560x1000 880x1000; do
node tool/capture/capture.mjs --build build/probe-app \
--out /tmp/review/runs-$platform-$size --platform $platform --size $size \
open=/runs/7 shot=run7
done
done
```
Add `--theme dark` (or `light`) to pin the theme.
Click through to a state:
```sh
node tool/capture/capture.mjs --build build/probe-app --out /tmp/review/artifact \
open=/runs/7@880x1000 click=Artifacts waitfor=release-report.txt shot=artifacts \
click=release-report.txt shot=artifact-open labels=artifact-open
```
To run the same flow as a script, use `--script tool/capture/examples/run7-artifacts.json`.
Search with `open=/search` then `type=release`, or use `--q release`.
Film a transition. This writes the frames (`fNNN_<ms>ms.png`, relative to the
click) to `<out>/film-label-Pipelines/` and the sheet to
`NN-film-label-Pipelines-sheet.png`:
```sh
node tool/capture/capture.mjs --build build/probe-app --out /tmp/review/film \
--film-ms 900 open=/runs@560x1000 film=Pipelines
```
In a JSON script, `{ "film": "Pipelines", "name": "tab-switch", "ms": 900,
"frames": 6 }` sets the name, the duration and how many frames go on the sheet.
Find targets: run `labels=now` after any step and read `NN-now.json`.
Look at every PNG you cite. A capture that exits 0 is not a review.
+108
View File
@@ -0,0 +1,108 @@
// Headless Chrome over the DevTools protocol: launch a private instance (fresh
// profile, remote debugging on an OS-assigned port) or attach to a running one
// via `--cdp http://127.0.0.1:<port>`. Either way the kit works in its own page
// target, and close() removes everything it created.
import { spawn } from 'node:child_process';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { setTimeout as delay } from 'node:timers/promises';
const CALL_TIMEOUT_MS = 30000;
const DEFAULT_CHROME ='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
async function launch(chromePath) {
const profile = await mkdtemp(join(tmpdir(), 'pipelines-capture-chrome-'));
const chrome = spawn(chromePath, [
'--headless=new', '--no-first-run', '--no-default-browser-check',
'--disable-gpu', '--hide-scrollbars', '--mute-audio',
'--remote-debugging-port=0', `--user-data-dir=${profile}`, 'about:blank',
], { stdio: ['ignore', 'ignore', 'pipe'] });
let stderr = '';
chrome.stderr.on('data', (d) => { stderr += d; });
const exited = new Promise((done) => chrome.once('exit', done));
const cleanup = async () => {
if (chrome.exitCode === null && chrome.signalCode === null) {
chrome.kill('SIGTERM');
const timedOut = await Promise.race([exited.then(() => false), delay(3000, true)]);
if (timedOut) { chrome.kill('SIGKILL'); await exited; }
}
await rm(profile, { recursive: true, force: true }).catch(() => {});
};
for (let i = 0; i < 150; i++) {
const ws = stderr.match(/DevTools listening on (ws:\/\/\S+)/)?.[1];
if (ws) return { ws, cleanup };
if (chrome.exitCode !== null) break;
await delay(100);
}
await cleanup();
throw new Error(`Chrome did not start (${chromePath}): ${stderr.slice(-800)}`);
}
async function attach(cdp) {
const version = await (await fetch(new URL('/json/version', cdp))).json();
return { ws: version.webSocketDebuggerUrl, cleanup: async () => {} };
}
/**
* Opens a page target. Returns `{ send, on, close }`: `send(method, params)`
* talks to the page session; `on(method, fn)` subscribes to its events and
* returns the unsubscribe function; `newPage()` opens a scratch page.
*/
export async function openBrowser({ cdp, chromePath = process.env.CHROME_PATH ?? DEFAULT_CHROME } = {}) {
const { ws: endpoint, cleanup } = cdp ? await attach(cdp) : await launch(chromePath);
const ws = new WebSocket(endpoint);
try {
await new Promise((ok, fail) => { ws.onopen = ok; ws.onerror = () => fail(new Error(`Cannot open ${endpoint}`)); });
} catch (error) { await cleanup(); throw error; }
let nextId = 0;
const pending = new Map();
const listeners = new Map();
let sessionId;
ws.onmessage = (event) => {
const m = JSON.parse(event.data);
if (m.id && pending.has(m.id)) {
const { ok, fail, method } = pending.get(m.id);
pending.delete(m.id);
return m.error ? fail(new Error(`${method}: ${m.error.message}`)) : ok(m.result ?? {});
}
if (m.method && m.sessionId === sessionId) for (const fn of listeners.get(m.method) ?? []) fn(m.params);
};
// Every call is bounded: an unresponsive page (for example a navigation to a
// server that never answers) fails the step instead of hanging the kit.
const raw = (method, params = {}, session) => new Promise((ok, fail) => {
const id = ++nextId;
const timer = setTimeout(() => {
pending.delete(id);
fail(new Error(`${method}: no reply within ${CALL_TIMEOUT_MS} ms`));
}, CALL_TIMEOUT_MS);
const settle = (fn) => (value) => { clearTimeout(timer); fn(value); };
pending.set(id, { ok: settle(ok), fail: settle(fail), method });
ws.send(JSON.stringify({ id, method, params, ...(session ? { sessionId: session } : {}) }));
});
let targetId;
try {
({ targetId } = await raw('Target.createTarget', { url: 'about:blank' }));
({ sessionId } = await raw('Target.attachToTarget', { targetId, flatten: true }));
} catch (error) { ws.close(); await cleanup(); throw error; }
return {
send: (method, params) => raw(method, params, sessionId),
on: (method, fn) => {
listeners.set(method, [...(listeners.get(method) ?? []), fn]);
return () => listeners.set(method, listeners.get(method).filter((f) => f !== fn));
},
newPage: async () => {
const page = await raw('Target.createTarget', { url: 'about:blank' });
const { sessionId: sid } = await raw('Target.attachToTarget', { targetId: page.targetId, flatten: true });
return {
send: (method, params) => raw(method, params, sid),
close: () => raw('Target.closeTarget', { targetId: page.targetId }).catch(() => {}),
};
},
close: async () => {
await raw('Target.closeTarget', { targetId }).catch(() => {});
ws.close();
await cleanup();
},
};
}
+142
View File
@@ -0,0 +1,142 @@
#!/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);
@@ -0,0 +1,16 @@
{
"size": "880x1000",
"steps": [
{ "open": "/runs/7" },
{ "shot": "summary" },
{ "click": "Artifacts" },
{ "waitfor": "release-report.txt" },
{ "shot": "artifacts" },
{ "click": "release-report.txt", "wait": 1500 },
{ "shot": "artifact-open" },
{ "labels": "artifact-open" },
{ "press": "Escape" },
{ "film": "Pipelines", "name": "tab-switch", "ms": 900 },
{ "shot": "pipelines" }
]
}
+157
View File
@@ -0,0 +1,157 @@
// Flutter-web page actions over one DevTools page session: open at a size,
// enable semantics, find targets by semantics label / identifier / point,
// click, type, screenshot and film.
import { setTimeout as delay } from 'node:timers/promises';
/** Parses `label:Text`, `key:id`, `xy:10,20`, `10,20` or bare `Text` (a label). */
export function parseTarget(target) {
if (typeof target === 'object') return target;
const s = String(target);
if (/^\d+(\.\d+)?,\d+(\.\d+)?$/.test(s)) return { xy: s.split(',').map(Number) };
const m = s.match(/^(label|key|xy):(.*)$/s);
if (!m) return { label: s };
return m[1] === 'xy' ? { xy: m[2].split(',').map(Number) } : { [m[1]]: m[2] };
}
export const describe = (t) => t.key ? `key ${t.key}` : t.xy ? `point ${t.xy}` : `label ${JSON.stringify(t.label)}`;
// In-page lookup. Labels: aria-label or a node's own text; an exact match beats
// a prefix match, then the smallest visible node wins (the most specific one).
const FIND = `(t) => {
const vis = (el) => { const r = el.getBoundingClientRect();
return r.width > 0 && r.height > 0 && r.bottom > 0 && r.right > 0
&& r.top < innerHeight && r.left < innerWidth ? r : null; };
const textOf = (el) => (el.getAttribute('aria-label') || el.innerText || el.value || '').trim();
let nodes = [];
if (t.key) nodes = [...document.querySelectorAll('[flt-semantics-identifier="' + CSS.escape(t.key) + '"], #' + CSS.escape(t.key))];
else {
const all = [...document.querySelectorAll('flt-semantics, [aria-label], input, textarea')];
nodes = all.filter((el) => textOf(el) === t.label);
if (!nodes.length) nodes = all.filter((el) => textOf(el).startsWith(t.label));
}
const hits = nodes.map((el) => ({ el, r: vis(el) })).filter((h) => h.r)
.sort((a, b) => a.r.width * a.r.height - b.r.width * b.r.height);
if (!hits.length) return null;
const r = hits[0].r;
return { x: r.left + r.width / 2, y: r.top + r.height / 2, text: textOf(hits[0].el).slice(0, 80) };
}`;
const LABELS = `(() => [...document.querySelectorAll('flt-semantics, [aria-label], input, textarea')]
.map((el) => { const r = el.getBoundingClientRect();
return { label: (el.getAttribute('aria-label') || (el.children.length ? '' : el.innerText) || '').trim(),
key: el.getAttribute('flt-semantics-identifier') || undefined,
role: el.getAttribute('role') || el.tagName.toLowerCase(),
rect: [r.left, r.top, r.width, r.height].map(Math.round) }; })
.filter((n) => (n.label || n.key) && n.rect[2] > 0 && n.rect[3] > 0))()`;
export function flutterPage(browser, log) {
const { send } = browser;
let viewport = { width: 880, height: 1000 };
const errors = [];
browser.on('Runtime.exceptionThrown', (p) => errors.push(p.exceptionDetails?.exception?.description ?? p.exceptionDetails?.text));
browser.on('Runtime.consoleAPICalled', (p) => {
if (p.type === 'error') errors.push(p.args.map((a) => a.value ?? a.description).join(' '));
});
const evaluate = async (expression) => {
const r = await send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true });
if (r.exceptionDetails) throw new Error(`page: ${r.exceptionDetails.exception?.description ?? r.exceptionDetails.text}`);
return r.result.value;
};
const until = async (fn, what, timeout) => {
const end = Date.now() + timeout;
for (;;) {
const v = await fn();
if (v) return v;
if (Date.now() > end) throw new Error(`Timed out after ${timeout} ms waiting for ${what}`);
await delay(100);
}
};
const resize = async (width, height) => {
viewport = { width, height };
if (width < 500) log(`warning: headless Chrome misrenders Flutter below ~500 px (asked ${width}); use 560 for phone`);
await send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false });
};
const locate = async (target, timeout = 5000) => {
const t = parseTarget(target);
if (t.xy) return { x: t.xy[0], y: t.xy[1], text: '' };
try {
return await until(() => evaluate(`(${FIND})(${JSON.stringify(t)})`), describe(t), timeout);
} catch (error) {
const known = (await evaluate(LABELS)).map((n) => n.key ? `${n.label} [key ${n.key}]` : n.label);
throw new Error(`${error.message}. Visible labels: ${JSON.stringify(known)}`);
}
};
const tap = async ({ x, y }) => {
for (const type of ['mouseMoved', 'mousePressed', 'mouseReleased']) {
await send('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 });
}
};
const png = async () => Buffer.from((await send('Page.captureScreenshot', { format: 'png' })).data, 'base64');
return {
errors,
resize,
labels: () => evaluate(LABELS),
shot: png,
async open(url, { width, height, theme }) {
await send('Page.enable');
await send('Runtime.enable');
await send('Page.bringToFront');
await resize(width, height);
await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: theme ?? '' }] });
await send('Page.navigate', { url });
await until(() => evaluate("Boolean(document.querySelector('flt-semantics-placeholder'))"), 'Flutter to start', 30000);
await evaluate("document.querySelector('flt-semantics-placeholder')?.click()");
await until(() => evaluate("document.querySelectorAll('flt-semantics').length > 0"), 'the semantics tree', 15000);
await delay(800);
},
async click(target, timeout) {
const point = await locate(target, timeout);
await tap(point);
return point;
},
waitFor: (target, timeout) => locate(target, timeout),
async type(text) {
const focused = await evaluate(`(() => {
const a = document.activeElement;
if (a && (a.tagName === 'INPUT' || a.tagName === 'TEXTAREA')) return true;
const el = [...document.querySelectorAll('input, textarea')].find((e) => e.checkVisibility?.() ?? true);
if (!el) return false; el.focus(); return true; })()`);
if (!focused) throw new Error('No text field to type into; click the field first');
await send('Input.insertText', { text });
},
async press(key) {
const codes = { Enter: 13, Escape: 27, Tab: 9, Backspace: 8, ArrowDown: 40, ArrowUp: 38 };
const base = { key, code: key, windowsVirtualKeyCode: codes[key] ?? 0, text: key === 'Enter' ? '\r' : undefined };
await send('Input.dispatchKeyEvent', { type: 'keyDown', ...base });
await send('Input.dispatchKeyEvent', { type: 'keyUp', ...base, text: undefined });
},
async scroll(dy, target) {
const at = target ? await locate(target) : { x: viewport.width / 2, y: viewport.height / 2 };
await send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: at.x, y: at.y, deltaX: 0, deltaY: dy });
},
/** Screencasts [ms] after clicking [target]; frames are `{ data, ms }` relative to the click. */
async film(target, ms) {
const point = await locate(target);
const frames = [];
const ack = (p) => {
frames.push({ data: p.data, t: p.metadata.timestamp });
send('Page.screencastFrameAck', { sessionId: p.sessionId }).catch(() => {});
};
const off = browser.on('Page.screencastFrame', ack);
await send('Page.startScreencast', { format: 'png', everyNthFrame: 1, maxWidth: viewport.width, maxHeight: viewport.height });
await delay(300);
const clickAt = Date.now() / 1000;
await tap(point);
await delay(ms);
await send('Page.stopScreencast');
await delay(100);
off();
const kept = frames.filter((f) => f.t >= clickAt - 0.05);
// A still page sends no frames; the last pre-click frame is the start state.
const before = frames.filter((f) => f.t < clickAt - 0.05).at(-1);
return [...(before ? [before] : []), ...kept].map((f) => ({ data: f.data, ms: Math.round((f.t - clickAt) * 1000) }));
},
};
}
+58
View File
@@ -0,0 +1,58 @@
// Static loopback server for a Flutter web build, on an OS-assigned port.
// Extension-less paths (`/runs/7`) fall back to index.html, as the Pipelines
// proxy serves the single page.
import { createServer } from 'node:http';
import { readFile, stat } from 'node:fs/promises';
import { once } from 'node:events';
import { extname, join, resolve, sep } from 'node:path';
const MIME = {
'.html': 'text/html; charset=utf-8',
'.js': 'text/javascript; charset=utf-8',
'.mjs': 'text/javascript; charset=utf-8',
'.json': 'application/json; charset=utf-8',
'.wasm': 'application/wasm',
'.png': 'image/png',
'.svg': 'image/svg+xml',
'.ico': 'image/x-icon',
'.ttf': 'font/ttf',
'.otf': 'font/otf',
'.woff': 'font/woff',
'.woff2': 'font/woff2',
};
/** Serves [dir]; resolves to `{ origin, close() }`. */
export async function serveBuild(dir) {
const root = resolve(dir);
if (!(await stat(join(root, 'index.html')).catch(() => null))) {
throw new Error(`No index.html in ${root}; build the probe first (see README).`);
}
const server = createServer(async (req, res) => {
try {
const pathname = decodeURIComponent(new URL(req.url, 'http://x').pathname);
let file = resolve(root, '.' + pathname);
if (file !== root && !file.startsWith(root + sep)) return res.writeHead(403).end();
try {
if ((await stat(file)).isDirectory()) file = join(file, 'index.html');
} catch {
if (!extname(pathname)) file = join(root, 'index.html');
}
const body = await readFile(file);
res.writeHead(200, {
'content-type': MIME[extname(file)] ?? 'application/octet-stream',
'cache-control': 'no-store',
}).end(body);
} catch {
res.writeHead(404).end('not found');
}
});
server.listen(0, '127.0.0.1');
await once(server, 'listening');
return {
origin: `http://127.0.0.1:${server.address().port}`,
close: () => new Promise((done) => {
server.closeAllConnections?.();
server.close(() => done());
}),
};
}
+47
View File
@@ -0,0 +1,47 @@
// Contact sheet of filmed frames, drawn on a canvas in a scratch page of the
// same Chrome (no image library needed).
/** Picks up to [count] frames evenly, always keeping the first and the last. */
export function pickFrames(frames, count) {
if (frames.length <= count) return frames;
return Array.from({ length: count }, (_, i) =>
frames[Math.round((i * (frames.length - 1)) / (count - 1))]);
}
/**
* Renders `[{ data: <base64 png>, label }]` at half size in a [columns]-wide
* grid with each label in the corner; resolves to a PNG Buffer.
*/
export async function contactSheet(browser, frames, { columns = 3, scale = 0.5 } = {}) {
const page = await browser.newPage();
try {
const expression = `(async () => {
const frames = ${JSON.stringify(frames)};
const images = await Promise.all(frames.map((f) => new Promise((ok, fail) => {
const im = new Image(); im.onload = () => ok(im); im.onerror = fail;
im.src = 'data:image/png;base64,' + f.data;
})));
const w = Math.round(images[0].width * ${scale}), h = Math.round(images[0].height * ${scale});
const cols = Math.min(${columns}, images.length), rows = Math.ceil(images.length / cols);
const canvas = document.createElement('canvas');
canvas.width = w * cols; canvas.height = h * rows;
const g = canvas.getContext('2d');
g.fillStyle = '#000'; g.fillRect(0, 0, canvas.width, canvas.height);
images.forEach((im, i) => {
const x = (i % cols) * w, y = Math.floor(i / cols) * h;
g.drawImage(im, x, y, w, h);
g.strokeStyle = '#888'; g.strokeRect(x + 0.5, y + 0.5, w - 1, h - 1);
g.font = 'bold 14px sans-serif';
const label = frames[i].label, tw = g.measureText(label).width;
g.fillStyle = 'rgba(0,0,0,0.7)'; g.fillRect(x + 4, y + 4, tw + 10, 20);
g.fillStyle = '#ff0'; g.fillText(label, x + 9, y + 19);
});
return canvas.toDataURL('image/png').split(',')[1];
})()`;
const r = await page.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true });
if (r.exceptionDetails) throw new Error(`contact sheet: ${r.exceptionDetails.text}`);
return Buffer.from(r.result.value, 'base64');
} finally {
await page.close();
}
}
+5
View File
@@ -0,0 +1,5 @@
#!/bin/bash
# THE way to run app tests (from app/): tool/memwatch/full.sh test
# Also for focused runs: tool/memwatch/full.sh test/features/runs
# Concurrency 4, 12 GB cap for this run only (see run.sh beside this file).
CONC=4 CAP_KB=12000000 exec "$(dirname "$0")/run.sh" "$@"
+28
View File
@@ -0,0 +1,28 @@
#!/bin/bash
# Points the legacy /tmp/memwatch/{run,full}.sh at the repo scripts, so older
# instructions keep working after /tmp is cleared (reboot). Each shim prefers
# the main clone's copy and falls back to the copy this was installed from (a
# worktree may be removed later). Shims are replaced atomically, so a run that
# is already executing the old file is unaffected.
#
# Usage: app/tool/memwatch/install.sh
set -eu
here=$(cd "$(dirname "$0")" && pwd)
common=$(git -C "$here" rev-parse --path-format=absolute --git-common-dir)
main="$(dirname "$common")/app/tool/memwatch"
dir=${MEMWATCH_DIR:-/tmp/memwatch}
mkdir -p "$dir"
for name in run full; do
tmp=$(mktemp "$dir/.$name.XXXXXX")
cat > "$tmp" <<EOF
#!/bin/bash
# Shim installed by app/tool/memwatch/install.sh; the repo script is the source.
for d in "$main" "$here"; do
[ -x "\$d/$name.sh" ] && exec "\$d/$name.sh" "\$@"
done
echo "memwatch: $name.sh not found in $main or $here" >&2; exit 127
EOF
chmod +x "$tmp"
mv -f "$tmp" "$dir/$name.sh"
done
echo "$dir/{run,full}.sh -> $main (fallback $here)"
+43
View File
@@ -0,0 +1,43 @@
#!/bin/bash
# Memory watchdog for Flutter tests. THE way to run app tests is full.sh (beside
# this file); use run.sh directly for a single file at the default 3 GB cap.
#
# Usage (from app/): tool/memwatch/run.sh "<test path> [args]"
# CONC flutter test --concurrency (default 1)
# CAP_KB total RSS cap for this run's own test processes (default 3 GB)
# MEMWATCH_DIR per-invocation output directory (default /tmp/memwatch)
# FLUTTER flutter executable
#
# Runs flutter test in the background and polls the RSS of ITS OWN descendant
# processes only; above CAP_KB it kills them (never another run's flutter_tester).
# Prints the peak and the suite's last line, and exits with flutter's status
# (137 when killed). A runaway test once grew to ~30 GB per process and crashed
# the Mac twice, so never run `flutter test` outside this watchdog.
CONC=${CONC:-1}; CAP_KB=${CAP_KB:-3000000}
MEMWATCH_DIR=${MEMWATCH_DIR:-/tmp/memwatch}
FLUTTER=${FLUTTER:-/Users/alan/development/flutter/bin/flutter}
# Called from elsewhere (for example the repo root): run in this script's app/.
[ -f pubspec.yaml ] || cd "$(dirname "$0")/../.." || exit 1
mkdir -p "$MEMWATCH_DIR" || exit 1
out=$(mktemp "$MEMWATCH_DIR/out.XXXXXX")
# $1 is deliberately unquoted: it carries the test path plus extra arguments.
"$FLUTTER" test --concurrency="$CONC" $1 > "$out" 2>&1 &
pid=$!
descendants() { local p; for p in $(pgrep -P "$1"); do echo "$p"; descendants "$p"; done; }
peak=0; killed=0
while kill -0 $pid 2>/dev/null; do
pids=$(descendants $pid | tr '\n' ',' | sed 's/,$//')
rss=0; [ -n "$pids" ] && rss=$(ps -o rss= -p "$pids" 2>/dev/null | awk '{s+=$1} END {print s+0}')
[ "$rss" -gt "$peak" ] && peak=$rss
if [ "$rss" -gt "$CAP_KB" ]; then
echo "KILLED at $((rss/1024)) MB: $1"
for p in $(descendants $pid); do kill -9 $p 2>/dev/null; done; kill -9 $pid 2>/dev/null
killed=1; break
fi
sleep 0.5
done
wait $pid 2>/dev/null; status=$?
[ $killed = 1 ] && status=137
echo "peak $((peak/1024)) MB: $1 :: $(tail -1 "$out")"
echo "full output: $out"
exit $status
+41 -5
View File
@@ -477,7 +477,13 @@ class _FixtureSink implements WebSocketSink {
/// fallback for `/runs/7`) can still open a deep location:
///
/// `?route=/runs/7/stage/build%3Fvisit%3D1` opens that app location;
/// `?q=release` types that query into Search once its field is shown.
/// `?q=release` types that query into Search once its field is shown;
/// `?platform=cupertino` renders the Cupertino host (`material`, the
/// default, renders Material as browsers do);
/// `?theme=dark` / `?theme=light` pins the platform brightness the app's
/// `ThemeMode.system` follows (omitted: the browser's color scheme).
///
/// app/tool/capture/ drives this entry generically; see its README.
void main() {
final params = Uri.base.queryParameters;
final cupertino = params['platform'] == 'cupertino';
@@ -494,11 +500,41 @@ void main() {
final query = params['q'];
if (query != null && query.isNotEmpty) _typeSearchWhenShown(query);
useAppUrlStrategy();
final app = PipelinesApp(
server: ServerEndpoint.resolve(base: Uri.base, web: true),
client: PipelinesClient(channelFactory: (_) => _FixtureChannel()),
cupertino: cupertino,
);
final brightness = switch (params['theme']) {
'dark' => Brightness.dark,
'light' => Brightness.light,
_ => null,
};
runApp(
PipelinesApp(
server: ServerEndpoint.resolve(base: Uri.base, web: true),
client: PipelinesClient(channelFactory: (_) => _FixtureChannel()),
cupertino: cupertino,
brightness == null
? app
: _PinnedBrightness(brightness: brightness, child: app),
);
}
/// Pins the platform brightness below it. The app's own `MediaQuery.fromView`
/// takes platform fields from this ambient query, so `ThemeMode.system` (and
/// the Cupertino theme's null brightness) resolve to [brightness] while size,
/// padding and text scale still follow the real view.
class _PinnedBrightness extends StatelessWidget {
const _PinnedBrightness({required this.brightness, required this.child});
final Brightness brightness;
final Widget child;
@override
Widget build(BuildContext context) => MediaQuery.fromView(
view: View.of(context),
child: Builder(
builder: (context) => MediaQuery(
data: MediaQuery.of(context).copyWith(platformBrightness: brightness),
child: child,
),
),
);
}