@untestutils/playwright 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 s00d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/harness.d.ts

@@ -0,0 +1,19 @@
+import { type Recipe } from '@untestutils/core';
+/**
+ * Prepare (or reuse) the harness and ensure `UNTESTUTILS_HOST_*` is set in
+ * *this* worker process. Cross-process reuse only writes `targets.json`;
+ * workers must apply env locally before reading `baseURL`.
+ */
+export declare function resolvePlaywrightHarnessId(harness: string | Recipe): Promise<string>;
+export declare function resolvePlaywrightBaseURL(harnessId: string): string;
+export declare function usePlaywrightHarnessId(harness: string | Recipe, use: (id: string) => Promise<void>): Promise<void>;
+type TestFixtures = {
+    baseURL: string;
+};
+type WorkerFixtures = {
+    harness: string | Recipe;
+    harnessId: string;
+};
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & TestFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & WorkerFixtures>;
+export {};
+//# sourceMappingURL=harness.d.ts.map

package/dist/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,MAAM,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB1F;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,KAAK,YAAY,GAAG;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,IAAI,6QAWf,CAAC"}

package/dist/harness.mjs

@@ -0,0 +1,41 @@
+import { test as base } from "@playwright/test";
+import { ensurePrepared, getRegisteredRecipe, normalizeBaseUrl, resolveArtifactsRoot, envKey, TargetRegistry } from "@untestutils/core";
+
+export async function resolvePlaywrightHarnessId(harness) {
+	const id = typeof harness === "string" ? harness : harness.id;
+	if (!id) throw new Error("[untestutils/playwright] test.use({ harness }) required");
+	const recipe = typeof harness === "string" ? getRegisteredRecipe(harness) : harness;
+	if (!recipe) throw new Error(`[untestutils/playwright] unknown harness "${id}"`);
+	const artifactsRoot = resolveArtifactsRoot();
+	const prepared = await ensurePrepared(recipe, { artifactsRoot });
+	const runningUrl = "url" in prepared.running ? prepared.running.url : undefined;
+	if (runningUrl) {
+		process.env[envKey(id)] = normalizeBaseUrl(runningUrl);
+	} else {
+		const registry = new TargetRegistry(artifactsRoot);
+		const entry = await registry.get(id);
+		if (entry) registry.applyEnv(entry);
+	}
+	return id;
+}
+export function resolvePlaywrightBaseURL(harnessId) {
+	const key = envKey(harnessId);
+	const url = process.env[key];
+	if (!url) throw new Error(`[untestutils/playwright] missing ${key}`);
+	return normalizeBaseUrl(url);
+}
+export async function usePlaywrightHarnessId(harness, use) {
+	await use(await resolvePlaywrightHarnessId(harness));
+}
+export const test = base.extend({
+	harness: ["", {
+		option: true,
+		scope: "worker"
+	}],
+	harnessId: [async ({ harness }, use) => {
+		await usePlaywrightHarnessId(harness, use);
+	}, { scope: "worker" }],
+	baseURL: async ({ harnessId }, use) => {
+		await use(resolvePlaywrightBaseURL(harnessId));
+	}
+});

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+import { type RecipeRegistry } from "@untestutils/core";
+export interface PlaywrightHarnessOptions {
+	/** Recipe map from `defineRecipes(...)` — import and pass it. */
+	recipes?: RecipeRegistry;
+	/** Override recipes module path; usually inferred from `defineRecipes`. */
+	recipesModule?: string;
+	prewarm?: string[];
+	/**
+	* Absolute or cwd-relative artifacts root. When set, takes precedence over
+	* `session` namespacing.
+	*/
+	artifactsRoot?: string;
+	/**
+	* Isolate TargetRegistry / locks / builds under
+	* `.untestutils/sessions/<session>/` so parallel Playwright runs (or PW +
+	* Vitest) do not tear down each other's servers.
+	*/
+	session?: string;
+	/**
+	* Expand into Playwright `projects` (one per engine) when `projects` is not
+	* already set. Default `['chromium']`.
+	*/
+	browsers?: Array<"chromium" | "firefox" | "webkit">;
+}
+type PWConfig = Record<string, unknown> & {
+	use?: Record<string, unknown>;
+	globalSetup?: string;
+	globalTeardown?: string;
+	workers?: number;
+	fullyParallel?: boolean;
+};
+/** Sanitize session segment for filesystem / env use. */
+export declare function sanitizePlaywrightSession(session: string): string;
+/**
+* Resolve the artifacts root for a Playwright run.
+* Explicit `artifactsRoot` wins; otherwise `session` / `UNTESTUTILS_SESSION`
+* nests under the default `.untestutils` root.
+*/
+export declare function resolvePlaywrightArtifactsRoot(opts?: {
+	artifactsRoot?: string;
+	session?: string;
+	cwd?: string;
+}): string;
+/**
+* Build a Playwright Test config that shares the same recipes.ts as Vitest.
+*
+* Defaults (overridable via rest fields):
+* - `fullyParallel: true`
+* - `workers: 2` when `CI` is set (local runs keep Playwright's CPU default)
+*/
+export declare function createPlaywrightConfig(opts: PlaywrightHarnessOptions & PWConfig): PWConfig;
+export declare function playwrightGlobalSetup(): Promise<void>;
+export declare function playwrightGlobalTeardown(): Promise<void>;
+export { resolvePlaywrightHarnessId, resolvePlaywrightBaseURL, usePlaywrightHarnessId, test } from "./harness.mjs";
+export { expect } from "@playwright/test";
+export { defineRecipes, useHarness } from "@untestutils/core";

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { type RecipeRegistry } from '@untestutils/core';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+export interface PlaywrightHarnessOptions {
+    /** Recipe map from `defineRecipes(...)` — import and pass it. */
+    recipes?: RecipeRegistry;
+    /** Override recipes module path; usually inferred from `defineRecipes`. */
+    recipesModule?: string;
+    prewarm?: string[];
+    /**
+     * Absolute or cwd-relative artifacts root. When set, takes precedence over
+     * `session` namespacing.
+     */
+    artifactsRoot?: string;
+    /**
+     * Isolate TargetRegistry / locks / builds under
+     * `.untestutils/sessions/<session>/` so parallel Playwright runs (or PW +
+     * Vitest) do not tear down each other's servers.
+     */
+    session?: string;
+    /**
+     * Expand into Playwright `projects` (one per engine) when `projects` is not
+     * already set. Default `['chromium']`.
+     */
+    browsers?: Array<'chromium' | 'firefox' | 'webkit'>;
+}
+type PWConfig = Record<string, unknown> & {
+    use?: Record<string, unknown>;
+    globalSetup?: string;
+    globalTeardown?: string;
+    workers?: number;
+    fullyParallel?: boolean;
+};
+/** Sanitize session segment for filesystem / env use. */
+export declare function sanitizePlaywrightSession(session: string): string;
+/**
+ * Resolve the artifacts root for a Playwright run.
+ * Explicit `artifactsRoot` wins; otherwise `session` / `UNTESTUTILS_SESSION`
+ * nests under the default `.untestutils` root.
+ */
+export declare function resolvePlaywrightArtifactsRoot(opts?: {
+    artifactsRoot?: string;
+    session?: string;
+    cwd?: string;
+}): string;
+/**
+ * Build a Playwright Test config that shares the same recipes.ts as Vitest.
+ *
+ * Defaults (overridable via rest fields):
+ * - `fullyParallel: true`
+ * - `workers: 2` when `CI` is set (local runs keep Playwright's CPU default)
+ */
+export declare function createPlaywrightConfig(opts: PlaywrightHarnessOptions & PWConfig): PWConfig;
+/** @internal */
+export declare const playwrightCompanionIo: {
+    createRequire: typeof createRequire;
+    existsSync: typeof existsSync;
+    fileURLToPath: typeof fileURLToPath;
+};
+/** @internal */
+export declare function resolvePlaywrightCompanion(name: 'pw-global-setup' | 'pw-global-teardown'): string;
+export declare function playwrightGlobalSetup(): Promise<void>;
+export declare function playwrightGlobalTeardown(): Promise<void>;
+export { resolvePlaywrightHarnessId, resolvePlaywrightBaseURL, usePlaywrightHarnessId, test, } from './harness';
+export { expect } from '@playwright/test';
+export { defineRecipes, useHarness } from '@untestutils/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAC;CACrD;AAED,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,yDAAyD;AACzD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMjE;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,GAAE;IACJ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACT,GACL,MAAM,CAOR;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,wBAAwB,GAAG,QAAQ,GAAG,QAAQ,CA8C1F;AAMD,gBAAgB;AAChB,eAAO,MAAM,qBAAqB;;;;CAIjC,CAAC;AAEF,gBAAgB;AAChB,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,GAAG,MAAM,CAsBjG;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CA8B3D;AAED,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CAG9D;AAED,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,IAAI,GACL,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,119 @@
+import { ensureRecipes, getRegisteredRecipe, getRecipesModulePath, ensurePrepared, stopAllTargets, resolveArtifactsRoot, progress, TargetRegistry } from "@untestutils/core";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "pathe";
+
+export function sanitizePlaywrightSession(session) {
+	const s = session.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+	if (!s) {
+		throw new Error("[untestutils/playwright] session must be a non-empty identifier");
+	}
+	return s;
+}
+
+export function resolvePlaywrightArtifactsRoot(opts = {}) {
+	const cwd = opts.cwd ?? process.cwd();
+	if (opts.artifactsRoot) return resolve(cwd, opts.artifactsRoot);
+	const base = resolveArtifactsRoot(cwd);
+	const session = opts.session ?? process.env.UNTESTUTILS_SESSION;
+	if (session) return join(base, "sessions", sanitizePlaywrightSession(session));
+	return base;
+}
+
+export function createPlaywrightConfig(opts) {
+	const { recipes, recipesModule, prewarm = [], artifactsRoot, session, browsers: browsersOpt, ...rest } = opts;
+	if (recipes) ensureRecipes(recipes);
+	const resolvedRoot = resolvePlaywrightArtifactsRoot({
+		artifactsRoot,
+		session
+	});
+	process.env.UNTESTUTILS_ARTIFACTS_DIR = resolvedRoot;
+	if (session) process.env.UNTESTUTILS_SESSION = sanitizePlaywrightSession(session);
+	else if (!artifactsRoot) delete process.env.UNTESTUTILS_SESSION;
+	process.env.UNTESTUTILS_PREWARM = JSON.stringify(prewarm);
+	const mod = recipesModule ?? getRecipesModulePath();
+	if (mod) process.env.UNTESTUTILS_RECIPES_MODULE = mod;
+	const browsers = browsersOpt?.length ? browsersOpt : undefined;
+	const defaults = { fullyParallel: true };
+	if (process.env.CI && rest.workers === undefined) {
+		defaults.workers = 2;
+	}
+	
+	if (browsers?.length && rest.projects === undefined) {
+		defaults.projects = browsers.map((browserName) => ({
+			name: browserName,
+			use: { browserName }
+		}));
+	}
+	return {
+		...defaults,
+		...rest,
+		use: { ...rest.use ?? {} },
+		globalSetup: companion("pw-global-setup"),
+		globalTeardown: companion("pw-global-teardown")
+	};
+}
+function companion(name) {
+	return resolvePlaywrightCompanion(name);
+}
+
+export const playwrightCompanionIo = {
+	createRequire,
+	existsSync,
+	fileURLToPath
+};
+
+export function resolvePlaywrightCompanion(name) {
+	const req = playwrightCompanionIo.createRequire(join(process.cwd(), "package.json"));
+	for (const id of [`untestutils/playwright/${name}`, `@untestutils/playwright/${name}`]) {
+		try {
+			return req.resolve(id);
+		} catch {}
+	}
+	try {
+		const pkgRoot = dirname(req.resolve("@untestutils/playwright/package.json"));
+		const mjs = join(pkgRoot, "dist", `${name}.mjs`);
+		if (playwrightCompanionIo.existsSync(mjs)) return mjs;
+		const ts = join(pkgRoot, "src", `${name}.ts`);
+		if (playwrightCompanionIo.existsSync(ts)) return ts;
+	} catch {}
+	const here = dirname(playwrightCompanionIo.fileURLToPath(import.meta.url));
+	const localTs = join(here, `${name}.ts`);
+	if (playwrightCompanionIo.existsSync(localTs)) return localTs;
+	throw new Error(`[untestutils/playwright] missing ${name}`);
+}
+export async function playwrightGlobalSetup() {
+	const modPath = process.env.UNTESTUTILS_RECIPES_MODULE;
+	let recipesFromModule;
+	if (modPath) {
+		const { pathToFileURL } = await import("node:url");
+		const loaded = await import(pathToFileURL(modPath).href);
+		recipesFromModule = loaded.recipes;
+	}
+	const artifactsRoot = resolveArtifactsRoot();
+	await stopAllTargets(artifactsRoot);
+	const registry = new TargetRegistry(artifactsRoot);
+	const prewarm = JSON.parse(process.env.UNTESTUTILS_PREWARM || "[]");
+	if (prewarm.length) {
+		progress.waveStart(prewarm);
+		for (const id of prewarm) {
+			const recipe = recipesFromModule?.[id] ?? getRegisteredRecipe(id);
+			if (!recipe) {
+				throw new Error(`[untestutils/playwright] prewarm "${id}" missing — import recipes via defineRecipes(..., import.meta.url)`);
+			}
+			await ensurePrepared(recipe, { artifactsRoot });
+		}
+		progress.waveReady();
+		progress.massRun();
+	}
+	
+	registry.applyAllToEnv(await registry.read());
+}
+export async function playwrightGlobalTeardown() {
+	progress.teardown();
+	await stopAllTargets(resolveArtifactsRoot());
+}
+export { resolvePlaywrightHarnessId, resolvePlaywrightBaseURL, usePlaywrightHarnessId, test } from "./harness.mjs";
+export { expect } from "@playwright/test";
+export { defineRecipes, useHarness } from "@untestutils/core";

