@jterrazz/test 15.1.1 → 15.3.0

package/dist/vitest.js

@@ -1,6 +1,9 @@
+import { c as GROUND_EXPECTED } from "./match.js";
 import { a as specDescription, r as VITEST_ARTIFACTS_DIR, t as COVERAGE_DIR } from "./artifacts.js";
-import { readFileSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { configDefaults, mergeConfig } from "vitest/config";
 //#region src/vitest/literate-plugin.ts
 /**
@@ -116,6 +119,12 @@ const EXCLUDE = [...configDefaults.exclude, "**/_fixtures/**"];
 * Defaults a vitest PROJECT accepts. `coverage` and `reporters` are root-only
 * options (vitest omits them from a project's config), so they are absent here
 * on purpose — setting them would be silently dropped.
+*
+* Exported for the project helpers, which build their canonical project ON
+* these rather than beside them: a helper's project must carry the same
+* budgets and the same artefact directory as a hand-written one.
+*
+* @internal
 */
 function projectDefaults() {
 	return {
@@ -164,4 +173,425 @@ function defineSpecConfig(config = {}) {
 	};
 }
 //#endregion
-export { defineSpecConfig, literate };
+//#region src/integrations/vitest-browser/commands.ts
+/** Where a golden sits: `_expected/<name>` beside the test that asked for it. */
+function goldenPath(testPath, name) {
+	if (testPath === void 0) throw new Error("golden: the command carries no test path — a golden is read from a test file.");
+	return resolve(dirname(testPath), GROUND_EXPECTED, name);
+}
+/** The ARIA snapshot of the rendered `<body>`, as YAML. */
+const ariaTree = async (context) => {
+	return await (await context.frame()).locator("body").ariaSnapshot();
+};
+/** The golden's current content, or `null` when it does not exist yet. */
+const goldenRead = (context, name) => {
+	const path = goldenPath(context.testPath, name);
+	return existsSync(path) ? readFileSync(path, "utf8") : null;
+};
+/** Write the golden — update mode's half, and the path it wrote, for the message. */
+const goldenWrite = (context, name, content) => {
+	const path = goldenPath(context.testPath, name);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, content, "utf8");
+	return path;
+};
+/**
+* The commands, as `component()` registers them — one list, so the names the
+* page calls and the names the project registers cannot drift.
+*/
+const COMPONENT_COMMANDS = {
+	ariaTree,
+	goldenRead,
+	goldenWrite
+};
+//#endregion
+//#region src/vitest/projects.ts
+/** The pipeline keys a consumer's Vite config contributes, and nothing else. */
+const PIPELINE_KEYS = [
+	"assetsInclude",
+	"css",
+	"define",
+	"envPrefix",
+	"esbuild",
+	"json",
+	"oxc",
+	"plugins",
+	"resolve"
+];
+/**
+* The seam's own runtime, pre-bundled so a cold cache never reloads mid-run.
+*
+* `msw` and `msw/browser` are NOT here: `@vitest/browser` already puts both in
+* `optimizeDeps.exclude`, and Vite's esbuild optimizer (6 and 7) treats an
+* entry that is both included and excluded as fatal — dependency optimisation
+* throws before a single test runs.
+*/
+const SEAM_DEPENDENCIES = [
+	"react",
+	"react-dom/client",
+	"react/jsx-dev-runtime",
+	"react/jsx-runtime",
+	"vitest-browser-react"
+];
+const requireFrom = createRequire(import.meta.url);
+/** This module's own file — the frames the caller search walks past. */
+const HELPERS_FILE = import.meta.filename;
+/** A stack frame's file, in either of the two shapes V8 prints it in. */
+const STACK_FRAME = /(?:\((?<wrapped>[^()]+):\d+:\d+\)|at (?<bare>[^()\s]+):\d+:\d+)$/u;
+/** A config vite bundled before importing it — `<its name>.timestamp-<hash>.mjs`. */
+const BUNDLED_CONFIG = /^(?<name>.+)\.timestamp-[^.]+\.mjs$/u;
+/** The file of the first frame below this module — who called the helper. */
+function callerFile() {
+	const { stack } = /* @__PURE__ */ new Error("@jterrazz/test: reading the call site of a project helper");
+	for (const frame of stack?.split("\n").slice(1) ?? []) {
+		const groups = STACK_FRAME.exec(frame.trim())?.groups;
+		const location = groups?.wrapped ?? groups?.bare;
+		if (location === void 0 || location.startsWith("node:")) continue;
+		const file = location.startsWith("file:") ? fileURLToPath(location) : location;
+		if (file !== HELPERS_FILE) return file;
+	}
+}
+/** The nearest directory at or above the cwd holding a file of this name. */
+function nearestHolding(name) {
+	let directory = process.cwd();
+	for (;;) {
+		if (existsSync(resolve(directory, name))) return directory;
+		const parent = dirname(directory);
+		if (parent === directory) return;
+		directory = parent;
+	}
+}
+/**
+* The directory of the CONFIG that called a helper — what the relative paths
+* it was handed mean.
+*
+* Not `process.cwd()`: a `vitest.config.ts` is read by more tools than the
+* runner, and knip and `typescript check` load every config of a repository
+* from the repository ROOT — `component({ vite: './web/vite.config.ts' })`
+* written beside an app resolved against the wrong tree and threw before a
+* single test ran. `import.meta` cannot answer either: it describes THIS
+* module. And vitest hands a project neither its root nor its config file — a
+* project function is called with `{ command, mode, isPreview, isSsrBuild }`
+* and nothing else.
+*
+* So the call site is read off the stack, where a loader that keeps a config's
+* identity (node, tsx, jiti — what those tools use) names the file itself.
+* Vite's own loader does not: it BUNDLES the config into
+* `node_modules/.vite-temp/` and only the config's NAME survives the move. The
+* name is what is then looked for upward from the cwd, because that loader is
+* the runner's and a runner is started in the tree it tests. A config loaded
+* by the runner from another tree entirely states `root` itself.
+*/
+function callerDirectory() {
+	const file = callerFile();
+	if (file === void 0) return process.cwd();
+	const bundled = BUNDLED_CONFIG.exec(basename(file))?.groups?.name;
+	if (bundled === void 0 || basename(dirname(file)) !== ".vite-temp") return dirname(file);
+	return nearestHolding(bundled) ?? process.cwd();
+}
+/** Is this specifier installed here? An absent optional peer is simply not pre-bundled. */
+function resolves(specifier) {
+	try {
+		requireFrom.resolve(specifier);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Serve msw's worker script from the package's OWN install, at the path the
+* worker asks for, with the scope header a worker registered at `/` needs.
+*
+* `@vitest/browser` resolves `/mockServiceWorker.js` too, but from ITS own
+* directory — and it does not depend on `msw`, so that resolution only lands
+* where the installer hoists. The package that OWNS the dependency is the one
+* that can always find it, and it is this one. Without either, a consumer runs
+* `msw init` and declares `msw`, which F8 forbids.
+*/
+function mswWorkerPlugin() {
+	return {
+		configureServer(server) {
+			const script = requireFrom.resolve("msw/mockServiceWorker.js");
+			server.middlewares.use("/mockServiceWorker.js", (_request, response) => {
+				response.setHeader("content-type", "text/javascript");
+				response.setHeader("service-worker-allowed", "/");
+				response.end(readFileSync(script, "utf8"));
+			});
+		},
+		name: "@jterrazz/test:msw-worker"
+	};
+}
+/**
+* Keep an app's Vite PIPELINE and drop everything that says where the app
+* lives.
+*
+* An allow-list, not a drop-list: a consumer's config carries keys the
+* framework has never heard of — `environments`, `ssr`, `appType`, `publicDir`
+* — and one of them re-roots the run and the project collects nothing. Naming
+* what the pipeline IS keeps an unknown key from leaking in. The consumer's
+* `plugins` are CONCATENATED after the seam's, never assigned over them.
+*/
+async function reroot(source, root) {
+	const environment = {
+		command: "serve",
+		isSsrBuild: false,
+		mode: "test"
+	};
+	let loaded;
+	let from = "the value it was given";
+	if (typeof source === "string") {
+		const { loadConfigFromFile } = await import("vite");
+		from = isAbsolute(source) ? source : resolve(root, source);
+		loaded = (await loadConfigFromFile(environment, from))?.config;
+	} else if (typeof source === "function") loaded = await source(environment);
+	else loaded = await source;
+	if (loaded === void 0) throw new Error(`component({ vite }): no config at ${from}`);
+	const inactive = transformKey() === "oxc" ? "esbuild" : "oxc";
+	const kept = {};
+	const config = { ...loaded };
+	for (const key of PIPELINE_KEYS) if (config[key] !== void 0 && key !== inactive) kept[key] = config[key];
+	return kept;
+}
+/** What a missing optional peer costs, said once rather than as a resolver stack. */
+const PROVIDER_MISSING = "component(): @vitest/browser-playwright is an optional peer — install it beside the runner it pins (npm i -D @vitest/browser-playwright@<the installed vitest version> playwright).";
+/** The installed version of a package, read from its own manifest. */
+function versionOf(specifier) {
+	const manifest = JSON.parse(readFileSync(requireFrom.resolve(`${specifier}/package.json`), "utf8"));
+	if (typeof manifest === "object" && manifest !== null && "version" in manifest) return String(manifest.version);
+	throw new Error(`component(): ${specifier} is installed without a version.`);
+}
+/**
+* Which of the two transformer keys the INSTALLED Vite actually reads.
+*
+* Vite 8 transforms with oxc and prints a warning for every `esbuild` option it
+* is handed; Vite 6 and 7 transform with esbuild and have no `oxc` key at all.
+* The inactive one is dropped rather than carried as a second, ignored
+* statement — a config that says the same thing twice is a config that will one
+* day say two different things.
+*/
+function transformKey() {
+	return Number.parseInt(versionOf("vite").split(".")[0] ?? "", 10) >= 8 ? "oxc" : "esbuild";
+}
+/**
+* The JSX default, on the key the running Vite reads, yielding to the
+* consumer's own: a `jsxImportSource` or a classic runtime is the app's
+* statement, not the seam's to overwrite.
+*/
+function jsxPipeline(pipeline) {
+	const key = transformKey();
+	const stated = pipeline[key];
+	if (key === "oxc") return { oxc: stated ?? { jsx: { runtime: "automatic" } } };
+	return { esbuild: stated ?? { jsx: "automatic" } };
+}
+/**
+* `@vitest/browser-playwright` peers vitest on an EXACT version: 4.1.10 wants
+* 4.1.10, not `^4.1`. A mismatch fails deep inside the tester with a message
+* about a missing runner, so the pair is checked where the project is built
+* and both versions are named.
+*/
+function assertProviderPin() {
+	const runner = versionOf("vitest");
+	let provider;
+	try {
+		provider = versionOf("@vitest/browser-playwright");
+	} catch {
+		throw new Error(PROVIDER_MISSING);
+	}
+	if (runner !== provider) throw new Error(`component(): @vitest/browser-playwright@${provider} peers vitest on an exact version, and vitest is ${runner}. Bump both to the same version in one change (npm i -D vitest@${provider} @vitest/browser-playwright@${provider}).`);
+}
+/** The framework's own update flag, read where `process` exists. */
+function updating() {
+	return process.env.TEST_UPDATE === "1" || process.argv.includes("-u") || process.argv.includes("--update");
+}
+/**
+* Hand the project's `wrap` to the page as a STATIC import.
+*
+* The page could fetch the module by URL when the first render needs it, and
+* that is what breaks: a dependency Vite never scanned is discovered mid-run,
+* the optimizer rewrites its cache, and every module the page is holding —
+* the test's own included — 404s behind a stale `?v=` hash. A setup file is in
+* the graph before the first test runs, so the wrap and everything it imports
+* are scanned, pre-bundled, and never re-optimised under the run.
+*
+* It is written into `.artifacts/` rather than served from memory because
+* vitest resolves `setupFiles` as paths on disk; it is generated, so it belongs
+* with everything else a tool generates, and never on the row.
+*
+* The wrapper lands on `globalThis` under a shared symbol rather than an
+* export: the setup module and the package's browser build are separate graphs
+* in the page and share no module instance.
+*/
+function writeSetupFile(wrap, root) {
+	const absolute = resolve(root, wrap);
+	const path = resolve(root, VITEST_ARTIFACTS_DIR, "component-setup.mjs");
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, [
+		"// Generated by `component({ wrap })` — @jterrazz/test. Do not edit.",
+		`import wrap from ${JSON.stringify(absolute)};`,
+		"globalThis[Symbol.for('@jterrazz/test:component-wrap')] = wrap;",
+		""
+	].join("\n"), "utf8");
+	return path;
+}
+/**
+* What the page cannot read for itself: update mode is a `process.env`/`argv`
+* read, and the project's clock is stated where `process` exists.
+*/
+function providedToPage(options) {
+	return {
+		...options.clock === void 0 ? {} : { componentClock: options.clock },
+		componentViewport: viewportOf(options),
+		update: updating()
+	};
+}
+/** The page size every render of the project starts at. */
+function viewportOf(options) {
+	return options.viewport ?? {
+		height: 720,
+		width: 1280
+	};
+}
+/** The globs a component project collects, and the ones it stays out of. */
+function componentGlobs(options) {
+	return {
+		exclude: options.exclude ?? (options.include === void 0 ? ["specs/**"] : []),
+		include: options.include ?? ["**/*.test.tsx"]
+	};
+}
+/**
+* A module test runs beside the module it covers: no DOM, no browser, no
+* pipeline. `.test.tsx` is excluded because a rendered thing is a component
+* test — a project's dependency scan reads every file its globs match, and a
+* `.tsx` collected here would be optimised for a page that never opens.
+*/
+function unit(options = {}) {
+	const fromRoots = options.roots?.map((root) => `${root.replace(/\/+$/u, "")}/**/*.test.ts`);
+	return mergeConfig(projectDefaults(), { test: {
+		exclude: options.exclude ?? ["specs/**", "**/*.test.tsx"],
+		include: options.include ?? fromRoots ?? ["**/*.test.ts"],
+		...options.serial === true ? { fileParallelism: false } : {},
+		name: "unit",
+		sequence: { groupOrder: 0 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
+}
+/**
+* A website spec meets the assembled product through a served page, in the
+* Chromium playwright drives. It opens a browser, so it is scheduled before the
+* component project and never beside it: two Chromiums must not share a slot on
+* a 2-vCPU runner.
+*/
+function website(options = {}) {
+	return mergeConfig(projectDefaults(), { test: {
+		...options.exclude === void 0 ? {} : { exclude: options.exclude },
+		...options.serial === true ? { fileParallelism: false } : {},
+		include: options.include ?? ["specs/website/**/*.test.ts"],
+		name: "website",
+		sequence: { groupOrder: 1 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
+}
+/**
+* A component test renders in a real Chromium — the browser the website facet
+* already drives through the same `playwright` peer.
+*
+* The default `include` reaches the whole project, so the default `exclude`
+* keeps it out of `specs/`, where the assembled product is specified. State
+* your own `include` and the exclusion is yours to state too.
+*/
+async function component(options = {}) {
+	const root = options.root ?? callerDirectory();
+	assertProviderPin();
+	const { playwright } = await import("@vitest/browser-playwright");
+	const pipeline = options.vite === void 0 ? {} : await reroot(options.vite, root);
+	const consumerPlugins = Array.isArray(pipeline.plugins) ? pipeline.plugins : [];
+	const project = {
+		...pipeline,
+		...jsxPipeline(pipeline),
+		optimizeDeps: { include: SEAM_DEPENDENCIES.filter(resolves) },
+		plugins: [mswWorkerPlugin(), ...consumerPlugins],
+		test: {
+			attachmentsDir: `${VITEST_ARTIFACTS_DIR}/attachments`,
+			browser: {
+				commands: COMPONENT_COMMANDS,
+				enabled: true,
+				headless: true,
+				instances: [{ browser: "chromium" }],
+				provider: playwright({ contextOptions: {
+					locale: options.locale ?? "en-US",
+					timezoneId: options.timezone ?? "UTC"
+				} }),
+				screenshotDirectory: `${VITEST_ARTIFACTS_DIR}/screenshots`,
+				viewport: viewportOf(options)
+			},
+			...componentGlobs(options),
+			...options.serial === true ? { fileParallelism: false } : {},
+			name: "component",
+			provide: providedToPage(options),
+			...options.wrap === void 0 ? {} : { setupFiles: [writeSetupFile(options.wrap, root)] },
+			sequence: { groupOrder: 2 },
+			...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+		}
+	};
+	return mergeConfig(projectDefaults(), project);
+}
+/**
+* The node facets' canonical projects.
+*
+* Each one collects the facet's own tree, carries the preset's budgets and
+* artefact directory, and runs in group 0 — the browser facets follow, so two
+* Chromiums never share a slot on a two-vCPU runner. `{ include, exclude,
+* timeout, serial }` is what a repository states when its tree, its budget or
+* its parallelism differs;
+* everything else is the framework's.
+*/
+/** The globs a node facet collects, and the ones a caller stated instead. */
+function facetProject(facet, options) {
+	return mergeConfig(projectDefaults(), { test: {
+		...options.exclude === void 0 ? {} : { exclude: options.exclude },
+		include: options.include ?? [`specs/${facet}/**/*.test.ts`],
+		...options.serial === true ? { fileParallelism: false } : {},
+		name: facet,
+		sequence: { groupOrder: 0 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
+}
+/** `api()` — the app met through HTTP. */
+function api(options = {}) {
+	return facetProject("api", options);
+}
+/** `jobs()` — what a name triggers in-process. */
+function jobs(options = {}) {
+	return facetProject("jobs", options);
+}
+/** `integration()` — a module against real services, or against a golden. */
+function integration(options = {}) {
+	return facetProject("integration", options);
+}
+/**
+* `mobile()` — the app on a simulator. A simulator is the one thing that
+* cannot share a machine with itself, so it runs last and alone (group 3).
+*/
+function mobile(options = {}) {
+	return mergeConfig(facetProject("mobile", options), { test: { sequence: { groupOrder: 3 } } });
+}
+/** The literate defaults — the path convention `cli()` assumes when nothing says otherwise. */
+const CLI_SPECIFICATION = "./specs/cli/cli.specification.ts";
+const CLI_DOCUMENTS = ["specs/cli/**/*.spec.yaml"];
+/**
+* A cli project collects the facet's `.test.ts` files AND its documents: a
+* `<case>.spec.yaml` is a test file of its own (docs/07 § the literate door),
+* so the plugin's glob has to join the include of the project that collects
+* them — which is this one, never the root config.
+*/
+function cli(options = {}) {
+	const { literate: literateOptions, ...common } = options;
+	const project = facetProject("cli", common);
+	if (literateOptions === false) return project;
+	return mergeConfig(project, { plugins: [literate({
+		include: literateOptions?.include ?? CLI_DOCUMENTS,
+		specification: literateOptions?.specification ?? CLI_SPECIFICATION
+	})] });
+}
+//#endregion
+export { api, cli, component, defineSpecConfig, integration, jobs, literate, mobile, unit, website };

package/package.json

@@ -1,10 +1,12 @@
 {
     "name": "@jterrazz/test",
-    "version": "15.1.1",
-    "description": "Declarative testing framework for HTTP APIs, CLIs, and background jobs — one entry point, real infrastructure, golden-file assertions, plus an oxlint convention plugin.",
+    "version": "15.3.0",
+    "description": "Declarative testing framework for HTTP APIs, CLIs, background jobs, websites, mobile apps and rendered components — one entry point, real infrastructure and a real browser, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",
+        "browser-mode",
         "cli-testing",
+        "component-testing",
         "e2e",
         "golden-files",
         "hexagonal",
@@ -14,7 +16,8 @@
         "test-framework",
         "testcontainers",
         "testing",
-        "vitest"
+        "vitest",
+        "website-testing"
     ],
     "license": "MIT",
     "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
@@ -34,6 +37,7 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
+            "browser": "./dist/browser/index.js",
             "import": "./dist/index.js"
         },
         "./vitest": {
@@ -74,29 +78,57 @@
     },
     "devDependencies": {
         "@hono/node-server": "^2.0.8",
-        "@jterrazz/typescript": "^10.0.0",
+        "@jterrazz/typescript": "^10.2.1",
         "@types/better-sqlite3": "^7.6.13",
         "@types/node": "^26.1.1",
         "@types/pg": "^8.20.0",
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
+        "@vitest/browser-playwright": "^4.1.10",
         "hono": "^4.12.30",
         "playwright": "^1.49.0",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0",
+        "react-router": "^8.4.0",
         "tsdown": "^0.22.7",
+        "vite": "^8.1.4",
         "vitest": "^4.1.10",
+        "vitest-browser-react": "^2.3.0",
         "webdriverio": "^9.30.0"
     },
     "peerDependencies": {
+        "@vitest/browser-playwright": "*",
         "appium": "^3.0.0",
         "playwright": "^1.49.0",
-        "vitest": "^4.1.10",
+        "react": "^18 || ^19",
+        "react-dom": "^18 || ^19",
+        "vite": "^6.4.0 || ^7 || ^8",
+        "vitest": "^4.1.10 || ^5",
+        "vitest-browser-react": "^2.3.0",
         "webdriverio": "^9.30.0"
     },
     "peerDependenciesMeta": {
+        "@vitest/browser-playwright": {
+            "optional": true
+        },
         "appium": {
             "optional": true
         },
         "playwright": {
             "optional": true
         },
+        "react": {
+            "optional": true
+        },
+        "react-dom": {
+            "optional": true
+        },
+        "vite": {
+            "optional": true
+        },
+        "vitest-browser-react": {
+            "optional": true
+        },
         "webdriverio": {
             "optional": true
         }