@cronn/playwright-utils 0.7.0 → 0.9.0

package/dist/index.d.mts

@@ -591,6 +591,33 @@ export declare class RouteInterceptorFixture {
   intercept(filter: RouteFilter): RouteInterceptor;
 }
 //#endregion
+//#region src/security/csp-report.d.ts
+/**
+ * Returns the `Content-Security-Policy` header of a response, or an empty
+ * string if the response or the header is missing.
+ */
+export declare function getCspHeader(response: Response | null): Promise<string>;
+/**
+ * Evaluates a `Content-Security-Policy` header against a set of recommended
+ * directives and returns the result as a Markdown report.
+ *
+ * The report lists all directives of the header, followed by recommendations
+ * for missing or weak directives. Missing fetch directives are evaluated using
+ * `default-src`, just like the browser falls back to it. Nonces are masked as
+ * `[NONCE_0]`, `[NONCE_1]`, … to keep the report deterministic for file snapshots.
+ *
+ * @example
+ * ```ts
+ * const response = await page.goto("/");
+ * const cspHeader = await getCspHeader(response);
+ *
+ * expect(cspReport(cspHeader)).toMatchTextFile({
+ *   fileExtension: "md",
+ * });
+ * ```
+ */
+export declare function cspReport(header: string): string;
+//#endregion
 //#region src/file.d.ts
 /**
  * Resolves the given path segments against the root directory of the closest
@@ -606,7 +633,64 @@ export declare class RouteInterceptorFixture {
  */
 export declare function resolveFromPackageRoot(...paths: Array<string>): string;
 //#endregion
-//#region src/page-object-model/locator-extensions.d.ts
+//#region src/page-object-model/form-filler.d.ts
+interface Fillable<TValue> {
+  fill: Filler<TValue>;
+}
+type Filler<TValue> = (value: TValue) => Promise<void>;
+type FormFields<TData> = { [K in keyof TData]-?: Fillable<Exclude<TData[K], undefined>> | Filler<Exclude<TData[K], undefined>>; };
+/**
+ * Creates a filler function that fills a form declaratively from a data
+ * object, e.g. as the `fill` method of a page object.
+ *
+ * Each key of `fields` maps a key of the data to a form input: either an
+ * object with a `fill` method (such as a `Locator` or a nested page object) or
+ * a filler function receiving the value. Fields are filled one after another
+ * in the order of the keys in `fields`, and fields whose value is `undefined`
+ * are skipped.
+ *
+ * The type of the data is either given explicitly as type argument or inferred
+ * from `fields`. When inferred, filler functions need an explicit parameter
+ * type, otherwise their value is `unknown`. In both cases, the returned
+ * function accepts partial data.
+ *
+ * As the returned function is a filler itself, it can be used as a field of
+ * another form filler to fill nested data.
+ *
+ * @param fields - Mapping from each key of the data to the input to fill
+ * @returns A function filling the form with the given data
+ * @example
+ * ```ts
+ * const { checkbox, textbox } = roleLocators(page);
+ *
+ * const registrationForm = {
+ *   fill: formFiller<Registration>({
+ *     name: textbox("Name"),
+ *     acceptTerms: (accepted) => checkbox("Accept terms").setChecked(accepted),
+ *   }),
+ * };
+ * ```
+ */
+export declare function formFiller<TData extends object>(fields: FormFields<TData>): Filler<Partial<TData>>;
+//#endregion
+//#region src/page-object-model/extend-locator.d.ts
+type WithoutLocatorKeys = Partial<Record<Exclude<keyof Locator, "toString">, never>>;
+type ExtendedLocator<TExtensions extends WithoutLocatorKeys> = Locator & TExtensions;
+/**
+ * Extends a `Locator` with custom properties and functions while retaining the full `Locator` API.
+ *
+ * Extensions must not override members of `Locator`. Locators derived from the extended locator
+ * (e.g. via `first()`, `filter()` or `locator()`) are plain `Locator`s without the extensions.
+ *
+ * Methods of `Locator` are bound to the original locator on every access, so accessing the same method
+ * twice returns different function instances (e.g. `extended.click !== extended.click`).
+ *
+ * @param locator The locator to extend
+ * @param createExtensions Creates the extensions, receiving the original locator
+ */
+export declare function extendLocator<TExtensions extends object & WithoutLocatorKeys>(locator: Locator, createExtensions: (locator: Locator) => TExtensions): ExtendedLocator<TExtensions>;
+//#endregion
+//#region src/page-object-model/role-locators.d.ts
 type RoleLocators = Record<Role, RoleLocator>;
 interface RoleLocator {
   (options?: RoleLocatorOptions): Locator;
@@ -673,4 +757,4 @@ export declare function maskedValueWithIndex(name: string): (index: number) => s
  */
 type PlaywrightTarget = Page | Locator;
 //#endregion
-export type { ConsoleMessageFilter, ConsoleMessageLevel, CspFixtures, CspViolation, HttpMethod, PlaywrightTarget, ResponseHandler, RoleLocators, RouteFilter };
+export type { ConsoleMessageFilter, ConsoleMessageLevel, CspFixtures, CspViolation, ExtendedLocator, FormFields, HttpMethod, PlaywrightTarget, ResponseHandler, RoleLocators, RouteFilter };

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { expect } from "@playwright/test";
+import { markdownTable } from "markdown-table";
 import path from "node:path";
 import { packageDirectorySync } from "package-directory";
 import { maskString, stringNormalizer } from "@cronn/playwright-file-snapshots";
@@ -770,6 +771,225 @@ function modifyTextBody(modifier) {
 	});
 }
 //#endregion
