@jterrazz/test 16.1.1 → 17.0.0

package/dist/shared-landmarks.js

@@ -0,0 +1,71 @@
+//#region src/visitor/targets/roles.ts
+const stated = (options) => options?.exact === void 0 ? {} : { exact: options.exact };
+const named = (kind) => (name, options) => ({
+	kind,
+	name,
+	...stated(options)
+});
+const optionallyNamed = (kind) => (name, options) => ({
+	kind,
+	...name === void 0 ? {} : { name },
+	...stated(options)
+});
+/** A button (or element with the button role), by accessible name. */
+const button = named("button");
+/** A form field, by label. */
+const field = named("field");
+/** A heading, by accessible name. */
+const heading = named("heading");
+/** A link, by accessible name. */
+const link = named("link");
+/** An element containing the given text. */
+const content = named("text");
+/** An option of a select or listbox, by label; asserted by presence, since a collapsed select's options have no box. */
+const option = named("option");
+/** A modal or non-modal `<dialog>`, by accessible name. A closed one is absent. */
+const dialog = optionallyNamed("dialog");
+/** A live region announcing a result: `role="status"`, an `<output>`. */
+const status = optionallyNamed("status");
+/** A table, by its caption or accessible name. */
+const table = optionallyNamed("table");
+/** A row of a table or grid, by the text of its cells. */
+const row = optionallyNamed("row");
+/** An item of a list, by its text. */
+const listitem = optionallyNamed("listitem");
+/** The escape hatch: an element by `data-testid`. Prefer user-facing targets. */
+const testId = (id) => ({
+	kind: "testId",
+	name: id
+});
+//#endregion
+//#region src/visitor/targets/landmarks.ts
+/** The `banner` landmark: the page header. */
+const banner = optionallyNamed("banner");
+/** The `complementary` landmark: an `<aside>`, a sidebar. */
+const complementary = optionallyNamed("complementary");
+/** The `contentinfo` landmark: the page footer. */
+const contentinfo = optionallyNamed("contentinfo");
+/** The `form` landmark: a form carrying an accessible name. */
+const form = optionallyNamed("form");
+/** The `main` landmark: the primary content of the document. */
+const main = optionallyNamed("main");
+/** The `navigation` landmark: a `<nav>`. Name it when a page has several. */
+const navigation = optionallyNamed("navigation");
+/** The `region` landmark: a `<section>` carrying an accessible name. */
+const region = optionallyNamed("region");
+/** The `search` landmark. */
+const search = optionallyNamed("search");
+/** Restrict a target to the inside of another: `click(within(navigation(), link('Articles')))`. */
+const within = (scope, target) => ({
+	...target,
+	scope: target.scope ? within(scope, target.scope) : scope
+});
+function scopeChain(target) {
+	const chain = [];
+	for (let current = target; current; current = current.scope) chain.unshift(current);
+	return chain;
+}
+//#endregion
+export { testId as S, listitem as _, main as a, status as b, scopeChain as c, button as d, content as f, link as g, heading as h, form as i, search as l, field as m, complementary as n, navigation as o, dialog as p, contentinfo as r, region as s, banner as t, within as u, option as v, table as x, row as y };
+
+//# sourceMappingURL=shared-landmarks.js.map

package/dist/shared-ledger.js

