@jterrazz/test 16.1.0 → 17.0.0

package/dist/config.d.ts

@@ -0,0 +1,40 @@
+import { Preset } from "@jterrazz/typescript/config";
+//#region lint/consumer/rulebook/preset.d.ts
+declare function testPreset(): Preset;
+//#endregion
+//#region lint/kit/project/settings.d.ts
+/** The `test` section of `jterrazz.config.ts`. */
+type TestSettings = {
+  /** The path every api route is mounted under (`'/api'`), left out of the folder each route's subject derives. */
+  basePath?: `/${string}`;
+  /** Api collections no English plural names (`data`, `people`), by route segment. */
+  collections?: readonly string[];
+  /** Routes the api takes on any method (`app.all('/mcp', ...)`), each path mapped to why it takes any. */
+  methodless?: Readonly<Record<string, string>>;
+  production?: {
+    allow: Readonly<Record<string, string>>;
+  };
+  /** How a project departs from the one its tree derives, keyed by its specification, with the reason. */
+  projects?: Readonly<Partial<Record<TestSpecification, TestProject>>>;
+  /** Path to an OpenAPI document (JSON or YAML) declaring the routes, when the app carries no route table. */
+  routes?: string;
+  /** The folders of `specs/` that hold specifications, each filing its specs under the subject they prove: `specs/<specification>/<subject>/`. */
+  specifications?: readonly string[];
+};
+/** The helpers a project is built by, named by their specification. */
+type TestSpecification = 'api' | 'cli' | 'component' | 'integration' | 'job' | 'lint' | 'mobile' | 'unit' | 'website';
+/** What a declared project states beyond its derived one: the global setups it runs, the options its helper takes, and why. */
+type TestProject = {
+  readonly reason: string;
+  readonly setup?: readonly string[];
+  readonly [option: string]: unknown;
+};
+declare module '@jterrazz/typescript/config' {
+  interface JterrazzConfig {
+    /** What `@jterrazz/test` reads. */
+    test?: TestSettings;
+  }
+}
+//#endregion
+export { type TestProject, type TestSettings, type TestSpecification, testPreset as test };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,309 @@
+import { t as isRecord } from "./shared-json-shape.js";
+import { t as CATALOGUE_CHAPTER } from "./shared-chapter.js";
+import { n as specificationModules, t as derivedProjects } from "./shared-derived-projects.js";
+import { t as TEST_SECTION } from "./shared-test-section.js";
+import { n as recommendedRules, t as consumerRows } from "./shared-manifest.js";
+import { createRequire } from "node:module";
+import { RENAMED_FOLDERS, SETUP_FOLDER, SPECIAL_FOLDERS, declaredSubpaths, readAt, rowNamed, whyOf } from "@jterrazz/typescript/rules";
+import { posix } from "node:path";
+import { defineStandard } from "@jterrazz/typescript/config";
+//#region src/standard/standard.ts
+var standard_default = defineStandard({ test: {
+	specifications: [
+		"api",
+		"cli",
+		"component",
+		"integration",
+		"job",
+		"lint",
+		"mobile",
+		"website"
+	],
+	projects: { unit: {
+		isolate: false,
+		reason: "a module test leaves no state behind in a module, so a worker runs its files in one module graph"
+	} }
+} });
+//#endregion
+//#region lint/kit/project/loaded-packages.ts
+const LOADED_BY = {
+	component: [
+		"@vitest/browser-playwright",
+		"playwright",
+		"vitest-browser-react"
+	],
+	mobile: ["appium", "webdriverio"],
+	website: ["@vitest/browser-playwright", "playwright"]
+};
+/** The peers the projects a tree names drive through this package, which the project declares and imports nowhere. */
+function packagesLoadedFor(root) {
+	const projects = derivedProjects(root);
+	return Object.entries(LOADED_BY).flatMap(([project, names]) => projects.has(project) ? names : []);
+}
+//#endregion
+//#region lint/consumer/rulebook/import.ts
+const importRulesForSpecifications = {
+	files: ["**/*.specification.ts"],
+	rules: { "import/exports-last": "off" }
+};
+/** Set in an override because a base profile turns the vitest plugin on in an override over the test globs, and an override's entry replaces a top-level one. */
+const vitestOnTests = {
+	files: ["**/*.{test,spec,test-d,spec-d}.{ts,tsx,js,jsx}", "**/specs/**/*.{ts,tsx}"],
+	rules: {
+		"vitest/consistent-test-filename": ["error", { pattern: String.raw`.*\.(?:test\.[tj]sx?|spec\.[tj]s)$` }],
+		"vitest/max-nested-describe": ["error", { max: 1 }],
+		"vitest/no-restricted-matchers": ["error", {
+			toMatchAriaSnapshot: "The ARIA tree is a golden: `expect(result.tree).toMatch(file('./__expected__/<case>.aria.yaml'))`.",
+			toMatchFileSnapshot: "Name the file yourself: `expect(subject).toMatch(file('./__expected__/<case>.<ext>'))`.",
+			toMatchInlineSnapshot: "An inline snapshot is the run judging itself: `expect(subject).toMatch(file('./__expected__/<case>.<ext>'))`, or compare to a literal with `toStrictEqual`.",
+			toMatchScreenshot: "A screenshot is not a golden this dialect can read: assert the ARIA tree, the content, or the markup.",
+			toMatchSnapshot: "The golden is `expect(subject).toMatch(file('./__expected__/<name>.<ext>'))`, a path from the spec file; under `src/` compare to a literal with `toStrictEqual`.",
+			toThrowErrorMatchingInlineSnapshot: "State the message: `expect(fn).toThrow('<what the subject says>')`.",
+			toThrowErrorMatchingSnapshot: "State the message: `expect(fn).toThrow('<what the subject says>')`."
+		}],
+		"vitest/no-restricted-vi-methods": ["error", {
+			setSystemTime: "`vi.setSystemTime` gives way to `clock.at(iso)`, which gives the calendar back.",
+			stubGlobal: "`vi.stubGlobal('fetch')` gives way to `await using _ = await intercept(defineStubs(...))`; a subject that fetches a PATH states where it resolves: `intercept(stubs, { origin: 'http://<host>.test' })`.",
+			useFakeTimers: "`vi.useFakeTimers` gives way to `clock.at(iso)` and `clock.advance(ms)`.",
+			useRealTimers: "`vi.useRealTimers` gives way to nothing: `using` gives the clock back at the scope end."
+		}],
+		"vitest/prefer-lowercase-title": ["error", { ignoreTopLevelDescribe: true }]
+	}
+};
+//#endregion
+//#region lint/consumer/rulebook/preset.ts
+function taughtBy(name) {
+	const row = rowNamed(consumerRows, name);
+	return {
+		read: readAt(row, CATALOGUE_CHAPTER),
+		why: whyOf(row)
+	};
+}
+const escaped = (text) => text.replaceAll(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
+const either = (patterns) => `(?:${patterns.map((pattern) => `(${pattern})`).join("|")})`;
+const SOURCE = String.raw`\.[cm]?[jt]sx?$`;
+const TEST_FILE = String.raw`\.(test\.[cm]?[jt]sx?|spec\.[cm]?[jt]s)$`;
+const RUNS_A_TEST = String.raw`\.(test\.tsx?|spec\.ts|specification\.tsx?)$`;
+function packages(names) {
+	return either(names.map((name) => {
+		const written = name.endsWith("*") ? `${escaped(name.slice(0, -1))}[^/]*` : escaped(name);
+		return String.raw`(^|/)node_modules/${written}([./]|$)|^${written}([./]|$)`;
+	}));
+}
+const SEAMS = [
+	{
+		fix: "`component.render()` and the element vocabulary render in a real browser: the queries are the same nouns, and they run against what ships",
+		packages: ["@testing-library/*"],
+		seam: "renderer"
+	},
+	{
+		fix: "a drawing of a browser proves what a browser does not: a rendered thing is a `.test.tsx` in the `__tests__/` of its component's folder, collected by `component()`",
+		packages: ["happy-dom", "jsdom"],
+		seam: "simulated-dom"
+	},
+	{
+		fix: "Browser Mode is the seam, not the surface: `component.render()` owns the locators, the visitor and the ARIA tree",
+		packages: [
+			"vitest/browser",
+			"vitest-browser-*",
+			"@vitest/browser*"
+		],
+		seam: "browser-mode"
+	},
+	{
+		fix: "the network answers through stubs: `await using _ = await intercept(defineStubs(...))` in module scope, `.intercept()` on a chain",
+		packages: ["msw", "nock"],
+		seam: "network"
+	},
+	{
+		fix: "the doubles ladder is closed: `mockOf<Port>()` for an injected interface, `vi.fn()` for a function, `vi.spyOn` for an object the test passes in",
+		packages: ["sinon", "vitest-mock-extended"],
+		seam: "doubles"
+	},
+	{
+		fix: "vitest is the runner this vocabulary speaks: `test`, `expect` and `vi` come from it",
+		packages: ["jest", "@jest/*"],
+		seam: "runner"
+	},
+	{
+		fix: "time is one primitive: `using _ = clock.at(iso)` pins the calendar and gives it back at the end of the scope",
+		packages: ["mockdate"],
+		seam: "clock"
+	},
+	{
+		fix: "the website specification drives the browser: `specification.website()` owns the page, and the peer is its",
+		packages: [
+			"playwright",
+			"playwright-core",
+			"@playwright/test"
+		],
+		seam: "browser"
+	},
+	{
+		fix: "the mobile specification drives the simulator: `specification.mobile()` owns the session, and the peers are its",
+		packages: ["webdriverio", "appium"],
+		seam: "simulator"
+	},
+	{
+		fix: "a component rendered to a string is still a component: the test is a `.test.tsx` in the `__tests__/` of its folder, and `result.html` carries the markup",
+		from: String.raw`\.test\.ts$`,
+		packages: ["react-dom/server"],
+		seam: "string-renderer"
+	}
+];
+const secondRuntime = taughtBy("no-second-test-runtime");
+function secondRuntimeLaw(seam, pathNot) {
+	return {
+		fix: seam.fix,
+		from: {
+			path: seam.from ?? RUNS_A_TEST,
+			...pathNot === void 0 ? {} : { pathNot }
+		},
+		name: `no-second-test-runtime-${seam.seam}`,
+		read: secondRuntime.read,
+		to: { path: packages(seam.packages) },
+		why: secondRuntime.why
+	};
+}
+function publishedFix() {
+	const published = declaredSubpaths("@jterrazz/test", import.meta.dirname);
+	return `import from "@jterrazz/test"; the published subpaths are ${published.length === 0 ? "none" : published.join(", ")}`;
+}
+const LAYERS = [
+	{
+		...taughtBy("no-test-to-test-import"),
+		fix: "under `specs/`, move what both read into the `__setup__/` of the lowest folder they share; under `src/`, into a `__tests__/<file>.fixtures.ts` for typed input data",
+		from: { path: TEST_FILE },
+		name: "no-test-to-test-import",
+		to: { path: String.raw`\.test\.[cm]?[jt]sx?$` }
+	},
+	{
+		...taughtBy("fixtures-imported-by-tests-only"),
+		fix: "import it from a `*.test.ts` only, or move what the file needs into a module of its own",
+		from: { pathNot: TEST_FILE },
+		name: "fixtures-imported-by-tests-only",
+		to: { path: String.raw`\.fixtures${SOURCE}` }
+	},
+	...SEAMS.map((seam) => secondRuntimeLaw(seam)),
+	{
+		...taughtBy("no-unpublished-subpath"),
+		fix: publishedFix(),
+		from: {},
+		name: "no-unpublished-subpath",
+		to: {
+			couldNotResolve: true,
+			path: "^@jterrazz/test/"
+		}
+	}
+];
+const EXTENSIONS = [
+	"c",
+	"m",
+	""
+].flatMap((module) => ["j", "t"].flatMap((language) => ["x", ""].map((jsx) => `${module}${language}s${jsx}`)));
+const AT_THE_SPECS_ROOT = [...[
+	"test",
+	"test-d",
+	"spec",
+	"specification"
+].flatMap((kind) => EXTENSIONS.map((extension) => `.${kind}.${extension}`)), ".spec.yaml"];
+const ANY_OTHER_FILE = [
+	".*",
+	".*.*",
+	".*.*.*",
+	".*.*.*.*"
+];
+const OF_A_UNIT = [[".json", "regex:(package|tsconfig)"], [".config.ts", "regex:(jterrazz|vitest)"]];
+function specsRootFiles() {
+	const refused = ANY_OTHER_FILE.map((key) => [key, "exists:0"]);
+	const held = AT_THE_SPECS_ROOT.flatMap((key) => [[key, "regex:.+"], [`.*${key}`, "regex:.+"]]);
+	return Object.fromEntries([
+		...refused,
+		...held,
+		...OF_A_UNIT
+	]);
+}
+const CLOSED_LIST = `regex:${either(["[^_].*", ...SPECIAL_FOLDERS.map((name) => escaped(name))])}`;
+const LISTED = SPECIAL_FOLDERS.map((name) => `\`${name}/\``).join(", ");
+const EARLIER_SPELLINGS = Object.entries(RENAMED_FOLDERS).filter(([earlier]) => earlier.startsWith("_")).map(([earlier, now]) => `\`${earlier}/\` is \`${now}/\``).join(", ");
+const NAMES = [
+	{
+		...taughtBy("specs-root-holds-specifications-and-shared"),
+		fix: `move a file where it belongs: code into \`specs/${SETUP_FOLDER}/\` or the \`${SETUP_FOLDER}/\` of the one specification that reads it, data into the ground folder of its role`,
+		ls: {
+			"**/specs": specsRootFiles(),
+			"**/specs/*": {}
+		},
+		name: "specs-root-holds-specifications-and-shared"
+	},
+	{
+		...taughtBy("special-folder-in-closed-list"),
+		fix: `rename it to the special folder that says what it holds (${LISTED}), or drop the \`_\` if it is a subject; an earlier spelling names its own (${EARLIER_SPELLINGS}), and what \`_shared/\` held sits in the special folders at the specs root`,
+		ignore: SPECIAL_FOLDERS.map((name) => `**/${name}`),
+		ls: { "**/specs/**": { ".dir": CLOSED_LIST } },
+		name: "special-folder-in-closed-list"
+	},
+	{
+		...taughtBy("spec-file-in-a-specs-tree"),
+		fix: "move it under `specs/<specification>/`, or rename it `.test.ts` in the `__tests__/` of the folder of the module it covers",
+		ignore: ["specs", "**/specs"],
+		ls: { "**": {
+			".*.spec.ts": "exists:0",
+			".spec.ts": "exists:0"
+		} },
+		name: "spec-file-in-a-specs-tree"
+	}
+];
+const TEST_COMMENT_OPENINGS = Object.freeze([
+	"Given - ",
+	"When - ",
+	"Then - ",
+	"And - ",
+	"checker-disable",
+	"testId:"
+]);
+const TEST_STANDARD = standard_default.test ?? {};
+const recordOf = (value) => isRecord(value) ? value : {};
+function loadedByName(section) {
+	return Object.values(recordOf(section.projects)).flatMap((project) => {
+		const { root, wrap } = recordOf(project);
+		return typeof wrap === "string" ? [posix.normalize(typeof root === "string" ? posix.join(root, wrap) : wrap)] : [];
+	});
+}
+function testPreset() {
+	return {
+		baseline: [TEST_SECTION],
+		layers: LAYERS,
+		name: TEST_SECTION,
+		names: NAMES,
+		oxlint: {
+			jsPlugins: ["@jterrazz/test/oxlint"],
+			overrides: [importRulesForSpecifications, vitestOnTests],
+			rules: {
+				...recommendedRules,
+				"jterrazz-typescript/comment-states-its-kind": ["error", { openings: [...TEST_COMMENT_OPENINGS] }]
+			}
+		},
+		checker: {
+			label: "Test Conventions (@jterrazz/test)",
+			module: createRequire(import.meta.url).resolve("#checker")
+		},
+		derive: (root) => ({ projects: Object.fromEntries(derivedProjects(root)) }),
+		entries: (section, root) => [...loadedByName(section), ...specificationModules(root)],
+		loadedPackages: packagesLoadedFor,
+		files: { "vitest.config.ts": {
+			scope: "unit",
+			text: "import { vitestConfig } from '@jterrazz/test/vitest';\n\nexport default await vitestConfig(import.meta.url);\n"
+		} },
+		origins: [{
+			file: "src/standard/standard.ts",
+			settings: TEST_STANDARD
+		}],
+		package: "@jterrazz/test",
+		settings: TEST_STANDARD
+	};
+}
+//#endregion
+export { testPreset as test };
+
+//# sourceMappingURL=config.js.map

package/dist/in-place.global-setup.d.ts

@@ -0,0 +1,11 @@
+//#region src/expectations/in-place/in-place.global-setup.d.ts
+export declare function inPlaceSetup(): string;
+type RunProject = {
+  config: {
+    root: string;
+  };
+  provide: (key: 'inPlaceRewrites', value: string) => void;
+};
+export default function setup(project: RunProject): () => void;
+//#endregion
+//# sourceMappingURL=in-place.global-setup.d.ts.map

package/dist/in-place.global-setup.js

@@ -0,0 +1,21 @@
+import { i as writePendingRewrites } from "./shared-in-place.js";
+import { l as VITEST_ARTIFACTS_DIR } from "./shared-artifacts.js";
+import { t as setupEntry } from "./shared-setup-entry.js";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/expectations/in-place/in-place.global-setup.ts
+function inPlaceSetup() {
+	return setupEntry(import.meta.dirname, "in-place");
+}
+const IN_PLACE_DIR = `${VITEST_ARTIFACTS_DIR}/in-place`;
+function setup(project) {
+	const folder = join(project.config.root, IN_PLACE_DIR, randomUUID());
+	project.provide("inPlaceRewrites", folder);
+	return () => {
+		writePendingRewrites(folder);
+	};
+}
+//#endregion
+export { setup as default, inPlaceSetup };
+
+//# sourceMappingURL=in-place.global-setup.js.map