@jterrazz/test 15.3.0 → 16.0.0

package/dist/vitest.js

@@ -1,11 +1,12 @@
-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 { i as GROUND_EXPECTED } from "./fixtures.js";
+import { i as SCREENSHOTS_DIR, n as COVERAGE_DIR, o as VITEST_ARTIFACTS_DIR, r as REPORTER_OUTPUT_FILES, t as ATTACHMENTS_DIR } from "./artifacts.js";
+import { n as specDescription } from "./literate.js";
 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
+//#region src/runner/literate-plugin.ts
 /**
 * The `literate()` vite plugin — door one of the spec-document format.
 *
@@ -70,7 +71,7 @@ function literate(options) {
 	};
 }
 //#endregion
-//#region src/vitest/preset.ts
+//#region src/runner/preset.ts
 /**
 * `defineSpecConfig()` — the shared vitest config every repository of the
 * ecosystem starts from.
@@ -116,6 +117,27 @@ const HOOK_TIMEOUT_MS = 3e4;
 */
 const EXCLUDE = [...configDefaults.exclude, "**/_fixtures/**"];
 /**
+* What a test may never carry into the next one, and the one policy the
+* framework states rather than lints.
+*
+* `retry: 0` is the policy: a flaky test is fixed or deleted, never re-rolled
+* until it passes. A retry turns a real defect into a slow one and hides the
+* day it becomes permanent.
+*
+* The three restores are the other half of the same idea. `vi.spyOn`,
+* `vi.stubGlobal` and `vi.stubEnv` each own a teardown, and a test that forgets
+* one leaks into whatever runs next — a failure that appears in a FILE that did
+* nothing wrong and disappears when that file is run alone. Turning them on
+* here is what lets `clock.at()` and `vi.stubEnv()` be written without an
+* `afterEach`, which is the shape rule J6w asks for.
+*/
+const HYGIENE = {
+	restoreMocks: true,
+	retry: 0,
+	unstubEnvs: true,
+	unstubGlobals: true
+};
+/**
 * 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.
@@ -130,20 +152,64 @@ function projectDefaults() {
 	return {
 		cacheDir: VITEST_ARTIFACTS_DIR,
 		test: {
+			attachmentsDir: ATTACHMENTS_DIR,
 			exclude: EXCLUDE,
 			hookTimeout: HOOK_TIMEOUT_MS,
+			...HYGIENE,
 			testTimeout: TEST_TIMEOUT_MS
 		}
 	};
 }
+/**
+* Coverage, when `--coverage` asks for it.
+*
+* `v8` because it is the runtime's own counter: no instrumentation pass, no
+* second transform of every file, and the numbers do not move when the bundler
+* does. The provider is an OPTIONAL peer (`@vitest/coverage-v8`), so a project
+* that never asks for coverage never installs it.
+*
+* `json-summary` is not a taste: it is the machine-readable report the ratchet
+* reads. `text` is for the human running the command, and `html` for the one
+* chasing a line. All three land under `.artifacts/vitest/coverage/`, the one
+* directory the toolchain's page owns.
+*
+* What is EXCLUDED is the shape of the answer, not a way to raise the number:
+* a type-only module has nothing to execute (v8 reports it as 0/0 or, worse,
+* as uncovered lines that cannot be covered), and the CLI entries are proven
+* by running the binary, not by importing it.
+*/
+const COVERAGE = {
+	exclude: [
+		"**/node_modules/**",
+		"specs/**",
+		"**/_fixtures/**",
+		"**/*.d.ts",
+		"**/*.test-d.ts",
+		"**/*.fixtures.ts",
+		"dist/**",
+		".artifacts/**",
+		"**/*.config.ts",
+		"**/*.config.mts"
+	],
+	provider: "v8",
+	reporter: [
+		"text",
+		"html",
+		"json-summary"
+	],
+	reportsDirectory: COVERAGE_DIR
+};
 /** Defaults for the root config — the project ones, plus what only a root carries. */
 function rootDefaults() {
 	return {
 		cacheDir: VITEST_ARTIFACTS_DIR,
 		test: {
-			coverage: { reportsDirectory: COVERAGE_DIR },
+			attachmentsDir: ATTACHMENTS_DIR,
+			coverage: COVERAGE,
 			exclude: EXCLUDE,
 			hookTimeout: HOOK_TIMEOUT_MS,
+			...HYGIENE,
+			outputFile: REPORTER_OUTPUT_FILES,
 			testTimeout: TEST_TIMEOUT_MS
 		}
 	};
@@ -173,7 +239,47 @@ function defineSpecConfig(config = {}) {
 	};
 }
 //#endregion