@@ -0,0 +1,68 @@
+import { t as isRecord } from "./shared-json-shape.js";
+import { l as VITEST_ARTIFACTS_DIR } from "./shared-artifacts.js";
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/expectations/in-place/update.ts
+/** `TEST_UPDATE=1` or vitest's `-u` / `--update`. */
+function shouldUpdateSnapshots() {
+	if (process.env.TEST_UPDATE === "1") return true;
+	return process.argv.includes("-u") || process.argv.includes("--update");
+}
+const UPDATE_HINT = "Run with TEST_UPDATE=1 (or vitest -u) to create it.";
+const FROZEN_HINT = "This golden is `{ frozen }`: update mode never writes it. Write the file by hand, or drop `{ frozen }` for one TEST_UPDATE=1 run and put it back.";
+function missingHint(frozen) {
+	return frozen ? FROZEN_HINT : UPDATE_HINT;
+}
+//#endregion
+//#region src/specifications/api/routes/ledger.ts
+const isLedger = (value) => isRecord(value) && Array.isArray(value.reached) && (value.declared === void 0 || Array.isArray(value.declared));
+function entriesOf(directory) {
+	try {
+		return readdirSync(directory, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+}
+const ROUTES_DIR = `${VITEST_ARTIFACTS_DIR}/routes`;
+function shardLedgersDir(shard) {
+	return `${ROUTES_DIR}/shard-${shard.index}-${shard.count}`;
+}
+function clearLedgers(directory) {
+	rmSync(directory, {
+		force: true,
+		recursive: true
+	});
+}
+function writeLedger(directory, ledger) {
+	mkdirSync(directory, { recursive: true });
+	writeFileSync(join(directory, `${randomUUID()}.json`), `${JSON.stringify(ledger)}\n`);
+}
+const parsed = (path) => JSON.parse(readFileSync(path, "utf8"));
+function readLedgers(directory) {
+	return entriesOf(directory).filter((entry) => entry.name.endsWith(".json")).map((entry) => parsed(join(directory, entry.name))).filter((ledger) => isLedger(ledger));
+}
+const PARTIAL_MARK = "partial";
+function markPartial(directory) {
+	mkdirSync(directory, { recursive: true });
+	writeFileSync(join(directory, PARTIAL_MARK), "");
+}
+function measure(ledgers) {
+	const tables = ledgers.map((ledger) => ledger.declared);
+	return {
+		declared: tables.every((table) => table !== void 0) ? tables.flat() : void 0,
+		reached: ledgers.flatMap((ledger) => ledger.reached)
+	};
+}
+async function routesLedger() {
+	try {
+		const { inject } = await import("vitest");
+		return inject("routesLedger");
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { readLedgers as a, writeLedger as c, measure as i, missingHint as l, clearLedgers as n, routesLedger as o, markPartial as r, shardLedgersDir as s, ROUTES_DIR as t, shouldUpdateSnapshots as u };
+
+//# sourceMappingURL=shared-ledger.js.map

package/dist/shared-literate-plugin.js

@@ -0,0 +1,183 @@
+import { n as refusal } from "./shared-refusal.js";
+import { d as isRelativePath, i as readSpecFile, l as SpecSyntaxError, u as dedent } from "./shared-spec-document.js";
+import { readFileSync } from "node:fs";
+import { basename, isAbsolute, resolve } from "node:path";
+//#region src/disk/spec-path.ts
+const DISK_KEY = "@jterrazz/test:disk";
+const DISK = Symbol.for(DISK_KEY);
+/** Name one file, by its path from the spec file. */
+function file(path) {
+	requireRelativePath("file", path);
+	if (path.endsWith("/")) {
+		const bare = path.replace(/\/+$/u, "");
+		throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+			fix: `name the directory with directory(${JSON.stringify(path)}), or the file without its /: file(${JSON.stringify(bare)})`,
+			found: `file(${JSON.stringify(path)}), a path ending in /, which is a directory's`
+		}));
+	}
+	return diskValue("file", path);
+}
+function diskValue(brand, path) {
+	const value = {
+		[DISK]: brand,
+		path
+	};
+	Object.defineProperty(value, Symbol.match, { value: () => {
+		throw new TypeError(refusal("one-verb-per-meaning", {
+			fix: `wrap the string to golden it, \`expect(text(value)).toMatch(${brand}(...))\`, or compare it to a value, \`toMatch('...')\``,
+			found: `toMatch(${brand}(${JSON.stringify(path)})) on a string, a value with no golden`
+		}));
+	} });
+	return Object.freeze(value);
+}
+/** Name one directory, by its path from the spec file, ending in `/`. */
+function directory(path) {
+	requireRelativePath("directory", path);
+	if (!path.endsWith("/")) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `end it in /: directory(${JSON.stringify(`${path}/`)}), or name a file with file(${JSON.stringify(path)})`,
+		found: `directory(${JSON.stringify(path)}), a path that does not end in /`
+	}));
+	return diskValue("directory", path);
+}
+function isDiskFile(value) {
+	return brandOf(value) === "file";
+}
+function isDiskDirectory(value) {
+	return brandOf(value) === "directory";
+}
+function isDiskTarget(value) {
+	return brandOf(value) !== void 0;
+}
+function brandOf(value) {
+	if (value === null || typeof value !== "object") return;
+	const brand = Reflect.get(value, DISK);
+	return brand === "file" || brand === "directory" ? brand : void 0;
+}
+function spelled(value) {
+	if (isDiskTarget(value)) return `${brandOf(value)}(${JSON.stringify(value.path)})`;
+	return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+function requireDiskFile(verb, value, extension = "") {
+	if (!isDiskFile(value)) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `name one file: ${verb}(file('./${exampleOf(verb, extension)}'))`,
+		found: isDiskDirectory(value) ? `${verb}(${spelled(value)}), a directory where one file is read` : `${verb}(${spelled(value)}), a value where a file is read`
+	}));
+	if (!value.path.endsWith(extension)) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `name the ${extension} file ${verb}() reads: ${verb}(file('./${exampleOf(verb, extension)}'))`,
+		found: `${verb}(${spelled(value)}), a file not ending in ${extension}`
+	}));
+	return value;
+}
+function requireDiskTarget(verb, value) {
+	if (!isDiskTarget(value)) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `name the disk: ${verb}(file('./<path>')) for a file, ${verb}(directory('./<path>/')) for a directory`,
+		found: `${verb}(${spelled(value)}), a value where the disk is read`
+	}));
+	return value;
+}
+function exampleOf(verb, extension) {
+	return {
+		fixture: "__fixtures__/config.json",
+		request: "__requests__/create.http",
+		run: "case.spec.yaml",
+		seed: "__seeds__/rows.sql"
+	}[verb] ?? `__expected__/output${extension || ".txt"}`;
+}
+function asRelative(path) {
+	const bare = typeof path === "string" ? path.replace(/^\/+/u, "") : "";
+	return `./${bare === "" ? "__expected__/output.txt" : bare}`;
+}
+function requireRelativePath(call, path) {
+	if (typeof path !== "string" || !isRelativePath(path)) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `start it with ./ or ../, from the spec file: ${call}('${asRelative(path)}')`,
+		found: `${call}(${JSON.stringify(path)}), a path that is not relative to the spec file`
+	}));
+}
+//#endregion
+//#region src/disk/resolved-spec-path.ts
+function resolveSpecPath(verb, path, specDir) {
+	requireRelativePath(verb, path);
+	return resolve(specDir, path);
+}
+//#endregion
+//#region src/expectations/in-place/render.ts
+function escapeTemplate(text) {
+	return text.replaceAll("\\", String.raw`\\`).replaceAll("`", "\\`").replaceAll("${", "\\${");
+}
+function renderText(text, indent) {
+	if (!text.includes("\n")) return `\`${escapeTemplate(text)}\``;
+	const inner = `${indent}    `;
+	const lines = text.split("\n");
+	const last = String(lines.pop());
+	const block = `\n${lines.map((line) => line === "" ? "" : `${inner}${line}`).join("\n")}\n${last === "" ? indent : `${inner}${last}`}`;
+	return dedent(block) === text ? `\`${escapeTemplate(block)}\`` : JSON.stringify(text);
+}
+const NUMBER_MARK = "@@in-place-number:";
+const GROUPED_FROM = 1e4;
+function grouped(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && Math.abs(value) >= GROUPED_FROM ? `${NUMBER_MARK}${String(value).replaceAll(/\B(?=(?:\d{3})+$)/gu, "_")}` : value;
+}
+const MARKED = new RegExp(`"${NUMBER_MARK}(?<digits>-?[\\d_]+)"`, "gu");
+const literal = (value, space) => JSON.stringify(value, (_key, item) => grouped(item), space)?.replaceAll(MARKED, "$<digits>");
+function renderValue(value, indent) {
+	return (literal(value, 4) ?? "undefined").split("\n").join(`\n${indent}`);
+}
+function renderRows(rows, indent) {
+	if (rows.length === 0) return "[]";
+	return `[\n${rows.map((row) => `${indent}    [${row.map((cell) => literal(cell) ?? "null").join(", ")}],`).join("\n")}\n${indent}]`;
+}
+//#endregion
+//#region src/specifications/cli/documents/literate-plugin.ts
+const SPEC_FILE = /\.spec\.yaml(?:\?.*)?$/u;
+function grammarRefusal(error, displayPath) {
+	return new Error(refusal({
+		fix: "write the key the grammar names; the reason prints the accepted set",
+		found: `${displayPath}:${error.line}: ${error.reason}`,
+		read: "docs/reference/linting.md#document-follows-its-grammar",
+		why: "A spec document follows one grammar, read by the parser the runner and the linter share: closed keys, `description:` and `runs:` required, `command:` and `exit:` in every run."
+	}), { cause: error });
+}
+function readDocument(content, displayPath) {
+	try {
+		return readSpecFile(content, displayPath);
+	} catch (error) {
+		throw error instanceof SpecSyntaxError ? grammarRefusal(error, displayPath) : error;
+	}
+}
+function literateModule(content, filePath, runnerPath) {
+	const { description } = readDocument(content, filePath).document;
+	return [
+		"import { test } from 'vitest';",
+		`import { cli } from ${JSON.stringify(runnerPath)};`,
+		"",
+		`test(${JSON.stringify(description)}, async () => {`,
+		`    await cli.run({ [Symbol.for(${JSON.stringify(DISK_KEY)})]: 'file', path: ${JSON.stringify(`./${basename(filePath)}`)} });`,
+		"});",
+		""
+	].join("\n");
+}
+function cleanId(id) {
+	return id.split("?")[0] ?? id;
+}
+function literate(options) {
+	const include = options.include ?? ["**/*.spec.yaml"];
+	let root = process.cwd();
+	return {
+		config: () => ({ test: { include } }),
+		configResolved: (resolved) => {
+			({root} = resolved);
+		},
+		enforce: "pre",
+		load: (id) => {
+			if (!SPEC_FILE.test(id)) return null;
+			const filePath = cleanId(id);
+			const runnerPath = isAbsolute(options.runner) ? options.runner : resolve(root, options.runner);
+			return literateModule(readFileSync(filePath, "utf8"), filePath, runnerPath);
+		},
+		name: "jterrazz-test:literate"
+	};
+}
+//#endregion
+export { renderValue as a, file as c, isDiskTarget as d, requireDiskFile as f, renderText as i, isDiskDirectory as l, literate as n, resolveSpecPath as o, requireDiskTarget as p, renderRows as r, directory as s, grammarRefusal as t, isDiskFile as u };
+
+//# sourceMappingURL=shared-literate-plugin.js.map