@cevek/screentest 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# screentest
+
+Local desktop tool for visual screenshot-test review. Takes a JSON tree of
+diffs as input, serves a React UI on `127.0.0.1`, lets a human accept new /
+changed snapshots one-by-one or in bulk. Accepted screenshots are uploaded to
+your Cloudflare Worker (R2) and the diff is written back into your project's
+`snapshot.json`.
+
+## Install
+
+```bash
+npm i -D @cevek/screentest
+# or pnpm add -D @cevek/screentest / yarn add -D @cevek/screentest
+```
+
+`screentest` is a CLI — no library API. The package installs a single
+`screentest` bin into `node_modules/.bin/`.
+
+## Run
+
+```bash
+screentest <doc-json-path> [--port 5174] [--no-open]
+                           [--worker-url <url>] [--token <token>]
+```
+
+`doc.json` is the input describing what to review. See the
+[input format](#input-format-docjson) below.
+
+Env vars:
+
+| Var                     | Default                                   |
+| ----------------------- | ----------------------------------------- |
+| `CLOUDFLARE_WORKER_URL` | `https://screentests.x-cevek.workers.dev` |
+| `CLOUDFLARE_TOKEN`      | `SECRET_123`                              |
+
+You almost certainly want to point these at your own R2-backed Worker. See
+the worker template at <https://github.com/x-cevek/screentest/tree/main/cloudflare-worker>.
+
+## Hotkeys
+
+| Key                            | Action                                  |
+| ------------------------------ | --------------------------------------- |
+| `↑` / `↓`                      | Previous / next pending test            |
+| `Enter`                        | Accept current (if valid)               |
+| `Cmd/Ctrl + wheel` over canvas | Move comparison slider                  |
+| Hold mouse on **Show diff**    | Purple-pixel overlay (change-type only) |
+
+## Input format: doc.json
+
+```json
+{
+  "groups": [
+    {
+      "name": "team",
+      "items": [
+        {
+          "name": "login",
+          "type": "new",
+          "actualFilename": "actual/team/login.png",
+          "patchSnapshotJsonFile": "/abs/path/to/snapshot.json"
+        },
+        {
+          "name": "page",
+          "type": "change",
+          "expectedHash": "aaa…(64 hex chars)…",
+          "actualFilename": "actual/team/page.png",
+          "patchSnapshotJsonFile": "/abs/path/to/snapshot.json"
+        },
+        {
+          "name": "deprecated-banner",
+          "type": "deleted",
+          "expectedHash": "bbb…(64 hex chars)…",
+          "patchSnapshotJsonFile": "/abs/path/to/snapshot.json"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Three test-item types:
+
+- **`new`** — `actualFilename` required. On accept, hashes the file (SHA-256
+  hex), uploads it to Cloudflare, inserts `{ name, hash }` into the snapshot
+  file.
+- **`change`** — both `actualFilename` and `expectedHash` required. Tool shows
+  expected vs actual with a slider + purple-pixel diff overlay. On accept, same
+  as `new` (re-hash, re-upload, update the entry).
+- **`deleted`** — `expectedHash` required, no `actualFilename`. Tool shows the
+  expected image plus a "this will be removed" plate. On accept, removes the
+  entry from the snapshot file and prunes any group that becomes empty.
+
+Paths in `actualFilename` are resolved relative to the doc.json directory.
+`patchSnapshotJsonFile` can be relative or absolute.
+
+## Snapshot file format
+
+What the tool writes into `patchSnapshotJsonFile`:
+
+```json
+{
+  "groups": [
+    {
+      "name": "team",
+      "items": [
+        { "name": "login", "hash": "aaa…(64 hex chars)…" },
+        { "name": "page", "hash": "bbb…(64 hex chars)…" }
+      ]
+    }
+  ]
+}
+```
+
+Writes are atomic (tmp file + rename) and serialized by a per-file mutex
+inside the server, so concurrent accepts don't race.
+
+## How tests produce doc.json
+
+The tool does NOT capture screenshots — it only reviews them. Producing the
+actual screenshots and the doc.json is your test runner's job. The simplest
+pattern:
+
+1. In each test, take a screenshot with Playwright; save to a known path; hash
+   it; compare to the entry in `snapshot.json` for that test. Fail the test
+   on mismatch.
+2. On failure (locally), run a script that walks the captured screenshots,
+   diffs them against `snapshot.json` (new / change / deleted), and writes a
+   `doc.json`.
+3. Spawn `screentest doc.json`. User reviews and accepts.
+
+See the [example test-runner setup](https://github.com/x-cevek/screentest/tree/main/test-project)
+for a reference implementation (Vitest + Playwright + helpers).
+
+## Security
+
+- Server listens only on `127.0.0.1` — never on `0.0.0.0`.
+- `actual` files are served strictly from a whitelist computed from
+  `doc.json` at startup. No path-traversal possible from the HTTP layer.
+- Stays in-process; no daemon, no auto-update.
+
+## Cloudflare Worker
+
+The Worker is the blob store. It stores accepted screenshots keyed by their
+SHA-256 hash and serves them back on subsequent reviews. See the
+[worker template + wrangler config](https://github.com/x-cevek/screentest/tree/main/cloudflare-worker)
+for the minimal implementation backed by R2.