-//#region src/integrations/vitest-browser/commands.ts
+//#region src/runner/facet-project.ts
+/** 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}/**/*.spec.ts`],
+		...options.serial === true ? { fileParallelism: false } : {},
+		name: facet,
+		sequence: { groupOrder: 0 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
+}
+//#endregion
+//#region src/facets/api/api.project.ts
+/** `api()` — the app met through HTTP. */
+function api(options = {}) {
+	return facetProject("api", options);
+}
+//#endregion
+//#region src/facets/cli/cli.project.ts
+/** 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;
+	const documents = literateOptions?.include ?? CLI_DOCUMENTS;
+	return mergeConfig(project, { plugins: [literate({
+		include: documents,
+		specification: literateOptions?.specification ?? CLI_SPECIFICATION
+	})] });
+}
+//#endregion
+//#region src/seams/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.");
@@ -205,7 +311,7 @@ const COMPONENT_COMMANDS = {
 	goldenWrite
 };
 //#endregion
-//#region src/vitest/projects.ts
+//#region src/facets/component/component.project.ts
 /** The pipeline keys a consumer's Vite config contributes, and nothing else. */
 const PIPELINE_KEYS = [
 	"assetsInclude",
@@ -459,39 +565,6 @@ function componentGlobs(options) {
 	};
 }
 /**
-* 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.
 *
@@ -511,17 +584,17 @@ async function component(options = {}) {
 		optimizeDeps: { include: SEAM_DEPENDENCIES.filter(resolves) },
 		plugins: [mswWorkerPlugin(), ...consumerPlugins],
 		test: {
-			attachmentsDir: `${VITEST_ARTIFACTS_DIR}/attachments`,
 			browser: {
 				commands: COMPONENT_COMMANDS,
 				enabled: true,
+				expect: { toMatchScreenshot: { screenshotDirectory: SCREENSHOTS_DIR } },
 				headless: true,
 				instances: [{ browser: "chromium" }],
 				provider: playwright({ contextOptions: {
 					locale: options.locale ?? "en-US",
 					timezoneId: options.timezone ?? "UTC"
 				} }),
-				screenshotDirectory: `${VITEST_ARTIFACTS_DIR}/screenshots`,
+				screenshotDirectory: SCREENSHOTS_DIR,
 				viewport: viewportOf(options)
 			},
 			...componentGlobs(options),
@@ -535,39 +608,20 @@ async function component(options = {}) {
 	};
 	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);
+//#endregion
+//#region src/facets/integration/integration.project.ts
+/** `integration()` — a module against real services, or against a golden. */
+function integration(options = {}) {
+	return facetProject("integration", options);
 }
+//#endregion
+//#region src/facets/jobs/jobs.project.ts
 /** `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);
