@crvy/rprtr 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-08-24
+
+### Added
+
+- **reporter:** Portable artifacts mode via CRVY_RPRTR_PORTABLE_ARTIFACTS
+- **server:** --update-snapshots run flag and docker-unavailable run reason
+- **server:** Carry run mode and phase in run-status broadcasts
+- **server:** Docker CLI helpers and container command resolution
+- **server:** DockerLauncher spawning playwright runs in containers
+- **server:** Run-mode resolution, docker launcher wiring, and docker CLI flags
+- **ui:** Run mode badge, update-baselines action, and image-pull state
+
+### Changed
+
+- **run-controller:** Extract RunLauncher strategy with LocalLauncher
+
+### Documentation
+
+- **spec:** Docker browser execution design
+- **plan:** Docker browser execution implementation plan
+- Docker mode usage and options
+- Docker rendering determinism findings; correct baseline arch guidance
+
+### Fixed
+
+- **run-controller:** Make UI re-run work on Playwright 1.59+
+- **server:** Surface auto-mode docker fallback warning
+- **server:** Rewrite container paths in reporter register payloads
+- **server:** Rewrite host paths in docker container command args
+- **server:** Warn when --config path is unreachable inside container
+- **reporter:** Content-addressed artifact names for static-host portability
+- **server:** Route docker runs via rootDir-keyed --test-list with host paths
+
+### Testing
+
+- CI-gated docker smoke test for containerized runs
+## [0.2.4] - 2026-07-06
+
+### Added
+
+- **cli:** Add --help/-h flag to print usage and exit 0
 ## [0.2.3] - 2026-07-03
 
 ### Fixed

package/README.md

