v-snap 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Troy Gerwien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,228 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/images/logo.svg" width="110" height="92" alt="">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">vsnap</h1>
+
+<p align="center">
+  <strong>Visual tests as fast and as dependable as unit tests.</strong><br>
+  For views drawn with Pixi, three.js, any canvas, or HTML.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Vitest-5-6E9F18?logo=vitest&logoColor=white" alt="Vitest 5">
+  <img src="https://img.shields.io/badge/Playwright-1.63-2EAD33" alt="Playwright 1.63">
+  <img src="https://img.shields.io/badge/Node-22.17%2B-5FA04E?logo=nodedotjs&logoColor=white" alt="Node 22.17 or later">
+  <img src="https://img.shields.io/badge/types-TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript types">
+  <img src="https://img.shields.io/badge/licence-MIT-7c5cff" alt="MIT licence">
+</p>
+
+`vsnap` makes visual testing as convenient as unit testing. A visual test
+builds a view in a known state, renders it to an image, and compares that
+image with a reference image, which is an accepted image committed beside
+the test file. It is a kind of snapshot test, also known as a visual
+regression test. vsnap runs on Vitest's browser mode, so visual tests are
+Vitest tests. It is not published yet.
+
+## Why vsnap
+
+- **Fast.** A canvas image takes about 4 ms to draw and check, 17 times
+  less than a screenshot test in the same browser. 1000 images run in under
+  8 seconds, start-up included.
+- **The same images on every machine.** Windows, Linux and macOS, on x64
+  and arm64 processors, draw the same images. A reference made on one
+  passes on the others.
+- **No Docker, no setup.** `npm ci` installs everything but the browser,
+  which the first run downloads.
+- **Tests read like unit tests.** One line declares one image, and a new
+  test needs no other change. There is no test page to build.
+- **Pixi, three.js, any canvas, and HTML.** vsnap draws Pixi and three.js
+  views itself, and support for another renderer is a small object. HTML
+  views are tested too.
+- **Vitest's tools work.** Watch mode reruns a test when its view changes.
+  The Vitest UI shows a failed image beside its reference, and the VS Code
+  extension lists and runs the tests.
+
+## How Fast?
+
+The same 1000 images of Pixi views, checked with vsnap and with Vitest's
+own `toMatchScreenshot`, in the same browser:
+
+| | 1000 images, start-up included | One image, at the median |
+| --- | ---: | ---: |
+| **vsnap**, in one page | **7.8 s** | **4.0 ms** |
+| `toMatchScreenshot`, in one page | 89.9 s (11.5x) | 67 ms (17x) |
+| `toMatchScreenshot`, 13 pages at once | 18.0 s (2.3x) | 131 ms (33x) |
+
+Like for like, in one browser page each, vsnap runs the whole suite 11.5
+times as fast, and each image 17 times as fast. By default, Vitest opens a
+page for each processor core but one, and runs that many test files at
+once. On the 14-core laptop measured, that is 13 pages, which share the
+processor, so each screenshot takes longer. Even then, vsnap in one page
+is 2.3 times as fast. A machine with fewer cores, such as a CI runner,
+runs fewer pages at once, so there the gap should be wider.
+
+[The benchmark](docs/how-it-works.md#the-benchmark) says how it was
+measured, and how to run it.
+
+## A Taste
+
+A test file sits in a `visual-tests` folder beside its view. Each test
+gives a name, and a pose: a function that returns the view in the state
+that the test describes.
+
+```tsx
+// src/hud/visual-tests/hud-view.test.tsx
+import { canvasTest } from 'vsnap';
+import { HudView } from '../hud-view';
+
+canvasTest('at the start', () => HudView({ score: () => 0 }));
+canvasTest('a high score', () => HudView({ score: () => 98_765 }));
+```
+
+The first run writes each image as its test's reference, beside the test
+file, as `hud-view.at-the-start.png` and `hud-view.a-high-score.png`. Look
+at them, and commit them. From then on, each run compares the images with
+them.
+
+## When an Image Changes
+
+A test whose image changed fails, and vsnap writes its actual image and a
+diff. The diff shows the reference dimmed, and the pixels that changed in
+red. Here, one more light is on:
+
+| The reference | The actual image | The diff |
+| :---: | :---: | :---: |
+| <img src="docs/images/example-reference.png" width="250" alt="A panel, with three of its lights on at the left, and two at the right"> | <img src="docs/images/example-actual.png" width="250" alt="The same panel, with a fourth light on in the middle"> | <img src="docs/images/example-diff.png" width="250" alt="The panel dimmed, with the new light in red"> |
+
+The failure message says where the image changed, and by how much:
+
+```
+Image 'a-panel' differs from its reference in 214 pixels, by up to 194 of 255,
+in the 16x16 pixels at (116, 108).
+```
+
+It goes on to name the three files, and ends with the command that
+accepts the change: `vitest run <file> -u`. The Vitest UI shows the same
+three images, with a slider between the reference and the actual image.
+
+## Quick Start
+
+1. Install vsnap beside Vitest. npm also installs Playwright and Vitest's
+   Playwright provider, which vsnap needs.
+
+   ```sh
+   npm install --save-dev vsnap vitest
+   ```
+
+2. List vsnap's projects in `vitest.config.ts`, after a project for the
+   unit tests, which leaves out the visual tests.
+
+   ```ts
+   import { configDefaults, defineConfig } from 'vitest/config';
+   import { vsnap } from 'vsnap/vitest';
+
+   export default defineConfig({
+       test: {
+           projects: [
+               {
+                   extends: true,
+                   test: {
+                       name: 'unit',
+                       exclude: [...configDefaults.exclude, '**/visual-tests/**'],
+                   },
+               },
+               ...vsnap(),
+           ],
+       },
+   });
+   ```
+
+3. Register the kinds of view that the tests pose in `vsnap.config.ts`,
+   beside it, and add the file to `tsconfig.json`'s `include`.
+
+   ```ts
+   import { defineVsnapConfig } from 'vsnap';
+   import { pixiViews } from 'vsnap/pixi';
+
+   const config = defineVsnapConfig({ views: [pixiViews()], defaultKind: 'pixi' });
+
+   // Gives canvasTest's types the kinds of view above, and the default kind.
+   declare module 'vsnap' {
+       interface Register {
+           config: typeof config;
+       }
+   }
+
+   export default config;
+   ```
+
+4. Add `.vitest/` to `.gitignore`. vsnap writes a failed test's images
+   there.
+
+5. Write a test, as above, and run `npx vitest`.
+
+[Getting Started](docs/getting-started.md) covers a project whose config
+already has settings, and what vsnap needs.
+
+## Documentation
+
+- **[Getting Started](docs/getting-started.md)**: the requirements, adding
+  vsnap to a project, and the first test.
+- **[Writing Tests](docs/writing-tests.md)**: declaring tests, views that
+  change over time, options, tables of cases, image names, and how HTML
+  views are captured.
+- **[Kinds of View](docs/kinds-of-view.md)**: Pixi, three.js, canvases and
+  HTML, the options of each, preparing and disposing of views, configs in
+  a monorepo, and support for another renderer.
+- **[Configuration](docs/configuration.md)**: `vsnap()`'s options, what
+  its projects inherit, and where test files and references go.
+- **[Running the Tests](docs/running-tests.md)**: the commands, the checks
+  of the references, the summary, reviewing a failed image, CI and watch
+  mode.
+- **[How It Works](docs/how-it-works.md)**: what makes vsnap fast, the
+  benchmark, and how it gives the same images on every machine.
+- **[Limits and Rules](docs/limits-and-rules.md)**: what the images leave
+  out, and the rules that tests follow.
+- **[Troubleshooting](docs/troubleshooting.md)**: vsnap's messages, and
+  what they usually mean.
+
+## API
+
+| Import | Export | What it is |
+| --- | --- | --- |
+| `vsnap` | `canvasTest(name, options?, pose)` | Declares a test of a view drawn on a canvas. It has Vitest's modifiers, such as `.skip`, `.only` and `.each` |
+| | `htmlTest(name, options?, pose)` | Declares a test of an HTML view, with the same modifiers |
+| | `defineVsnapConfig(config)` | Returns the config that `vsnap.config.ts` exports, with its kinds of view and its default kind |
+| | `bindCanvasTest(config)` | Returns a `canvasTest` whose types know one config's kinds of view, for a monorepo's packages |
+| | `htmlViews(options)` | Returns the kind for HTML views, with steps to prepare and dispose of them, and a background for every test |
+| | `fitImage`, `readCanvas` | Helpers for support for another renderer: how an image fits the size budget, and a canvas's pixels |
+| `vsnap/vitest` | `vsnap(options?)` | Returns the Vitest projects that run the visual tests, to list in `test.projects` |
+| `vsnap/pixi` | `pixiViews(options?)` | Returns the kind for Pixi views |
+| `vsnap/three` | `threeViews(options?)` | Returns the kind for three.js views |
+
+## Requirements
+
+| Needs | Version |
+| --- | --- |
+| Vitest, with `@vitest/browser-playwright` | 5 |
+| Playwright, installed with vsnap | 1.63, any patch release |
+| Node | 22.17 or later |
+| Pixi, for Pixi views | 8.16 or later |
+| three.js, for three.js views | 0.160 or later |
+
+A canvas test can draw with the browser's own canvas, and needs no
+renderer library. [Getting Started](docs/getting-started.md#requirements)
+says why each is needed.
+
+## Contributing
+
+To work on vsnap itself, see [CONTRIBUTING.md](./CONTRIBUTING.md). It says
+how vsnap's own tests run, how the package is laid out, how the test
+environment is checked and upgraded, and how the package is built and
+published.
+
+## Licence
+
+MIT. The fonts in `src/browser/fonts/` are under the SIL Open Font
+License, whose text is beside them.

package/lib/browser/calibration.js

@@ -0,0 +1,120 @@
+import { isAllOne } from "../shared/image-pixels.js";
+import { describeDifference, hashPixels, isPass, openSession, toBase64, visualCommands } from "./judge.js";
+import { captureHtmlImage } from "./html-image.js";
+import { CANVAS_CALIBRATION, SAMPLE } from "./canvas-calibration.js";
+import { inject } from "vitest";
+//#region src/browser/calibration.ts
+/**
+* Checks that this machine is the reference environment, before any test
+* runs. First it checks the browser's facts. Then it draws a calibration set
+* of small images. Each one exercises one way that an image can differ
+* between machines. If anything differs beyond the tolerance, the run stops
+* with one error that says what differs. That is clearer than failing every
+* test for one reason that nobody can see. In `environment` mode, it writes
+* the facts and the calibration set's references instead. It runs once per
+* run for each kind of page.
+*/
+async function checkCalibration(pageKind) {
+	const session = await openSession({ calibration: pageKind });
+	if (session.isCalibrated) return;
+	if (!navigator.userAgent.includes("HeadlessChrome")) {
+		const message = `The visual tests (${pageKind}) run in Playwright's headless Chromium, which vsnap sets up, but this page runs in another browser (${navigator.userAgent}), such as a headed one, with --browser.headless=false, or one that the config names. It would draw the images differently, so no actual image of a test was compared. Run the visual tests headless. To look at a view, open its actual image in .vitest/vsnap/, or the failed test in the Vitest UI.`;
+		await visualCommands.abortVisualRun(message);
+		throw new Error(message);
+	}
+	const problems = [...await visualCommands.checkVisualEnvironment(readEnvironment())];
+	const calibrations = pageKind === "canvas" ? CANVAS_JUDGED : HTML_CALIBRATION;
+	if (problems.length === 0) for (const [name, draw] of Object.entries(calibrations)) {
+		const verdict = await draw(name, session.hashes[name]);
+		if (!isPass(verdict)) {
+			const detail = verdict.outcome === "differs" ? describeDifference(verdict) : verdict.outcome;
+			problems.push(`the calibration image '${name}' differs (${detail}), as ${verdict.diffFile ?? verdict.actualFile} shows`);
+		}
+	}
+	if (problems.length > 0) {
+		const message = `This machine is not the visual tests' reference environment (${pageKind}). These checks failed: ${problems.join("; ")}. No test's actual image was compared. vsnap draws with the browser of one Playwright version, so check that the project installs the Playwright version that vsnap's package.json names, and only one copy of it.`;
+		await visualCommands.abortVisualRun(message);
+		throw new Error(message);
+	}
+	await visualCommands.recordVisualCalibration({
+		pageKind,
+		names: Object.keys(calibrations)
+	});
+}
+/**
+* Returns a canvas calibration image that judges itself against its
+* expected hash. Only an image whose hash differs goes to Node.
+*/
+function judgeCanvasCalibration(draw) {
+	return async (name, expectedHash) => {
+		const image = draw();
+		if (isAllOne(image.pixels)) throw new Error(`The calibration image '${name}' is blank. Something it draws with failed on this machine.`);
+		const hash = await hashPixels(image.width, image.height, image.pixels);
+		if (hash === expectedHash) return {
+			outcome: "same",
+			referenceFile: name
+		};
+		return visualCommands.judgeVisualMismatch({
+			calibration: "canvas",
+			name,
+			test: `calibration ${name}`,
+			width: image.width,
+			height: image.height,
+			hash,
+			pixels: toBase64(image.pixels)
+		});
+	};
+}
+const CANVAS_JUDGED = Object.fromEntries(Object.entries(CANVAS_CALIBRATION).map(([name, draw]) => [name, judgeCanvasCalibration(draw)]));
+function readEnvironment() {
+	const gl = document.createElement("canvas").getContext("webgl2");
+	const info = gl?.getExtension("WEBGL_debug_renderer_info");
+	return {
+		browser: /HeadlessChrome\/[\d.]+/.exec(navigator.userAgent)?.[0] ?? navigator.userAgent,
+		webglRenderer: info !== void 0 && info !== null && gl !== null ? String(gl.getParameter(info.UNMASKED_RENDERER_WEBGL)) : "none",
+		locale: Intl.DateTimeFormat().resolvedOptions().locale,
+		timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+		devicePixelRatio
+	};
+}
+/** Creates a calibration image made of HTML markup. */
+function createHtmlCalibration(markup) {
+	return async (name) => {
+		const root = document.createElement("div");
+		root.style.cssText = "padding:8px;color:#e6edf3;font-size:14px;";
+		root.innerHTML = markup;
+		return captureHtmlImage(root, { maxPixels: inject("visualMaxPixels") }, {
+			calibration: "html",
+			name,
+			test: `calibration ${name}`
+		});
+	};
+}
+const HTML_CALIBRATION = {
+	"blank-text": createHtmlCalibration([
+		10,
+		13,
+		13.5,
+		16,
+		17.3,
+		24
+	].map((size) => `<div style="font-size:${size}px;width:max-content;border:1px solid #58a6ff;margin:2px 0">${SAMPLE}</div>`).join("") + "<p style=\"width:200px;border:1px solid #ffe45c;line-height:1.4\">Wrapping text, with emoji 😀 and 漢字, in a narrow box.</p>"),
+	"boxes": createHtmlCalibration(`<div style="display:flex;gap:16px">
+        <div style="width:90px;height:60px;border-radius:14px 4px 22px 8px;background:linear-gradient(135deg,#ff4f8b,#ffe45c)"></div>
+        <div style="width:60px;height:60px;border-radius:50%;background:radial-gradient(circle,#fff,#2a1766);box-shadow:0 6px 14px rgba(0,0,0,.6)"></div>
+        <div style="width:60px;height:40px;border:3px dashed #5bd1ff;outline:2px solid #58a6ff;outline-offset:3px"></div></div>`),
+	"rotated": createHtmlCalibration(`<div style="display:flex;gap:24px;padding:12px">
+        <div style="width:60px;height:40px;background:#ffe45c;transform:rotate(7deg)"></div>
+        <div style="perspective:200px"><div style="width:60px;height:40px;background:#ff4f8b;transform:rotateY(35deg)"></div></div>
+        <img style="width:80px;height:60px;transform:rotate(-3deg)" src="data:image/svg+xml,${encodeURIComponent("<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"40\" height=\"30\"><rect width=\"40\" height=\"30\" fill=\"#2a1766\"/><circle cx=\"20\" cy=\"15\" r=\"10\" fill=\"#5bd1ff\"/></svg>")}"></div>`),
+	"filters": createHtmlCalibration(`<div style="display:flex;gap:18px;padding:10px;background:linear-gradient(90deg,#123,#456)">
+        <div style="width:50px;height:50px;background:#ffe45c;filter:blur(3px)"></div>
+        <div style="width:50px;height:50px;background:#5bd1ff;filter:drop-shadow(4px 4px 3px #000)"></div>
+        <div style="width:50px;height:50px;backdrop-filter:blur(4px);border:1px solid #fff"></div></div>`),
+	"controls": createHtmlCalibration(`<div style="display:flex;gap:10px;align-items:center;flex-wrap:wrap;width:520px">
+        <input type="checkbox" checked><input type="radio" checked><input type="range" value="30">
+        <progress value="0.4"></progress><button>Button</button><select><option>Option</option></select>
+        <input type="text" value="Text field"><textarea rows="2" cols="12">Two lines</textarea></div>`)
+};
+//#endregion
+export { checkCalibration };