-}
+//#endregion
+//#region src/facets/mobile/mobile.project.ts
 /**
 * `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).
@@ -575,23 +629,45 @@ function integration(options = {}) {
 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"];
+//#endregion
+//#region src/facets/website/website.project.ts
 /**
-* 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.
+* 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 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
-	})] });
+function website(options = {}) {
+	return mergeConfig(projectDefaults(), { test: {
+		...options.exclude === void 0 ? {} : { exclude: options.exclude },
+		...options.serial === true ? { fileParallelism: false } : {},
+		include: options.include ?? ["specs/website/**/*.spec.ts"],
+		name: "website",
+		sequence: { groupOrder: 1 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
+}
+//#endregion
+//#region src/runner/projects.ts
+/**
+* A module test runs beside the module it covers: no DOM, no browser, no
+* pipeline. Its suffix is `.test.ts` and its place is OUTSIDE `specs/`, where
+* the assembled product is specified in `.spec.ts` — the two exclusions say
+* exactly that. `.test.tsx` is the third exclusion 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 }
+	} });
 }
 //#endregion
 export { api, cli, component, defineSpecConfig, integration, jobs, literate, mobile, unit, website };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "15.3.0",
+    "version": "16.0.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",
@@ -31,6 +31,7 @@
     "files": [
         "dist",
         "!dist/catalog.*",
+        "!dist/coverage.*",
         "schema"
     ],
     "type": "module",
@@ -64,15 +65,12 @@
         "docs": "npm run build && node dist/catalog.js && typescript docs",
         "lint": "typescript check && node dist/checker.js specs",
         "lint:fix": "typescript fix && node dist/checker.js specs --fix",
-        "test": "vitest --run"
+        "test": "vitest --run",
+        "coverage": "npm run build && vitest --run --coverage && node dist/coverage.js --write",
+        "coverage:check": "node dist/coverage.js"
     },
     "dependencies": {
-        "better-sqlite3": "^12.11.1",
-        "mockdate": "^3.0.5",
         "msw": "^2.15.0",
-        "pg": "^8.22.0",
-        "redis": "^6.1.0",
-        "testcontainers": "^12.0.4",
         "vitest-mock-extended": "^5.0.0",
         "yaml": "^2.9.0"
     },
@@ -84,26 +82,36 @@
         "@types/pg": "^8.20.0",
         "@types/react": "^19.3.0",
         "@types/react-dom": "^19.3.0",
-        "@vitest/browser-playwright": "^4.1.10",
+        "@vitest/browser-playwright": "5.0.1",
+        "@vitest/coverage-v8": "^5.0.1",
+        "better-sqlite3": "^12.11.1",
         "hono": "^4.12.30",
+        "oxlint": "^1.83.0",
+        "pg": "^8.22.0",
         "playwright": "^1.49.0",
         "react": "^19.3.0",
         "react-dom": "^19.3.0",
         "react-router": "^8.4.0",
+        "redis": "^6.1.0",
+        "testcontainers": "^12.0.4",
         "tsdown": "^0.22.7",
         "vite": "^8.1.4",
-        "vitest": "^4.1.10",
+        "vitest": "5.0.1",
         "vitest-browser-react": "^2.3.0",
         "webdriverio": "^9.30.0"
     },
     "peerDependencies": {
         "@vitest/browser-playwright": "*",
         "appium": "^3.0.0",
+        "better-sqlite3": "^12.11.1",
+        "pg": "^8.22.0",
         "playwright": "^1.49.0",
         "react": "^18 || ^19",
         "react-dom": "^18 || ^19",
+        "redis": "^6.1.0",
+        "testcontainers": "^12.0.4",
         "vite": "^6.4.0 || ^7 || ^8",
-        "vitest": "^4.1.10 || ^5",
+        "vitest": "^5",
         "vitest-browser-react": "^2.3.0",
         "webdriverio": "^9.30.0"
     },
@@ -114,6 +122,12 @@
         "appium": {
             "optional": true
         },
+        "better-sqlite3": {
+            "optional": true
+        },
+        "pg": {
+            "optional": true
+        },
         "playwright": {
             "optional": true
         },
@@ -123,6 +137,12 @@
         "react-dom": {
             "optional": true
         },
+        "redis": {
+            "optional": true
+        },
+        "testcontainers": {
+            "optional": true
+        },
         "vite": {
             "optional": true
         },
@@ -134,6 +154,6 @@
         }
     },
     "engines": {
-        "node": ">=20"
+        "node": ">=24"
     }
 }