+//#region src/normalizers/masked-value.ts
+/**
+* Formats a name as a masked placeholder, e.g. `maskedValue("base url")`
+* returns `[BASE_URL]`.
+*
+* @param name - Name of the masked value
+*/
+function maskedValue(name) {
+	return `[${name.toUpperCase().replace(/[ -.:,;]/g, "_")}]`;
+}
+/**
+* Creates a factory for indexed masked placeholders, e.g. `[USER_1]`.
+*
+* @param name - Name of the masked value
+* @returns A function mapping an index to a masked placeholder
+*/
+function maskedValueWithIndex(name) {
+	return (index) => maskedValue(`${name}_${index}`);
+}
+//#endregion
+//#region src/security/csp-report.ts
+const RECOMMENDED_DIRECTIVES = [
+	{ name: "upgrade-insecure-requests" },
+	{ name: "trusted-types" },
+	{
+		name: "require-trusted-types-for",
+		values: ["'script'"]
+	},
+	{
+		name: "default-src",
+		values: ["'self'"]
+	},
+	{
+		name: "script-src",
+		requireNonce: true,
+		tolerated: ["'strict-dynamic'"],
+		fallback: "default-src",
+		optional: ["script-src-elem", "script-src-attr"]
+	},
+	{
+		name: "script-src-elem",
+		requireNonce: true,
+		tolerated: ["'strict-dynamic'"],
+		optional: true
+	},
+	{
+		name: "script-src-attr",
+		values: ["'none'"],
+		optional: true
+	},
+	{
+		name: "style-src",
+		requireNonce: true,
+		fallback: "default-src",
+		optional: ["style-src-elem", "style-src-attr"]
+	},
+	{
+		name: "style-src-elem",
+		requireNonce: true,
+		optional: true
+	},
+	{
+		name: "style-src-attr",
+		values: ["'none'"],
+		optional: true
+	},
+	{
+		name: "img-src",
+		values: ["'self'", "data:"],
+		fallback: "default-src"
+	},
+	{
+		name: "font-src",
+		values: ["'self'"],
+		fallback: "default-src"
+	},
+	{
+		name: "connect-src",
+		values: ["'self'"],
+		fallback: "default-src"
+	},
+	{
+		name: "object-src",
+		values: ["'none'"]
+	},
+	{
+		name: "base-uri",
+		values: ["'self'"]
+	},
+	{
+		name: "form-action",
+		values: ["'self'"]
+	},
+	{
+		name: "frame-ancestors",
+		values: ["'none'"]
+	}
+];
+const NONCE_PLACEHOLDER = "'nonce-[RANDOM]'";
+const MASKED_NONCE = maskedValueWithIndex("NONCE");
+/**
+* Returns the `Content-Security-Policy` header of a response, or an empty
+* string if the response or the header is missing.
+*/
+async function getCspHeader(response) {
+	return await response?.headerValue("content-security-policy") ?? "";
+}
+/**
+* Evaluates a `Content-Security-Policy` header against a set of recommended
+* directives and returns the result as a Markdown report.
+*
+* The report lists all directives of the header, followed by recommendations
+* for missing or weak directives. Missing fetch directives are evaluated using
+* `default-src`, just like the browser falls back to it. Nonces are masked as
+* `[NONCE_0]`, `[NONCE_1]`, … to keep the report deterministic for file snapshots.
+*
+* @example
+* ```ts
+* const response = await page.goto("/");
+* const cspHeader = await getCspHeader(response);
+*
+* expect(cspReport(cspHeader)).toMatchTextFile({
+*   fileExtension: "md",
+* });
+* ```
+*/
+function cspReport(header) {
+	const { directives, recommendations } = evaluateCsp(parseCsp(header));
+	return [
+		"# CSP Report",
+		"## Detected Directives",
+		directives.length === 0 ? "None" : markdownTable([["Directive", "Value"], ...maskNonces(directives).map((directive) => [code(directive.name), formatValues(directive.values)])]),
+		"## Recommendations",
+		recommendations.length === 0 ? "None" : recommendations.map((recommendation) => `- ${code(recommendation.directive)}: ${recommendation.message}`).join("\n")
+	].join("\n\n").concat("\n");
+}
+function parseCsp(header) {
+	return header.split(";").map((directive) => directive.trim()).filter((directive) => directive !== "").map((directive) => {
+		const [name = "", ...values] = directive.split(/\s+/);
+		return {
+			name: name.toLowerCase(),
+			values
+		};
+	});
+}
+function evaluateCsp(directives) {
+	const directivesByName = /* @__PURE__ */ new Map();
+	for (const directive of directives) if (!directivesByName.has(directive.name)) directivesByName.set(directive.name, directive);
+	return {
+		directives,
+		recommendations: RECOMMENDED_DIRECTIVES.flatMap((recommended) => evaluateDirective(recommended, directivesByName).map((message) => ({
+			directive: recommended.name,
+			message
+		})))
+	};
+}
+function evaluateDirective(recommended, directivesByName) {
+	const directive = directivesByName.get(recommended.name);
+	if (directive === void 0 && isOptional(recommended, directivesByName)) return [];
+	const fallback = recommended.fallback !== void 0 ? directivesByName.get(recommended.fallback) : void 0;
+	const actual = directive ?? fallback;
+	if (actual === void 0) return [`Missing, add ${code([recommended.name, ...formatRecommendedValues(recommended)].join(" "))}`];
+	const inherited = directive === void 0 ? ` (inherited from ${code(actual.name)})` : "";
+	const messages = [];
+	const recommendedValues = recommended.values;
+	const extraValues = findExtraValues(recommended, actual.values);
+	const hasRecommendedValue = extraValues.length < actual.values.length;
+	if (recommendedValues !== void 0 && extraValues.length > 0 && !hasRecommendedValue) messages.push(`Add ${formatValues(recommendedValues)}`);
+	if (recommended.requireNonce === true && !actual.values.some(isNonce)) messages.push(`Add a nonce source`);
+	for (const value of extraValues) messages.push(`Remove ${code(value)}${inherited}`);
+	return messages;
+}
+function isOptional(recommended, directivesByName) {
+	if (Array.isArray(recommended.optional)) return recommended.optional.every((name) => directivesByName.has(name));
+	return recommended.optional === true;
+}
+/**
+* Returns all sources which are neither recommended nor tolerated. Directives
+* without recommended sources accept any value, and `'none'` is always
+* accepted as it is stricter than any recommendation.
+*/
+function findExtraValues(recommended, values) {
+	if (recommended.values === void 0 && recommended.requireNonce !== true || isNone(values)) return [];
+	const acceptedValues = [...recommended.values ?? [], ...recommended.tolerated ?? []];
+	return values.filter((value) => !acceptedValues.includes(value) && !(recommended.requireNonce === true && isNonce(value)));
+}
+function formatRecommendedValues(recommended) {
+	return [...recommended.requireNonce === true ? [NONCE_PLACEHOLDER] : [], ...recommended.values ?? []];
+}
+function maskNonces(directives) {
+	const nonceIndices = /* @__PURE__ */ new Map();
+	function maskNonce(value) {
+		if (!isNonce(value)) return value;
+		let index = nonceIndices.get(value);
+		if (index === void 0) {
+			index = nonceIndices.size;
+			nonceIndices.set(value, index);
+		}
+		return `'nonce-${MASKED_NONCE(index)}'`;
+	}
+	return directives.map((directive) => ({
+		...directive,
+		values: directive.values.map(maskNonce)
+	}));
+}
+function isNone(values) {
+	return values.length === 1 && values[0] === "'none'";
+}
+function isNonce(value) {
+	return value.startsWith("'nonce-");
+}
+function formatValues(values) {
+	if (values.length === 0) return "_none_";
+	return code(values.join(" "));
+}
+function code(text) {
+	return `\`${text.replaceAll("|", "\\|")}\``;
+}
+//#endregion
 //#region src/file.ts
 /**
 * Resolves the given path segments against the root directory of the closest
@@ -789,7 +1009,81 @@ function resolveFromPackageRoot(...paths) {
 	return path.resolve(packageDir, ...paths);
 }
 //#endregion
-//#region src/page-object-model/locator-extensions.ts
+//#region src/page-object-model/form-filler.ts
+/**
+* Creates a filler function that fills a form declaratively from a data
+* object, e.g. as the `fill` method of a page object.
+*
+* Each key of `fields` maps a key of the data to a form input: either an
+* object with a `fill` method (such as a `Locator` or a nested page object) or
+* a filler function receiving the value. Fields are filled one after another
+* in the order of the keys in `fields`, and fields whose value is `undefined`
+* are skipped.
+*
+* The type of the data is either given explicitly as type argument or inferred
+* from `fields`. When inferred, filler functions need an explicit parameter
+* type, otherwise their value is `unknown`. In both cases, the returned
+* function accepts partial data.
+*
+* As the returned function is a filler itself, it can be used as a field of
+* another form filler to fill nested data.
+*
+* @param fields - Mapping from each key of the data to the input to fill
+* @returns A function filling the form with the given data
+* @example
+* ```ts
+* const { checkbox, textbox } = roleLocators(page);
+*
+* const registrationForm = {
+*   fill: formFiller<Registration>({
+*     name: textbox("Name"),
+*     acceptTerms: (accepted) => checkbox("Accept terms").setChecked(accepted),
+*   }),
+* };
+* ```
+*/
+function formFiller(fields) {
+	return async (data) => {
+		for (const [key, filler] of Object.entries(fields)) {
+			const value = data[key];
+			if (value === void 0) continue;
+			if (typeof filler === "function") await filler(value);
+			else await filler.fill(value);
+		}
+	};
+}
+//#endregion
+//#region src/page-object-model/extend-locator.ts
+/**
+* Extends a `Locator` with custom properties and functions while retaining the full `Locator` API.
+*
+* Extensions must not override members of `Locator`. Locators derived from the extended locator
+* (e.g. via `first()`, `filter()` or `locator()`) are plain `Locator`s without the extensions.
+*
+* Methods of `Locator` are bound to the original locator on every access, so accessing the same method
+* twice returns different function instances (e.g. `extended.click !== extended.click`).
+*
+* @param locator The locator to extend
+* @param createExtensions Creates the extensions, receiving the original locator
+*/
+function extendLocator(locator, createExtensions) {
+	const extensions = createExtensions(locator);
+	return new Proxy(locator, {
+		get(target, property) {
+			if (isOwnKeyOf(extensions, property)) return extensions[property];
+			const value = Reflect.get(target, property, target);
+			return typeof value === "function" && property !== "constructor" ? value.bind(target) : value;
+		},
+		has(target, property) {
+			return isOwnKeyOf(extensions, property) || Reflect.has(target, property);
+		}
+	});
+}
+function isOwnKeyOf(object, key) {
+	return Object.hasOwn(object, key);
+}
+//#endregion
+//#region src/page-object-model/role-locators.ts
 const ROLES = [
 	"alert",
 	"alertdialog",
@@ -916,26 +1210,6 @@ function roleLocators(locator, defaultOptions = DEFAULT_OPTIONS) {
 	return Object.fromEntries(ROLES.map((role) => [role, getByRole(role)]));
 }
 //#endregion
-//#region src/normalizers/masked-value.ts
-/**
-* Formats a name as a masked placeholder, e.g. `maskedValue("base url")`
-* returns `[BASE_URL]`.
-*
-* @param name - Name of the masked value
-*/
-function maskedValue(name) {
-	return `[${name.toUpperCase().replace(/[ -.:,;]/g, "_")}]`;
-}
-/**
-* Creates a factory for indexed masked placeholders, e.g. `[USER_1]`.
-*
-* @param name - Name of the masked value
-* @returns A function mapping an index to a masked placeholder
-*/
-function maskedValueWithIndex(name) {
-	return (index) => maskedValue(`${name}_${index}`);
-}
-//#endregion
 //#region src/normalizers/mask-base-url.ts
 /**
 * Creates a normalizer that replaces occurrences of the base URL with
@@ -951,4 +1225,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { ConsoleCaptor, CspCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, captureCspViolations, createFetchAdapter, cspFixtures, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, roleLocators };
+export { ConsoleCaptor, CspCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, captureCspViolations, createFetchAdapter, cspFixtures, cspReport, extendLocator, formFiller, getCspHeader, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, roleLocators };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/playwright-utils",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",
@@ -29,33 +29,34 @@
     }
   },
   "dependencies": {
+    "markdown-table": "^3.0.4",
     "package-directory": "^8.2.0"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
-    "@changesets/cli": "3.0.2",
-    "@cronn/element-snapshot": "0.30.0",
+    "@changesets/cli": "3.0.3",
+    "@cronn/element-snapshot": "0.32.1",
     "@cronn/playwright-file-snapshots": "2.2.2",
     "@playwright/test": "1.63.0",
-    "@types/node": "24.13.4",
+    "@types/node": "24.19.1",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "5.0.0",
-    "eslint": "10.10.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "eslint": "10.12.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.2",
     "eslint-plugin-unused-imports": "4.4.1",
-    "knip": "6.35.1",
-    "oxc-minify": "0.149.0",
-    "oxfmt": "0.67.0",
-    "publint": "0.3.24",
+    "knip": "6.39.0",
+    "oxc-minify": "0.153.0",
+    "oxfmt": "0.72.0",
+    "publint": "0.3.25",
     "rimraf": "6.1.3",
     "tsdown": "0.23.0",
-    "turbo": "2.10.12",
+    "turbo": "2.11.7",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "8.70.0",
+    "typescript-eslint": "8.71.1",
     "vitepress": "2.0.0-alpha.20",
     "vitepress-plugin-group-icons": "1.7.6",
-    "vitest": "5.0.0"
+    "vitest": "5.0.3"
   },
   "peerDependencies": {
     "@cronn/playwright-file-snapshots": "^2",
@@ -64,7 +65,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.5.1",
+      "version": "12.11.2",
       "onFail": "download"
     },
     "runtime": {
@@ -90,9 +91,7 @@
     "lint:check": "eslint . --max-warnings=0",
     "lint:fix": "eslint . --max-warnings=0 --fix",
     "playwright:install": "playwright install chromium",
-    "pnpm:check": "pnpm dedupe --check",
     "pnpm:clean": "pnpm pm clean && pnpm store prune",
-    "pnpm:fix": "pnpm dedupe",
     "release": "pnpm turbo run build && pnpm changeset publish",
     "test:integration": "playwright test",
     "test:unit": "vitest run",