@jterrazz/test 9.0.0 → 9.2.0

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.0.0",
+    "version": "9.2.0",
     "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",
@@ -46,10 +46,11 @@
     },
     "scripts": {
         "build": "tsdown --config tsdown.config.ts",
-        "docs": "typescript docs && npm run build && node dist/catalog.js",
+        "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",
@@ -63,18 +64,25 @@
     },
     "devDependencies": {
         "@hono/node-server": "^2.0.8",
-        "@jterrazz/typescript": "^6.1.0",
+        "@jterrazz/typescript": "^7.0.0",
         "@types/better-sqlite3": "^7.6.13",
         "@types/node": "^26.1.1",
         "@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"
     }