@@ -122,6 +122,39 @@ If you generate a report on one operating system and then open it on another (fo
 
 For fully portable artifact loading across operating systems, run the reporter in CI mode (`ci: true`) and ship the `screenshots/` directory alongside the report JSON.
 
+## Docker Mode
+
+Run Playwright browsers inside a pinned Docker container so screenshot baselines are reproducible across machines — no local browser or system-dependency installation required.
+
+```bash
+npx crvy-rprtr --run-mode docker
+```
+
+The server still runs on your host; only `playwright test` executes in the container, against the official `mcr.microsoft.com/playwright:v<your @playwright/test version>-noble` image with your project bind-mounted. Reporters stream results back live, and approve/update flows work unchanged.
+
+| Mode             | Behavior                                                                        |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `auto` (default) | Docker when a daemon is reachable, local on CI, warned local fallback otherwise |
+| `docker`         | Always Docker; runs fail fast with `docker-unavailable` when the daemon is down |
+| `local`          | Never Docker                                                                    |
+
+| Option                         | Description                                                                                                                                                                  |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--run-mode <mode>`            | `local`, `docker`, or `auto` (default: `auto`)                                                                                                                               |
+| `--docker-image <image>`       | Custom image. With a custom image, the container-side package manager is auto-detected from your lockfile (`npx` / `pnpm exec` / `yarn` / `bunx`); the image must contain it |
+| `--docker-platform <platform>` | `linux/amd64` or `linux/arm64` (default: host architecture)                                                                                                                  |
+
+Programmatic equivalents: `startServer({ runMode: 'docker', docker: { image, platform, command, extraArgs } })`. `docker.command` overrides the container-side invocation verbatim (e.g. `['pnpm', 'exec', 'playwright']`); `docker.extraArgs` appends raw `docker run` flags.
+
+Notes:
+
+> **Important — baselines are image-specific, not architecture-specific.** Text rendering follows the image's fontconfig: Ubuntu-based images (including the default `mcr.microsoft.com/playwright:*-noble`) render text with subpixel (LCD) antialiasing and slight hinting, while Debian-based images (e.g. `node:24` + `playwright install --with-deps`) render grayscale with full hinting — different pixels _and_ slightly different text widths. Generate and verify baselines in the **same image** everywhere (CI and local), and regenerate baselines once after switching image flavor. See [docs/docker-screenshot-determinism.md](docs/docker-screenshot-determinism.md) for the full investigation.
+
+- Baselines are **not** architecture-specific for typical DOM/text pages: amd64 and arm64 variants of the same image render bit-identically in practice (verified: 100/103 tests byte-identical between an amd64 CI runner and Apple Silicon). Use the native architecture on every host — do **not** pin `--docker-platform` to force amd64 emulation on Apple Silicon (Rosetta/QEMU is slower and less stable, and buys nothing). Residual risk: canvas 2D / complex SVG / WebGL content can show tiny cross-arch anti-aliasing diffs; handle per-test with `maxDiffPixels`.
+- If your `playwright.config.ts` uses `webServer`, that server now starts inside the container: it must bind `0.0.0.0`, and hosts it references must resolve inside the container.
+- Timezone and locale are pinned (`TZ=UTC`, `LANG=C.UTF-8`, `LC_ALL=C.UTF-8`) so date/number rendering in screenshots is stable; override via `docker.extraArgs` if you need a different locale under test.
+- The "Run & update baselines" button (▶↻) regenerates baselines inside the container, keeping generation and verification in the same image.
+
 ## Programmatic API
 
 ```ts

package/dist/{chunk-HAFWYUNO.js → chunk-4YJL655E.js}

@@ -1,3 +1,9 @@
+// src/ci.ts
+function isCI(env = process.env) {
+  const ci = env.CI;
+  return ci !== void 0 && ci !== "" && ci !== "false" && ci !== "0";
+}
+
 // src/snapshot-path-resolver.ts
 import { createHash } from "crypto";
 import { basename, dirname, extname, join, parse, relative, resolve } from "path";
@@ -187,13 +193,14 @@ var RunTestDescriptorSchema = z.object({
   titlePath: z.array(z.string())
 });
 var RunRequestBodySchema = z.object({
-  tests: z.array(RunTestDescriptorSchema).optional()
+  tests: z.array(RunTestDescriptorSchema).optional(),
+  update: z.boolean().optional()
 });
 var RunResponseSchema = z.discriminatedUnion("ok", [
   z.object({ ok: z.literal(true) }),
   z.object({
     ok: z.literal(false),
-    reason: z.enum(["no-config", "already-running", "no-tests"])
+    reason: z.enum(["no-config", "already-running", "no-tests", "docker-unavailable"])
   })
 ]);
 var StopResponseSchema = z.discriminatedUnion("ok", [
@@ -300,7 +307,9 @@ var WebSocketMessageSchema = z2.discriminatedUnion("type", [
   z2.object({
     type: z2.literal("run-status"),
     data: z2.object({
-      running: z2.boolean()
+      running: z2.boolean(),
+      mode: z2.enum(["local", "docker"]).optional(),
+      phase: z2.string().optional()
     })
   })
 ]);
@@ -330,6 +339,7 @@ var RunEndDataSchema = z2.object({
 var RegisterDataSchema = z2.object({
   playwrightSnapshotDir: z2.string().optional(),
   playwrightTestDir: z2.string().optional(),
+  playwrightRootDir: z2.string().optional(),
   playwrightSnapshotPathTemplate: z2.string().optional(),
   playwrightToHaveScreenshotPathTemplate: z2.string().optional(),
   configFile: z2.string().optional(),
@@ -362,7 +372,8 @@ var ReportApiResponseSchema = z2.object({
   tests: z2.record(z2.string(), TestDataSchema),
   isUpdateMode: z2.boolean().optional(),
   isRunning: z2.boolean().optional(),
-  runEnabled: z2.boolean().optional()
+  runEnabled: z2.boolean().optional(),
+  runMode: z2.enum(["local", "docker"]).optional()
 });
 var ClientBootstrapDataSchema = z2.object({
   report: ReportApiResponseSchema.extend({
@@ -599,6 +610,7 @@ function finalizeRunEvent(state, options = {}) {
 }
 
 export {
+  isCI,
   isForeignAbsolutePath,
   createMutableReportState,
   applyTestBeginEvent,