@jterrazz/test 9.1.0 → 9.2.1

package/dist/oxlint.js

@@ -162,7 +162,7 @@ const RULE_DOCS = {
 	},
 	"a2-known-constructors": {
 		channel: "statique",
-		convention: "Trois constructeurs et seulement trois : `specification.api()`, `specification.jobs()`, `specification.cli(bin)` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur.",
+		convention: "Quatre constructeurs et seulement quatre : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.website()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur.",
 		family: "A",
 		id: "A2",
 		rationale: "Une surface fermée empêche l’invention de constructeurs parallèles et garde l’API mémorisable."
@@ -432,6 +432,22 @@ const RULE_DOCS = {
 		family: "J",
 		id: "J5",
 		rationale: "Un titre est un fragment de prose, pas une phrase — la casse minuscule le garde fragmentaire ; minusculiser un symbole nommé le mal-orthographierait."
+	},
+	"w1-scenario-pure": {
+		channel: "statique",
+		convention: "Un scénario de visite est le When : le visiteur agit, la capture reflète l’état final ; aucun `expect()` dans le callback — les assertions vivent dans le Then, sur le résultat retourné.",
+		facet: "website",
+		family: "W",
+		id: "W1",
+		rationale: "Séparer l’interaction de l’assertion garde la grammaire setup → action → résultat intacte et les scénarios rejouables."
+	},
+	"w2w-user-facing-elements": {
+		channel: "statique",
+		convention: "Les éléments d’un scénario sont user-facing (`button`, `link`, `field`, `heading`, `content`) ; `testId()` est l’unique échappatoire et déclenche un avertissement.",
+		facet: "website",
+		family: "W",
+		id: "W2",
+		rationale: "Tester ce que l’utilisateur voit (rôles, labels) rend les specs robustes aux refontes DOM ; un test-id contourne cette garantie."
 	}
 };
 /**
@@ -736,16 +752,18 @@ const a10DuplicateBinding = {
 };
 //#endregion
 //#region src/lint/rules/a2-known-constructors.ts
-/** The three constructors, and only three (A2 — see docs/10-linting.md). */
+/** The four constructors, and only four (A2 — see docs/10-linting.md). */
 const KNOWN_CONSTRUCTORS = /* @__PURE__ */ new Set([
 	"api",
 	"cli",
-	"jobs"
+	"jobs",
+	"website"
 ]);
 /**
-* CONVENTIONS A2 — `specification.api()`, `specification.jobs()` and
-* `specification.cli()` are the only members. Any other access
-* (`specification.app`, `.http`, `.stack`, …) is flagged at the member site.
+* CONVENTIONS A2 — `specification.api()`, `specification.jobs()`,
+* `specification.cli()` and `specification.website()` are the only members.
+* Any other access (`specification.app`, `.http`, `.stack`, …) is flagged at
+* the member site.
 */
 const a2KnownConstructors = {
 	create(context) {
@@ -762,7 +780,7 @@ const a2KnownConstructors = {
 	},
 	meta: {
 		docs: RULE_DOCS["a2-known-constructors"],
-		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs() and specification.cli() (A2 — see docs/10-linting.md)." },
+		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli() and specification.website() (A2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2404,6 +2422,7 @@ const INTEGRATION_DEPS = {
 	hono: ["hono", "@hono/node-server"],
 	msw: ["msw"],
 	openai: ["openai"],
+	playwright: ["playwright"],
 	postgres: ["pg"],
 	redis: ["redis"],
 	sqlite: ["better-sqlite3"],
@@ -2474,6 +2493,7 @@ const i1LayerBoundaries = {
 			if (layer === "core") {
 				if (target.startsWith("core/") || target.startsWith("integrations/docker/") || target.startsWith("integrations/hono/") || withoutExtension(target) === "vitest/matchers") return null;
 				if (target.startsWith("integrations/msw/") && inside === "core/specification/shared/builder.ts") return null;
+				if (target.startsWith("integrations/playwright/") && inside === "core/specification/website/start-website.ts") return null;
 				return "crossLayer";
 			}
 			if (layer === "integrations") return target.startsWith("core/") || target.startsWith(`integrations/${integrationFolder}/`) ? null : "crossLayer";
@@ -2882,6 +2902,52 @@ const plugin = {
 				messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (J5 — see docs/10-linting.md)." },
 				type: "problem"
 			}
+		},
+		"w1-scenario-pure": {
+			create(context) {
+				return { CallExpression(node) {
+					const callee = node.callee;
+					if (!callee || memberPropertyName(callee) !== "visit") return;
+					const scenario = node.arguments?.[1];
+					if (scenario?.type !== "ArrowFunctionExpression" && scenario?.type !== "FunctionExpression") return;
+					walk(scenario, (inner) => {
+						if (inner.type !== "CallExpression") return;
+						const innerCallee = inner.callee;
+						if (innerCallee?.type === "Identifier" && innerCallee.name === "expect") context.report({
+							messageId: "expectInScenario",
+							node: inner
+						});
+					});
+				} };
+			},
+			meta: {
+				docs: RULE_DOCS["w1-scenario-pure"],
+				messages: { expectInScenario: "No expect() inside a visit scenario — the scenario is the When; assert the final state on the returned result in the Then (W1 — see docs/10-linting.md)." },
+				type: "problem"
+			}
+		},
+		"w2w-user-facing-elements": {
+			create(context) {
+				return { CallExpression(node) {
+					const callee = node.callee;
+					if (!callee || memberPropertyName(callee) !== "visit") return;
+					const scenario = node.arguments?.[1];
+					if (scenario?.type !== "ArrowFunctionExpression" && scenario?.type !== "FunctionExpression") return;
+					walk(scenario, (inner) => {
+						if (inner.type !== "CallExpression") return;
+						const innerCallee = inner.callee;
+						if (innerCallee?.type === "Identifier" && innerCallee.name === "testId") context.report({
+							messageId: "testIdElement",
+							node: inner
+						});
+					});
+				} };
+			},
+			meta: {
+				docs: RULE_DOCS["w2w-user-facing-elements"],
+				messages: { testIdElement: "Prefer a user-facing element (button, link, field, heading, content) over testId() — the escape hatch hides what the user actually sees (W2 — see docs/10-linting.md)." },
+				type: "suggestion"
+			}
 		}
 	}
 };

package/dist/playwright.adapter.js

@@ -0,0 +1,135 @@
+import { mkdtempSync } from "node:fs";
+import { resolve } from "node:path";
+import { tmpdir } from "node:os";
+//#region src/integrations/playwright/playwright.adapter.ts
+/** Translate a user-facing element descriptor into a playwright locator. */
+function locate(page, element) {
+	switch (element.kind) {
+		case "button": return page.getByRole("button", { name: element.name });
+		case "field": return page.getByLabel(element.name);
+		case "heading": return page.getByRole("heading", { name: element.name });
+		case "link": return page.getByRole("link", { name: element.name });
+		case "testId": return page.getByTestId(element.name);
+		case "text": return page.getByText(element.name);
+	}
+}
+/** The visitor implementation — every action auto-waits via playwright actionability. */
+function createVisitor(page, baseUrl) {
+	return {
+		check: (element) => locate(page, element).first().check(),
+		click: (element) => locate(page, element).first().click(),
+		fill: (element, value) => locate(page, element).first().fill(value),
+		goto: async (path) => {
+			await page.goto(`${baseUrl}${path}`, { waitUntil: "load" });
+		},
+		hover: (element) => locate(page, element).first().hover(),
+		press: (key) => page.keyboard.press(key),
+		see: (element) => locate(page, element).first().waitFor({ state: "visible" }),
+		select: async (element, option) => {
+			await locate(page, element).first().selectOption(option);
+		}
+	};
+}
+/**
+* Browser adapter backed by playwright chromium.
+*
+* ONE browser process per adapter (= per runner = per vitest worker),
+* launched lazily on the first `open()`. Each visit gets a fresh
+* `BrowserContext` — isolation without paying a browser launch per spec.
+*
+* Playwright is an optional peer dependency: it is only imported here, and
+* this module is only loaded when a spec calls `.visit()`.
+*/
+var PlaywrightAdapter = class {
+	browser = null;
+	async close() {
+		if (this.browser) {
+			await this.browser.close();
+			this.browser = null;
+		}
+	}
+	async open(url, options) {
+		const context = await (await this.launch()).newContext({ extraHTTPHeaders: options.headers });
+		if (options.external === "block") {
+			const origin = new URL(options.baseUrl).origin;
+			await context.route("**/*", (route) => {
+				if (new URL(route.request().url()).origin === origin) route.continue();
+				else route.abort();
+			});
+		}
+		try {
+			const page = await context.newPage();
+			const consoleMessages = [];
+			page.on("console", (message) => {
+				consoleMessages.push({
+					text: message.text(),
+					type: message.type()
+				});
+			});
+			const response = await page.goto(url, { waitUntil: "load" });
+			if (options.scenario) try {
+				await options.scenario(createVisitor(page, options.baseUrl));
+			} catch (error) {
+				const evidence = await this.captureEvidence(page);
+				throw new Error(`visit scenario failed: ${error instanceof Error ? error.message : String(error)}${evidence ? `\nEvidence: ${evidence}` : ""}`, { cause: error });
+			}
+			const extraction = await page.evaluate(() => {
+				const links = [...document.querySelectorAll("link")].map((link) => ({
+					href: link.href,
+					hreflang: link.hreflang || void 0,
+					rel: link.rel,
+					type: link.type || void 0
+				}));
+				const metas = [...document.querySelectorAll("meta")].map((meta) => ({
+					content: meta.content,
+					name: meta.name || void 0,
+					property: meta.getAttribute("property") ?? void 0
+				}));
+				const jsonLdBlocks = [...document.querySelectorAll("script[type=\"application/ld+json\"]")].map((script) => script.textContent ?? "");
+				return {
+					html: document.documentElement.outerHTML,
+					jsonLdBlocks,
+					links,
+					metas,
+					text: document.body?.innerText ?? "",
+					title: document.title
+				};
+			});
+			return {
+				consoleMessages,
+				status: response?.status() ?? 0,
+				url: page.url(),
+				...extraction
+			};
+		} finally {
+			await context.close();
+		}
+	}
+	/** Screenshot the failing state into a temp file; never masks the original error. */
+	async captureEvidence(page) {
+		try {
+			const path = resolve(mkdtempSync(resolve(tmpdir(), "spec-website-")), "failure.png");
+			await page.screenshot({
+				fullPage: true,
+				path
+			});
+			return path;
+		} catch {
+			return null;
+		}
+	}
+	/** Launch the shared chromium instance (once), with an actionable error when playwright is absent. */
+	async launch() {
+		if (this.browser) return this.browser;
+		let chromium;
+		try {
+			({chromium} = await import("playwright"));
+		} catch {
+			throw new Error(".visit() requires playwright (optional peer dependency): npm install -D playwright && npx playwright install chromium");
+		}
+		this.browser = await chromium.launch();
+		return this.browser;
+	}
+};
+//#endregion
+export { PlaywrightAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "9.1.0",
+    "version": "9.2.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.",
     "keywords": [
         "api-testing",
@@ -49,7 +49,8 @@
         "docs": "npm run build && node dist/catalog.js && typescript docs",
         "lint": "typescript check && node dist/checker.js specs",
         "lint:fix": "typescript fix",
-        "test": "vitest --run"
+        "test": "vitest --run",
+        "pretest": "playwright install chromium"
     },
     "dependencies": {
         "better-sqlite3": "^12.11.1",
@@ -69,12 +70,19 @@
         "@types/pg": "^8.20.0",
         "hono": "^4.12.30",
         "oxlint": "^1.74.0",
+        "playwright": "^1.49.0",
         "tsdown": "^0.22.7",
         "vitest": "^4.1.10"
     },
     "peerDependencies": {
+        "playwright": "^1.49.0",
         "vitest": "^4.1.10"
     },
+    "peerDependenciesMeta": {
+        "playwright": {
+            "optional": true
+        }
+    },
     "engines": {
         "node": ">=20"
     }