From ea428d3c9899ed3de3423c307475fd80ee410dc5 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 1 Nov 2026 21:22:08 +0000 Subject: [PATCH] Add generic capture kit and repo-owned test memory watchdog 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. --- app/AGENTS.md | 3 +- app/tool/capture/README.md | 107 ++++++++++++ app/tool/capture/browser.mjs | 108 ++++++++++++ app/tool/capture/capture.mjs | 142 ++++++++++++++++ app/tool/capture/examples/run7-artifacts.json | 16 ++ app/tool/capture/page.mjs | 157 ++++++++++++++++++ app/tool/capture/serve.mjs | 58 +++++++ app/tool/capture/sheet.mjs | 47 ++++++ app/tool/memwatch/full.sh | 5 + app/tool/memwatch/install.sh | 28 ++++ app/tool/memwatch/run.sh | 43 +++++ app/tool/search_selection_probe_entry.dart | 46 ++++- 12 files changed, 754 insertions(+), 6 deletions(-) create mode 100644 app/tool/capture/README.md create mode 100644 app/tool/capture/browser.mjs create mode 100644 app/tool/capture/capture.mjs create mode 100644 app/tool/capture/examples/run7-artifacts.json create mode 100644 app/tool/capture/page.mjs create mode 100644 app/tool/capture/serve.mjs create mode 100644 app/tool/capture/sheet.mjs create mode 100755 app/tool/memwatch/full.sh create mode 100755 app/tool/memwatch/install.sh create mode 100755 app/tool/memwatch/run.sh diff --git a/app/AGENTS.md b/app/AGENTS.md index 7193a754..49c0db1a 100644 --- a/app/AGENTS.md +++ b/app/AGENTS.md @@ -18,8 +18,9 @@ - Tests mirror directories under `test/`; tests use local fixtures/fake gateways, never mutate production. Put item evidence in `notes/.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/` 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/` 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 diff --git a/app/tool/capture/README.md b/app/tool/capture/README.md new file mode 100644 index 00000000..41e025c8 --- /dev/null +++ b/app/tool/capture/README.md @@ -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:`. Then it runs the steps and writes + `NN-.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=`, `q=`, `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=` | click the centre of the target, then wait `--wait` ms (default 1000) | +| `waitfor=` | 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=` | 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.png`, relative to the +click) to `/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. diff --git a/app/tool/capture/browser.mjs b/app/tool/capture/browser.mjs new file mode 100644 index 00000000..fdfd6ea3 --- /dev/null +++ b/app/tool/capture/browser.mjs @@ -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:`. 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(); + }, + }; +} diff --git a/app/tool/capture/capture.mjs b/app/tool/capture/capture.mjs new file mode 100644 index 00000000..0431c07f --- /dev/null +++ b/app/tool/capture/capture.mjs @@ -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-.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 | --url ) --out [options] [steps...] +options: --script --size WxH (880x1000) --platform material|cupertino + --theme light|dark --q --wait + --film-ms --cdp http://127.0.0.1: --probe true|false +steps: open=[@WxH] wait= shot= click= waitfor= + type= press= scroll= size=WxH + film= labels= +target: