webview-preview 1.0.0 → 1.1.0

package/AGENTS.md

@@ -16,6 +16,9 @@ Read the [README](./README.md) for install and options. Everything here assumes
 4. Open the PNG only after the numbers make sense. Crop it to the area you care about before looking.
 5. Change, run again, compare the same numbers.
 
+Do not use `--watch`: it never exits. It is for a person keeping a snapshot open while editing; you run the command
+again after each change.
+
 When you report back, say which engine you checked and what you could **not** check (see the limits below).
 
 ## Writing steps
@@ -63,6 +66,13 @@ element.getClientRects().length > 0
 If the project's config has macros (`macros` in `webview-preview.config.mjs` — signing in, opening a dialog), use them
 (`macro:signIn`): they are already correct. A flow you repeat more than twice belongs there too.
 
+## Errors in the page
+
+After the steps the tool prints the page's `console.error` calls, uncaught exceptions and unhandled rejections
+(`console.error: …`, `uncaught: …`, `unhandled rejection: …`). Read them before you look at a snapshot: a blank or
+half-rendered picture almost always has its cause there. Mention any you did not cause — they may be bugs the user
+should know about. Add `--fail-on-error` when the run must fail on them.
+
 ## Measuring
 
 Start with `measure:<selector>` — one line with position, size, box, visibility, font, colours and text:
@@ -83,7 +93,9 @@ screenshot scale.
 "print:document.querySelector('form').getBoundingClientRect().width"
 ```
 
-**Frame by frame.** To see whether something animates smoothly, jumps, or flickers, record every animation frame into
+**Frame by frame.** To *see* an animation, use `film:` right after the step that starts it —
+`"click:text=New project" "film:open:500@[role=dialog]"` gives one PNG with 10 frames over 500 ms, cropped to the
+dialog. To *measure* whether something animates smoothly, jumps, or flickers, record every animation frame into
 `window` and print the log afterwards. Keep only the frames where the value changed:
 
 ```
@@ -145,6 +157,10 @@ Put the result in the project's `webview-preview.config.mjs` (or `preview/mocks.
 person's — gets there in one command. Mention in your report which requests you mocked and with what data; mocked
 data can hide a real bug in how the app handles the real server.
 
+Loading and offline states are reachable too: `--latency 2000` (or the step `latency:2000`) keeps every request
+waiting, so you can snap the spinner or skeleton; `offline` / `online` steps drop the connection for `fetch` / XHR,
+switch `navigator.onLine` and fire the events, so an app's offline banner or retry logic shows up for real.
+
 ## Keyboard, mouse and focus
 
 Use the real input steps, not `js:` clicks, whenever the question is about what a person experiences:
@@ -152,6 +168,7 @@ Use the real input steps, not `js:` clicks, whenever the question is about what
 | Question | Steps |
 |---|---|
 | Does Tab go in the right order, does a focus trap hold? | `click:` the first field, then `key:Tab` / `key:Shift+Tab`, `print:document.activeElement…` after each |
+| Does Tab go through the right elements, in order, and stay inside a dialog? | `focusorder` (after opening the dialog); every stop should say `in dialog`, and it should loop back |
 | Is the focus ring visible and not clipped? | `key:Tab` until the element is focused, then `snap:ring@<selector>` (8 px margin included) |
 | Does the hover state look right? | `hover:<selector>`, `wait:300` for the transition, `snap:x@<selector>` |
 | Does typing work (validation, masks, Cyrillic…)? | `click:<input>`, `type:<text>`, `print:` the value / error text |
@@ -178,6 +195,22 @@ npx webview-preview /screen <steps> snap:screen "snap:panel@[data-test=panel]" -
 change is a regression to explain. Use a separate `--baseline` folder for such throw-away checks so you do not
 overwrite the project's committed baselines. Run `webview-preview clean` when you are done with the snapshots.
 
+When the user should see the result too, add `--report` and give them the path to `report.html`: baseline, this run
+and the difference side by side, with the run's output on top.
+
+## Sizes, theme and motion
+
+A layout change can break only the narrow window or only the dark theme. Check them in the same run instead of
+asking the user:
+
+```
+npx webview-preview /screen <steps> snap:screen --size 1200x650,800x600
+npx webview-preview /screen <steps> snap:screen --color-scheme dark
+```
+
+Each size runs the steps from the start and names the snapshots `<prefix><WxH>-<name>.png`. `--reduced-motion`
+makes a page that respects it skip its transitions, so a snapshot right after a click shows the final state.
+
 ## Still out of reach — and a few traps
 
 **Fractional scroll.** `scrollTop = 55.5` is rounded; real wheel and touchpad scrolling can stop between pixels. A
@@ -187,6 +220,9 @@ overwrite the project's committed baselines. Run `webview-preview clean` when yo
 WebKitGTK). The app opens in its default state — the default tab, no saved session — so reach the state you need with
 steps or `init`; do not rely on what an earlier run clicked.
 
+**Tab on macOS.** WebKit on a Mac tabs to text fields only unless Full Keyboard Access is on; buttons and links are
+skipped. That is what users of the app on a Mac get too — use `key:Alt+Tab` there to walk every element.
+
 **Windows' WebView2 itself.** `msedge` is the same engine, not the same embedding; window chrome, scrollbars of the
 host and DPI handling of a native window can differ.
 
@@ -203,6 +239,9 @@ host and DPI handling of a native window can differ.
 - The numbers you defined in step 1 match, in the engine the user runs (`webkitgtk` for Tauri on Linux, `msedge` for
   Windows).
 - No `js failed` / `print failed` / selector errors you did not expect; exit code 0.
+- What you measured by eye is pinned with `assert:` — `assert:document.activeElement.matches('[role=dialog] button')`,
+  `assert:getComputedStyle(document.querySelector('.card')).borderRadius === '12px'` — so a later run proves it in one
+  line. `assert:` shows only the final value; for `a === b` print `a` first if it fails.
 - Keyboard and hover behaviour checked with `key:` / `hover:` where the change touches them.
 - You looked at one snapshot of the final state.
 - You listed what could not be checked: fractional scroll, the other platform's engine, real backend data.

package/README.md

@@ -1,5 +1,7 @@
 # webview-preview
 
+[![test](https://github.com/n0t4u404/webview-preview/actions/workflows/test.yml/badge.svg)](https://github.com/n0t4u404/webview-preview/actions/workflows/test.yml)
+
 See your UI the way your desktop app really renders it. `webview-preview` opens a page in the **same engine your app
 runs on** — WebKitGTK on Linux, Edge (the WebView2 engine) on Windows, WebKit on macOS — runs a list of steps
 (click, type, wait, measure) and saves PNG snapshots.
@@ -27,6 +29,7 @@ plain init scripts and fit there too.
 - [Config file](#config-file)
 - [Steps](#steps)
 - [Macros](#macros)
+- [Errors in the page](#errors-in-the-page)
 - [Command line](#command-line)
 - [JavaScript API](#javascript-api)
 - [Login, backend and other things outside the page](#login-backend-and-other-things-outside-the-page)
@@ -155,7 +158,12 @@ npx webview-preview /settings snap:settings
 | `server.cwd` | Folder for `server.command`. | the config's folder |
 | `server.readyTimeoutMs` | How long to wait for the port. | `30000` |
 | `engine` | See [engines](#which-engine-matches-my-app). | `auto` |
-| `size` | Window size in CSS pixels, `WxH`. | `1200x650` |
+| `size` | Window size in CSS pixels, `WxH`. Several sizes — `"1200x650,800x600"` or a list — run the steps once per size; snapshots get the size in the name: `webkitgtk-800x600-page.png`. | `1200x650` |
+| `colorScheme` | `prefers-color-scheme` for the page: `light` or `dark`. | system |
+| `reducedMotion` | `prefers-reduced-motion: reduce` for the page. | `false` |
+| `report` | Write `<out>/report.html` after every run. See [Comparing with a baseline](#comparing-with-a-baseline). | `false` |
+| `watch` | What `--watch` follows: a folder, a file or a list, relative to the config's folder. The config file itself is always followed. | `src` if it exists, else the config's folder |
+| `offline` / `latency` | Start offline / delay every `fetch` / XHR request by ms. See [Slow network and offline](#4-slow-network-and-offline). | `false` / `0` |
 | `out` | Snapshot folder, relative to the config's folder. | `.webview-preview` |
 | `prefix` | File name prefix. | `<engine>-` |
 | `scale` | Device pixel ratio for Playwright engines (`2` = HiDPI). WebKitGTK: off-screen snapshots are 1×, `--headed` ones follow your screen. | `1` |
@@ -171,6 +179,7 @@ npx webview-preview /settings snap:settings
 | `globals` | Objects to put on `window` before the page starts, by path: `{ "window.api": anyApi({ … }) }`. See [Desktop bridges](#desktop-bridges-tauri-electron-wails). | — |
 | `locale` | `navigator.language` for the page, `en-US`, `ru-RU` … Playwright engines also switch `Intl` and `Accept-Language`; WebKitGTK only `navigator.language`. | system |
 | `macros` | Named lists of steps, run with `macro:<name>`. See [Macros](#macros). | — |
+| `failOnError` | Exit with 1 when the page logged `console.error` or threw. See [Errors in the page](#errors-in-the-page). | `false` |
 
 Command-line options win over the config file.
 
@@ -222,6 +231,11 @@ Steps run one after another, after the page has loaded and settled for 1.5 s.
 | `click:<selector>` | Clicks the middle of the element with the real mouse — focus moves, `:active` and `:focus` apply like for a person. |
 | `print:<expression>` | Prints the value: strings as they are, DOM elements as their HTML (first 200 characters), everything else as JSON. Promises are not awaited. |
 | `measure:<selector>` | Prints one line about the element: how many match, position and size, margin / padding / border, visible or hidden, display, opacity, font, colours and text. |
+| `offline` / `online` | Drops the connection for `fetch` / XHR and brings it back, with `navigator.onLine` and the events, then waits 700 ms like `js:`. See [Slow network and offline](#4-slow-network-and-offline). |
+| `latency:<ms>` | Delays every `fetch` / XHR request from now on; `latency:0` turns it off. |
+| `focusorder` / `focusorder:<n>` | Presses `Tab` with the real keyboard n times (20 by default) and prints where focus went, one line per stop — tag, role, name, label, "in dialog" — and `→ back to 1 after N stops` when it loops. Shows a focus trap, a skipped field or focus escaping a dialog at a glance. Starts from the current focus. |
+| `assert:<expression>` | Checks that the expression is truthy: prints `assert ok: …`, or `assert failed: … — got <value>` / `— threw <message>` and makes the run exit with 1. The other steps still run. |
+| `film:<name>:<ms>[/<n>][@<selector>]` | Takes n frames (10 by default, up to 60) evenly over ms, starting now, and puts them into one `<prefix><name>.png`, 5 per row, left to right. With a selector every frame is cropped to the area the element covered during the whole film (plus `--snap-margin`). Prints the real time of every frame: `film open: 10 frames at 0 55 111 … 500 ms`. Put it right after the step that starts the animation. |
 | `resize:<W>x<H>` | Resizes the window. |
 | `macro:<name>` | Runs the steps of a macro from the config. See [Macros](#macros). |
 
@@ -288,6 +302,21 @@ npx webview-preview / macro:openSettings snap:settings
 A macro may run other macros; one that runs itself stops with an error. Prefer real clicks and typing over setting
 values from code: the run then goes through the same handlers, focus and validation as for a person.
 
+## Errors in the page
+
+Every run collects what went wrong inside the page — `console.error` calls, uncaught exceptions and unhandled promise
+rejections — and prints them after the steps, the same message once with a count:
+
+```
+console.error: Failed to load {"code":500} (×2)
+unhandled rejection: Error: no session — global code@http://localhost:5173/src/app.tsx:4:25
+uncaught: TypeError: null is not an object (evaluating 'user.name') — onclick@http://localhost:5173/src/app.tsx:12:5
+```
+
+A blank snapshot usually has its reason here. With `--fail-on-error` (`failOnError: true`) the run exits with 1 when
+there is anything to print — useful in CI. Pages opened from `file://` report uncaught errors only as
+"Script error." in WebKit; serve the page over `http://` to see them.
+
 ## Command line
 
 ```
@@ -297,7 +326,11 @@ webview-preview [route-or-url] [steps...] [options]
 | Option | |
 |---|---|
 | `--engine <name>` | `auto`, `webkitgtk`, `msedge`, `chrome`, `chromium`, `webkit` |
-| `--size <WxH>` | Window size |
+| `--size <WxH>` | Window size; several, comma-separated: `1200x650,800x600` |
+| `--color-scheme <light\|dark>` | `prefers-color-scheme` for the page |
+| `--reduced-motion` | `prefers-reduced-motion: reduce` for the page |
+| `--watch` | Run again whenever a file changes; the server stays up between runs. Ctrl+C to stop |
+| `--offline` / `--latency <ms>` | Start offline / delay every `fetch` / XHR request |
 | `--out <dir>` | Snapshot folder |
 | `--prefix <text>` | File name prefix |
 | `--scale <n>` | Device pixel ratio (Playwright engines) |
@@ -305,6 +338,7 @@ webview-preview [route-or-url] [steps...] [options]
 | `--snap-margin <px>` | Room around `snap:name@selector` |
 | `--wait-timeout <ms>` | How long `waitfor:` waits |
 | `--keep-storage` | WebKitGTK: keep storage between runs |
+| `--report` | Write `<out>/report.html` with the output and all snapshots (baseline and difference after `--compare`) |
 | `--compare` / `--update-baseline` | Compare snapshots with baselines / replace the baselines |
 | `--baseline <dir>` / `--max-diff-pixels <n>` / `--compare-tolerance <n>` | Baseline folder, allowed difference |
 | `--base-url <url>` | Base for routes |
@@ -314,6 +348,7 @@ webview-preview [route-or-url] [steps...] [options]
 | `--log-requests` | Only list requests, answer nothing |
 | `--tauri` | Stub the Tauri bridge (answers from `tauri.commands` in the config) |
 | `--locale <tag>` | `navigator.language` for the page |
+| `--fail-on-error` | Exit with 1 when the page logged `console.error` or threw |
 | `--config <file>` | Use this config file |
 | `--no-config` | Ignore config files |
 | `-h`, `--help` / `-v`, `--version` | |
@@ -352,6 +387,9 @@ result.failed; // false
 `preview()` reads the config file the same way the CLI does; pass `config: false` to skip it or `config: "path"` to
 choose one. Types are included.
 
+`watchPreview(options, onRun)` is `--watch`: it runs once, then again on every change, calls `onRun(result)` after
+each run and resolves to a function that stops watching and the server.
+
 ## Login, backend and other things outside the page
 
 A real app rarely shows the screen you want straight away: it checks a session and sends you to a login page, it
@@ -462,7 +500,23 @@ With `mock` set, the same list shows which requests were answered: `GET /api/me
 desktop side does by itself (a Tauri command that calls a server from Rust). For desktop calls, stub the bridge in
 `init`; for the rest, run the real service locally.
 
-## Desktop bridges: Tauri, Electron, Wails
+### 4. Slow network and offline
+
+How does the screen look while data is on its way, and what happens when the connection drops?
+
+```sh
+npx webview-preview /dashboard --latency 2000 wait:300 snap:loading wait:2500 snap:loaded
+npx webview-preview /dashboard waitfor:.instance-card offline snap:offline online wait:1000 snap:back-online
+```
+
+| | |
+|---|---|
+| `latency:<ms>` step / `--latency <ms>` / `latency` in the config | Every `fetch` / XHR request waits that long first, answers from `mock` too. `latency:0` turns it off. |
+| `offline` / `online` steps, `--offline` / `offline: true` | `navigator.onLine` turns `false`, the page gets the `offline` event, `fetch` rejects with `TypeError: Failed to fetch`, XHR fires `error`. `online` brings it all back and fires `online`. `--offline` starts that way; the page itself still loads. |
+
+While offline, the request list shows `GET /api/me -> offline`. Like `mock`, this covers `fetch` and XHR only:
+pictures, WebSocket and the desktop side keep their connection.
+
 
 Your frontend calls the desktop side: Tauri's `invoke`, an Electron preload API, Wails bindings. Outside the app
 there is no desktop side, so those calls fail — and the screen you want may never render. `webview-preview` puts a
@@ -560,6 +614,9 @@ npx webview-preview /settings snap:settings "snap:menu@[role=menu]" --compare
   The `.diff.png` shows the snapshot in grey with the changed pixels in red. More than `maxDiffPixels` changed
   (default `0`) → exit code `1`.
 - **The change is intended**: `--update-baseline` replaces the baselines with this run's snapshots.
+- **See it all on one page**: add `--report`. `<out>/report.html` shows the run's output and every snapshot —
+  after `--compare` with the baseline, this run and the difference side by side, changed ones marked red. Open it in
+  any browser; it works without a server and follows the system's light or dark theme.
 
 Snapshots differ between engines and screen scales, so the engine is part of the file name (`webkitgtk-…`,
 `msedge-…`) and each engine has its own baselines. `compareTolerance` (default `2` of 255 per channel) ignores
@@ -591,8 +648,38 @@ for engine in webkitgtk chrome; do npx webview-preview /settings --engine $engin
 
 ```sh
 npx webview-preview / snap:wide resize:900x500 wait:300 snap:narrow
+npx webview-preview / snap:home --size 1200x650,800x600,480x800
+```
+
+**Keep a snapshot fresh while you edit** — leave it running next to the editor and keep the PNG open:
+
+```sh
+npx webview-preview /settings waitfor:.settings snap:settings "measure:.settings" --watch
+```
+
+Every save runs the steps again from a clean page (the dev server stays up), prints the numbers and rewrites the
+snapshot. A change of the config file is picked up too.
+
+**See an animation, not only where it ends** — a dialog that opens:
+
+```sh
+npx webview-preview / "click:text=New project" "film:open:500@[role=dialog]"
+```
+
+One picture with 10 frames: you see whether it fades and grows smoothly, starts from the wrong place, jumps at the end
+or plays twice. Frames are real screenshots taken as fast as the engine allows, so the printed times are what to
+trust, not the planned spacing.
+
+**Light and dark, with and without motion:**
+
+```sh
+for scheme in light dark; do npx webview-preview / snap:home-$scheme --color-scheme $scheme; done
+npx webview-preview / click:.menu-button snap:menu-open --reduced-motion
 ```
 
+With `--reduced-motion` a page that respects it skips its transitions, so a snapshot right after a click shows the
+final state instead of a frame in the middle of the animation — and you see whether the page respects it at all.
+
 **Measure instead of looking** — sizes and positions are more reliable than eyes:
 
 ```sh
@@ -633,6 +720,8 @@ More of these — animations frame by frame, measuring, getting past login — i
 | `WebKitGTK engine needs Linux with python3-gi and WebKit2 4.1` | Install the [Linux packages](#linux--webkitgtk). |
 | `This engine needs playwright-core` | `npm i -D playwright-core`. |
 | `Executable doesn't exist` (Playwright) | `npx playwright install webkit` (or `chromium`); for `msedge` / `chrome` install the browser itself. |
+| macOS, `webkit`: `Tab` skips buttons and links | That is macOS: with Full Keyboard Access off (the default) WebKit tabs to text fields only — a Tauri app on a Mac behaves the same. Use `key:Alt+Tab` to reach every element, as Option+Tab does in Safari. |
+| WebKitGTK in CI | Run under `xvfb-run -a` (it needs an X display even off-screen); `sudo apt-get install -y python3-gi gir1.2-webkit2-4.1 xvfb`. |
 | `Server did not open port …` | The `server.command` failed or uses another port. Run it by hand to see why; raise `readyTimeoutMs` for slow starts. |
 | `"/route" is not a full URL` | Set `baseUrl` in the config or pass `--base-url`. |
 | Blank snapshot | The page needs more time or threw on start: add `wait:2000`, and `print:document.body.innerHTML.length`. |
@@ -653,6 +742,17 @@ agent to it (for example from `CLAUDE.md` or `AGENTS.md` in your project):
 UI changes: check them in the real engine with `npx webview-preview` — see node_modules/webview-preview/AGENTS.md.
 ```
 
+## Development
+
+```sh
+npm test                                   # the default engine for this system
+WEBVIEW_PREVIEW_ENGINE=chrome npm test     # one engine
+```
+
+The tests open `test/fixture/index.html` and check snapshots, input, focus order, errors, mock, offline, sizes,
+`film:`, compare and the report. GitHub Actions runs them on every push: WebKitGTK and Chromium on Linux, Edge and
+Chrome on Windows, WebKit on macOS; snapshots and reports of every run are kept as artifacts.
+
 ## License
 
 MIT © n0t4u404

package/bin/webview-preview.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { cleanSnapshots, ENGINES, preview } from "#src/index.mjs";
+import { cleanSnapshots, ENGINES, preview, watchPreview } from "#src/index.mjs";
 
 const FLAGS = {
 	"--engine": "engine",
@@ -16,7 +16,9 @@ const FLAGS = {
 	"--compare-tolerance": "compareTolerance",
 	"--older-than": "olderThan",
 	"--wait-timeout": "waitTimeout",
-	"--locale": "locale"
+	"--locale": "locale",
+	"--color-scheme": "colorScheme",
+	"--latency": "latency"
 }
 const LIST_FLAGS = { "--init": "init", "--init-file": "initFile", "--mock-file": "mockFile" }
 
@@ -34,17 +36,26 @@ Steps:
   snap:<name>      save <out>/<prefix><name>.png
   print:<expr>     print the value of an expression
   measure:<css selector>  print size, position, box, visibility, font and text of the element
+  assert:<expr>    check that the expression is truthy; if not, print why and exit with 1
+  focusorder[:<n>] press Tab n times (default 20) and print where focus went; shows when it loops
+  film:<name>:<ms>[/<n>][@<css selector>]  n frames (default 10) over ms, from now, into one
+                   <out>/<prefix><name>.png, 5 per row; with a selector, cropped to where the element was
   resize:<WxH>     resize the window
   snap:<name>@<css selector>  save only that element (plus --snap-margin)
   key:<key>        press a key: Tab, Shift+Tab, Enter, Escape, ArrowDown, Control+a, x …
   type:<text>      type text with the keyboard
   hover:<css selector>  move the mouse to the element's centre
   click:<css selector>  click the element's centre with the mouse
+  offline / online go offline or back: navigator.onLine, online/offline events, fetch and XHR fail
+  latency:<ms>     delay every fetch/XHR request by ms (0 turns it off)
   macro:<name>     run the steps of a macro from the config (macros: { name: [...] })
 
 Options:
   --engine <name>  ${ENGINES.join(" | ")} (default: auto)
-  --size <WxH>     window size in CSS pixels (default: 1200x650)
+  --size <WxH>     window size in CSS pixels (default: 1200x650); several sizes, comma-separated
+                   (1200x650,800x600), run the steps once per size into <prefix><WxH>-<name>.png
+  --color-scheme <light|dark>  prefers-color-scheme for the page (default: the system's)
+  --reduced-motion prefers-reduced-motion: reduce
   --out <dir>      folder for snapshots (default: .webview-preview)
   --prefix <text>  file name prefix (default: "<engine>-")
   --scale <n>      device pixel ratio for Playwright engines (default: 1); WebKitGTK renders
@@ -53,6 +64,8 @@ Options:
   --headed         WebKitGTK: show a real window instead of rendering off-screen
   --wait-timeout <ms>  how long waitfor waits (default: 10000)
   --keep-storage   WebKitGTK: keep localStorage, cookies and cache between runs (default: start clean)
+  --report         write <out>/report.html: the output and every snapshot, with baseline and
+                   difference next to it after --compare
   --compare        compare every snapshot with the baseline of the same name (a missing one is created)
   --update-baseline  replace the baselines with this run's snapshots
   --baseline <dir> baseline folder (default: webview-preview-baseline)
@@ -67,6 +80,11 @@ Options:
   --tauri          stub the Tauri bridge (invoke, events, window); answers come from
                    tauri.commands in the config, anything else gets null
   --locale <tag>   navigator.language for the page: en-US, ru-RU … (Playwright: also Intl)
+  --offline        start offline (the page itself still loads)
+  --latency <ms>   delay every fetch/XHR request from the start
+  --watch          run again whenever a file changes (the config's watch, default src/ or the config's folder,
+                   plus the config file); the server stays up between runs
+  --fail-on-error  exit with 1 when the page logged console.error or threw (they are always printed)
   --config <file>  config file (default: webview-preview.config.{mjs,js,json})
   --no-config      ignore config files
 
@@ -102,6 +120,26 @@ const parseArgs = argv => {
 			options.headed = true;
 			continue;
 		}
+		if (arg === "--report") {
+			options.report = true;
+			continue;
+		}
+		if (arg === "--watch") {
+			options.isWatching = true;
+			continue;
+		}
+		if (arg === "--offline") {
+			options.offline = true;
+			continue;
+		}
+		if (arg === "--reduced-motion") {
+			options.reducedMotion = true;
+			continue;
+		}
+		if (arg === "--fail-on-error") {
+			options.failOnError = true;
+			continue;
+		}
 		if (arg === "--tauri") {
 			options.tauri = true;
 			continue;
@@ -152,7 +190,18 @@ try {
 		console.log(`${cleanOptions.dryRun ? "would delete" : "deleted"} ${removed.length} snapshot(s) in ${out}`);
 		process.exit(0);
 	}
-	const result = await preview(parsed.options);
+	const { isWatching, ...previewOptions } = parsed.options;
+	if (isWatching) {
+		const stop = await watchPreview(previewOptions, result => {
+			for (const file of result.saved) console.log(file);
+		});
+		for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(signal, () => {
+			stop();
+			process.exit(0);
+		});
+		await new Promise(() => {});
+	}
+	const result = await preview(previewOptions);
 	for (const file of result.saved) console.log(file);
 	process.exit(result.failed ? 1 : 0);
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "webview-preview",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "Open your UI in the engine your desktop app really runs on (WebKitGTK, Edge/WebView2, WebKit), drive it with steps and save PNG snapshots.",
 	"license": "MIT",
 	"author": "n0t4u404",
@@ -30,6 +30,9 @@
 	"imports": {
 		"#src/*": "./src/*"
 	},
+	"scripts": {
+		"test": "node --test"
+	},
 	"bin": {
 		"webview-preview": "bin/webview-preview.mjs"
 	},

package/src/core/config.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -10,7 +10,8 @@ export const loadConfig = async (configPath, cwd = process.cwd()) => {
 		: CONFIG_FILES.map(name => path.join(cwd, name)).find(candidate => existsSync(candidate));
 	if (!file) return {}
 	if (!existsSync(file)) throw new Error(`Config not found: ${file}`);
-	if (file.endsWith(".json")) return { ...JSON.parse(readFileSync(file, "utf8")), configDir: path.dirname(file) }
-	const module = await import(pathToFileURL(file).href);
-	return { ...(module.default ?? module), configDir: path.dirname(file) }
+	const where = { configDir: path.dirname(file), configFile: file }
+	if (file.endsWith(".json")) return { ...JSON.parse(readFileSync(file, "utf8")), ...where }
+	const module = await import(`${pathToFileURL(file).href}?mtime=${statSync(file).mtimeMs}`);
+	return { ...(module.default ?? module), ...where }
 }

package/src/core/steps.mjs

@@ -1,10 +1,19 @@
+import { NETWORK_STEPS, networkStep } from "#src/page/network.mjs";
+
 export const LOAD_SETTLE_MS = 1500;
 export const JS_SETTLE_MS = 700;
 export const TIMEOUT_MS = 30000;
 export const WAIT_FOR_TIMEOUT_MS = 10000;
 export const WAIT_FOR_POLL_MS = 50;
 
-const STEP_KINDS = new Set(["js", "jsnow", "wait", "waitfor", "snap", "print", "measure", "resize", "key", "type", "hover", "click"]);
+const STEP_KINDS = new Set(["js", "jsnow", "wait", "waitfor", "snap", "print", "measure", "assert", "focusorder", "resize", "key", "type", "hover", "click", "offline", "online", "latency", "film"]);
+export const ASSERT_MARKER = "__webviewPreviewAssert:";
+export const FOCUS_MARKER = "__webviewPreviewFocus:";
+const FOCUS_ORDER_DEFAULT = 20;
+const FOCUS_ORDER_MAX = 200;
+const FILM = /^([^:@]+):(\d+)(?:\/(\d+))?(?:@(.+))?$/s;
+const FILM_FRAMES_DEFAULT = 10;
+const FILM_FRAMES_MAX = 60;
 const MODIFIERS = { Shift: "Shift", Control: "Control", Ctrl: "Control", Alt: "Alt", Meta: "Meta" }
 export const KEY_NAMES = [
 	"Tab", "Enter", "Escape", "Backspace", "Delete", "Insert", "Space", "Home", "End", "PageUp", "PageDown",
@@ -82,6 +91,53 @@ const MEASURE_FUNCTION = `(selector, query, isVisible) => {
 	].join(" · ");
 }`;
 
+const assertExpression = expression => `(() => {
+	const show = value => {
+		if (typeof value === "string") return JSON.stringify(value);
+		if (typeof Node !== "undefined" && value instanceof Node) return value.nodeType === 1 ? value.outerHTML.slice(0, 120) : String(value.nodeName);
+		try {
+			return JSON.stringify(value) ?? String(value);
+		} catch {
+			return String(value);
+		}
+	}
+	const report = problem => ${JSON.stringify(ASSERT_MARKER)} + JSON.stringify([${JSON.stringify(expression)}, problem]);
+	try {
+		const value = (${expression});
+		return report(value ? null : "got " + show(value));
+	} catch (error) {
+		return report("threw " + (error && error.message || error));
+	}
+})()`;
+
+const FOCUS_DESCRIBE = `(() => {
+	const element = document.activeElement;
+	if (!element || element === document.body || element === document.documentElement) return ${JSON.stringify(FOCUS_MARKER)} + JSON.stringify(["item", null]);
+	const tag = element.tagName.toLowerCase();
+	const role = element.getAttribute("role");
+	const name = element.getAttribute("name");
+	const type = tag === "input" ? element.getAttribute("type") : null;
+	const label = (element.getAttribute("aria-label") || (element.labels && element.labels[0] ? element.labels[0].innerText : "") || element.getAttribute("placeholder") || element.innerText || element.value || element.getAttribute("title") || "").replace(/\\s+/g, " ").trim().slice(0, 40);
+	const parts = [tag + (role ? "[role=" + role + "]" : "") + (name ? "[name=" + name + "]" : "") + (type ? "[type=" + type + "]" : "")];
+	if (element.id && !/^(:|_r_|«)/.test(element.id)) parts[0] += "#" + element.id;
+	if (label) parts.push(JSON.stringify(label));
+	const dialog = element.closest("[role=dialog], dialog");
+	if (dialog) parts.push("in dialog");
+	const path = [];
+	for (let node = element; node && node.nodeType === 1; node = node.parentElement) path.unshift(node.tagName + ":" + [...(node.parentElement ? node.parentElement.children : [])].indexOf(node));
+	return ${JSON.stringify(FOCUS_MARKER)} + JSON.stringify(["item", parts.join(" "), path.join("/")]);
+})()`;
+
+const focusOrderSteps = (value, step) => {
+	const count = value === "" ? FOCUS_ORDER_DEFAULT : Number(value);
+	if (!Number.isInteger(count) || count < 1 || count > FOCUS_ORDER_MAX) throw new Error(`focusorder takes how many Tab presses, 1-${FOCUS_ORDER_MAX}, got "${step}"`);
+	return [
+		{ kind: "print", value: `${JSON.stringify(FOCUS_MARKER)} + JSON.stringify(["start", ${count}])` },
+		...Array.from({ length: count }, () => [{ kind: "key", value: "Tab", key: "Tab", modifiers: [] }, { kind: "print", value: FOCUS_DESCRIBE }]).flat(),
+		{ kind: "print", value: `${JSON.stringify(FOCUS_MARKER)} + JSON.stringify(["end"])` }
+	];
+}
+
 const measureExpression = selector => `(${MEASURE_FUNCTION})(${JSON.stringify(selector)}, ${QUERY_FUNCTION}, ${VISIBLE_FUNCTION})`;
 
 const rectExpression = (selector, isScrolled) => `(() => {
@@ -101,6 +157,16 @@ const rectExpression = (selector, isScrolled) => `(() => {
 	return JSON.stringify({ x: rect.left, y: rect.top, width: rect.width, height: rect.height });
 })()`;
 
+const filmStep = (value, step) => {
+	const match = FILM.exec(value);
+	if (!match) throw new Error(`film needs name:ms, like film:open:400@[role=dialog], got "${step}"`);
+	const [, name, durationMs, count, selector] = match;
+	const frames = Number(count ?? FILM_FRAMES_DEFAULT);
+	if (frames < 2 || frames > FILM_FRAMES_MAX) throw new Error(`film takes 2 to ${FILM_FRAMES_MAX} frames, got "${step}"`);
+	const film = { kind: "film", value: name, durationMs: Number(durationMs), frames }
+	return selector ? { ...film, selector, rect: rectExpression(selector, false) } : film;
+}
+
 const parseKey = combo => {
 	const parts = combo.split("+");
 	const key = parts.pop();
@@ -131,7 +197,7 @@ export const parseSize = value => {
 	return { width: Number(match[1]), height: Number(match[2]) }
 }
 
-export const parseSteps = steps => steps.map(step => {
+export const parseSteps = steps => steps.flatMap(step => {
 	const separator = step.indexOf(":");
 	const kind = separator === -1 ? step : step.slice(0, separator);
 	const value = separator === -1 ? "" : step.slice(separator + 1);
@@ -158,6 +224,13 @@ export const parseSteps = steps => steps.map(step => {
 		if (!selector) throw new Error(`waitfor needs a selector, got "${step}"`);
 		return { kind, value, check: waitForExpression(selector, isGone) }
 	}
+	if (kind === "focusorder") return focusOrderSteps(value, step);
+	if (kind === "film") return filmStep(value, step);
+	if (NETWORK_STEPS.has(kind)) return networkStep(kind, value, step);
+	if (kind === "assert") {
+		if (!value) throw new Error(`assert needs an expression, got "${step}"`);
+		return { kind: "print", value: assertExpression(value), assert: value }
+	}
 	if (kind === "measure") {
 		if (!value) throw new Error(`measure needs a selector, got "${step}"`);
 		return { kind: "print", value: printExpression(measureExpression(value)) }

package/src/core/watch.mjs

@@ -0,0 +1,31 @@
+import { existsSync, statSync, watch } from "node:fs";
+import path from "node:path";
+
+const IGNORED = /(^|[\\/])(node_modules|\.git)([\\/]|$)/;
+const DEBOUNCE_MS = 300;
+
+export const watchFiles = ({ targets, ignore, onChange }) => {
+	let timer;
+	let changed = null;
+	const watchers = targets.map(target => {
+		if (!existsSync(target)) throw new Error(`watch: ${target} does not exist`);
+		const isFile = statSync(target).isFile();
+		try {
+			return watch(target, { recursive: true }, (_, file) => {
+				const full = file && !isFile ? path.join(target, String(file)) : target;
+				if (IGNORED.test(full) || ignore.some(dir => full.startsWith(dir + path.sep))) return;
+				changed = full;
+				clearTimeout(timer);
+				timer = setTimeout(() => onChange(changed), DEBOUNCE_MS);
+			});
+		} catch (error) {
+			if (error.code === "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM") throw new Error("--watch needs Node 20 or newer");
+			throw error;
+		}
+	});
+	
+	return () => {
+		clearTimeout(timer);
+		for (const watcher of watchers) watcher.close();
+	}
+}