package/dist/pw-global-setup.d.mts

@@ -0,0 +1 @@
+export { playwrightGlobalSetup as default } from "./index.mjs";

package/dist/pw-global-setup.d.ts

@@ -0,0 +1,2 @@
+export { playwrightGlobalSetup as default } from './index';
+//# sourceMappingURL=pw-global-setup.d.ts.map

package/dist/pw-global-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pw-global-setup.d.ts","sourceRoot":"","sources":["../src/pw-global-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,IAAI,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/pw-global-setup.mjs

@@ -0,0 +1 @@
+export { playwrightGlobalSetup as default } from "./index.mjs";

package/dist/pw-global-teardown.d.mts

@@ -0,0 +1 @@
+export { playwrightGlobalTeardown as default } from "./index.mjs";

package/dist/pw-global-teardown.d.ts

@@ -0,0 +1,2 @@
+export { playwrightGlobalTeardown as default } from './index';
+//# sourceMappingURL=pw-global-teardown.d.ts.map

package/dist/pw-global-teardown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pw-global-teardown.d.ts","sourceRoot":"","sources":["../src/pw-global-teardown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,IAAI,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/pw-global-teardown.mjs

@@ -0,0 +1 @@
+export { playwrightGlobalTeardown as default } from "./index.mjs";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@untestutils/playwright",
+  "version": "0.5.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./pw-global-setup": {
+      "types": "./dist/pw-global-setup.d.ts",
+      "import": "./dist/pw-global-setup.mjs",
+      "default": "./dist/pw-global-setup.mjs"
+    },
+    "./pw-global-teardown": {
+      "types": "./dist/pw-global-teardown.d.ts",
+      "import": "./dist/pw-global-teardown.mjs",
+      "default": "./dist/pw-global-teardown.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "pathe": "^2.0.3",
+    "@untestutils/core": "0.5.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@types/node": "^26.6.1",
+    "publint": "^0.3.24",
+    "typescript": "^6.0.3",
+    "obuild": "^0.4.40"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.63.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://s00d.github.io/untestutils/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/s00d/untestutils.git",
+    "directory": "packages/playwright"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "obuild && tsc -p tsconfig.build.json",
+    "publint": "publint --strict"
+  }
+}