@cevek/screentest 0.2.5 → 0.3.1

package/README.md

@@ -1,13 +1,12 @@
 # @cevek/screentest
 
-Local desktop tool for visual screenshot-test review, **plus** the runner
-helpers and Docker-based test harness needed to actually capture the
+Local desktop tool for visual screenshot-test review **plus** the runner
+helpers and Docker-based browser harness needed to capture the
 screenshots. Everything ships in one npm package — no copy-paste.
 
 ## Install
 
 ```bash
-# pick your package manager — all three are supported:
 npm  i -D @cevek/screentest playwright vitest && npx  playwright install firefox
 # pnpm add -D @cevek/screentest playwright vitest && pnpm exec playwright install firefox
 # yarn add -D @cevek/screentest playwright vitest && yarn playwright install firefox
@@ -15,26 +14,31 @@ npm  i -D @cevek/screentest playwright vitest && npx  playwright install firefox
 
 `playwright` and `vitest` are peer-deps — keep them in your devDependencies.
 
-`screentest init` detects your package manager (from your lockfile or
-`packageManager` field) and writes a matching `Dockerfile.tests`.
-
 ## Quick start
 
 ```bash
-# 1. Scaffold the test harness into your project.
+# 1. Scaffold vitest.screentest.config.ts + tests/example.test.ts
 npx screentest init
 
-# 2. Build the Docker image once.
-docker build -f Dockerfile.tests -t screentest-tests .
+# 2. Start the shared Firefox daemon (one-time per machine — image builds
+#    on first run, ~2 min; cached forever after).
+npx screentest serve
 
 # 3. Run.
 APP_URL=http://localhost:5050 npx screentest test
 ```
 
+The daemon lives outside your project — one container serves every
+project on your machine. It listens on `ws://localhost:5180`, holds
+~300MB RAM at idle, and stays up across reboots-of-your-app until you
+`screentest stop` it.
+
+Your **tests run natively on the host** (your normal vitest + TS + path
+aliases + watch mode); only the Firefox rendering happens in the
+container, over a WebSocket. Editing tests never needs an image rebuild.
+
 `screentest init` creates:
 
-- `Dockerfile.tests` — playwright-noble + your project deps + vitest CMD
-  (auto-picked for pnpm / npm / yarn based on your lockfile)
 - `vitest.screentest.config.ts` — separate vitest config wired with the
   package's globalSetup. Kept under its own name so your normal
   `vitest.config.ts` (unit tests) is untouched.
@@ -49,33 +53,38 @@ and screenshot tests via `screentest test` stay completely separate.
 ## Commands
 
 ```bash
-screentest <doc-json-path> [--port 5174] [--no-open]
-                           [--worker-url URL] [--token TOKEN]
+screentest serve    # start the shared Firefox browser-server daemon
+screentest stop     # stop it
+screentest status   # is it running?
 ```
 
-Open the review UI on a pre-built `doc.json`. Used internally by `screentest
-test` and `screentest review`.
-
 ```bash
-screentest test [--host]
+screentest test
 ```
 
-Default workflow: run vitest **inside Docker** (network=host), and on failure
-auto-launch the review UI. `--host` runs vitest on the host instead (debug
-only — bytes diverge from your CI baseline). Set `CI=1` to skip the auto-UI
-launch.
+Run vitest on the host, connect to the daemon for browser rendering.
+On failure (or new snapshots) auto-launch the review UI. Set `CI=1` to
+skip the auto-UI and just propagate the exit code.
 
 ```bash
 screentest review
 ```
 
-Skip vitest, just regenerate `doc.json` from cached actuals and open the UI.
+Skip vitest, regenerate `doc.json` from cached actuals, open the UI.
 
 ```bash
 screentest init
 ```
 
-Scaffold Dockerfile + vitest config + example test (see above).
+Scaffold vitest config + example test (see above).
+
+```bash
+screentest <doc-json-path> [--port 5174] [--no-open]
+                           [--worker-url URL] [--token TOKEN]
+```
+
+Open the review UI on a pre-built `doc.json`. Used internally by
+`screentest test` and `screentest review`.
 
 ## Writing tests
 
@@ -102,26 +111,33 @@ describe('team', () => {
     await page.goto(`${APP_URL}/team`);
     await page.locator('input[name="username"]').waitFor({ state: 'visible' });
     await compareSnapshot(page, 'login'); // → team / login flow / login
+
+    // Snapshot just one element instead of the whole page:
+    await compareSnapshot(page.locator('header'), 'header');
   });
 });
 ```
 
-Snapshot paths are auto-derived from `describe(...)` + `it(...)`. The
-hashes are stored in `snapshot.json` at your project root; actuals + the
-generated `doc.json` go to `node_modules/.cache/screentest/` (gitignored
-by convention).
+Snapshot paths are auto-derived from `describe(...)` + `it(...)` plus the
+`compareSnapshot` leaf name. Hashes go into `tests/snapshot.json` by
+default; override with `SCREENTEST_SNAPSHOT_FILE=path/to/snapshot.json`.
+Actuals + the generated `doc.json` go to
+`node_modules/.cache/screentest/` (gitignored by convention).
+
+> **Upgrading from < 0.3:** an existing `<projectRoot>/snapshot.json` keeps
+> working — the runner picks it up if `tests/snapshot.json` isn't there yet.
 
 ## Docker Desktop host networking
 
-`screentest test` uses `--network=host` so the container can reach your
-app at `localhost:*`. On macOS / Windows Docker Desktop enable it once:
-`Settings → Resources → Network → Enable host networking`. On Linux Docker
-(CI) it works out of the box.
+The daemon container uses `--network=host` so its Firefox can reach
+your app at `localhost:*`. On macOS / Windows Docker Desktop enable it
+once: `Settings → Resources → Network → Enable host networking`. On
+Linux Docker (CI) it works out of the box.
 
 ## Cloudflare Worker (blob store)
 
-Accepted screenshots are stored in your Cloudflare Worker (R2-backed). See
-the [worker template](https://github.com/x-cevek/screentest/tree/main/cloudflare-worker)
+Accepted screenshots are stored in your Cloudflare Worker (R2-backed).
+See the [worker template](https://github.com/x-cevek/screentest/tree/main/cloudflare-worker)
 for a 100-line implementation + `wrangler deploy` instructions.
 
 Once deployed:
@@ -136,12 +152,12 @@ Or pass `--worker-url` / `--token` to `screentest` directly.
 ## CI
 
 ```yaml
-- run: docker build -f Dockerfile.tests -t screentest-tests .
+- run: npx screentest serve # builds image + starts daemon
 - run: CI=1 npx screentest test
 ```
 
-In `CI=1` the orchestrator exits with vitest's code and never tries to open
-the UI.
+In `CI=1` the orchestrator exits with vitest's code and never tries to
+open the UI.
 
 ## Input format reference
 

package/dist/global-setup.js

@@ -2,6 +2,13 @@
 import { firefox } from "playwright";
 var server;
 async function setup(project) {
+  const externalWs = process.env.SCREENTEST_FIREFOX_WS;
+  if (externalWs) {
+    project.provide("wsEndpoint", externalWs);
+    console.log(`[screentest] using external firefox daemon: ${externalWs}`);
+    return async () => {
+    };
+  }
   server = await firefox.launchServer();
   const wsEndpoint = server.wsEndpoint();
   project.provide("wsEndpoint", wsEndpoint);