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.
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
# 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.
|