@cronn/playwright-utils 0.6.0 → 0.8.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
+import { APIRequestContext, APIResponse, ConsoleMessage, Fixtures, Locator, Page, PlaywrightTestArgs, PlaywrightTestOptions, Request, Response, Route } from "@playwright/test";
 import { Normalizer } from "@cronn/playwright-file-snapshots";
-import { APIRequestContext, APIResponse, ConsoleMessage, Locator, Page, Request, Response, Route } from "@playwright/test";
 //#region src/environment.d.ts
 /**
  * Whether the current process runs in a CI environment, based on the `CI`
@@ -166,9 +166,6 @@ export declare class ConsoleCaptor {
  * @example
  * ```ts
  * const errorCaptor = captureConsole(page, "error");
- * const cspCaptor = captureConsole(page, message =>
- *     hasLogLevel(message, "warning", "error") && message.text().includes("Content Security Policy")
- * );
  * ```
  */
 export declare function captureConsole(page: Page, levelOrFilter?: ConsoleMessageLevel | Array<ConsoleMessageLevel> | ConsoleMessageFilter): ConsoleCaptor;
@@ -183,6 +180,153 @@ export declare function captureConsole(page: Page, levelOrFilter?: ConsoleMessag
  */
 export declare function hasLogLevel(message: ConsoleMessage, ...level: Array<ConsoleMessageLevel>): boolean;
 //#endregion
+//#region src/capturing/csp-captor.d.ts
+/**
+ * A Content Security Policy violation, as reported by the browser's
+ * [`securitypolicyviolation`](https://developer.mozilla.org/en-US/docs/Web/API/Document/securitypolicyviolation_event) event.
+ */
+type CspViolation = SecurityPolicyViolationEventInit;
+/**
+ * Collects the Content Security Policy violations of a page.
+ *
+ * Browsers report CSP violations through the `securitypolicyviolation` DOM event,
+ * which is not otherwise exposed by Playwright. A captor registers a listener for
+ * this event on every document of the page and collects the reported violations,
+ * and can limit the capturing to a single action.
+ *
+ * Several captors can run on the same page at the same time, and every captor
+ * receives all violations independently.
+ *
+ * @example
+ * ```ts
+ * const violations = captureCspViolations(page);
+ *
+ * await violations.during(() => page.goto("/users"));
+ *
+ * expect(violations.violations).toEqual([]);
+ * ```
+ */
+export declare class CspCaptor {
+  private readonly page;
+  private readonly bindingName;
+  private initialized;
+  private capturing;
+  /**
+   * The captured violations, in the order in which the page reported them.
+   *
+   * The array is filled while the captor is running, so it can also be
+   * inspected inside the action passed to {@link during}.
+   */
+  readonly violations: Array<CspViolation>;
+  /**
+   * Create a captor for the CSP violations of a page.
+   *
+   * The captor does not collect anything until it is started, either by
+   * {@link startCapture} or by {@link during}.
+   *
+   * @param page - The page to capture CSP violations of
+   */
+  constructor(page: Page);
+  private ensureInitialized;
+  /**
+   * Start collecting the CSP violations of the page.
+   *
+   * A captor can be started and stopped repeatedly; the collected violations are
+   * kept across restarts.
+   *
+   * Because violations are captured through an init script, {@link startCapture}
+   * has to be called before the page navigates for violations of the initial
+   * load to be captured.
+   */
+  startCapture(): Promise<void>;
+  /**
+   * Stop collecting the CSP violations of the page.
+   *
+   * The already captured {@link violations} are kept.
+   */
+  stopCapture(): void;
+  /**
+   * Remove all captured {@link violations}.
+   */
+  clearViolations(): void;
+  /**
+   * Collect the CSP violations reported while the callback runs.
+   *
+   * The capturing is stopped once the action has finished, even if it throws.
+   * A promise returned by the action is awaited before the captor stops, no
+   * matter when it is awaited by the caller.
+   *
+   * @param action - The action to capture CSP violations during
+   * @returns The value of the action
+   *
+   * @example
+   * ```ts
+   * const captor = captureCspViolations(page);
+   *
+   * await captor.during(() => page.goto("/users"));
+   *
+   * expect(captor.violations).toEqual([]);
+   * ```
+   */
+  during<T>(action: () => Promise<T>): Promise<T>;
+}
+/**
+ * Factory method to create a {@link CspCaptor}.
+ *
+ * @param page - The page to capture CSP violations for
+ * @returns CspCaptor
+ *
+ * @example
+ * ```ts
+ * const captor = captureCspViolations(page);
+ * ```
+ */
+export declare function captureCspViolations(page: Page): CspCaptor;
+interface CspFixtures {
+  /**
+   * A {@link CspCaptor} capturing every CSP violation of the page, available for
+   * tests that want to trigger and assert on a specific violation.
+   */
+  cspCaptor: CspCaptor;
+  /**
+   * Option fixture controlling whether {@link cspFixtures} skips failing
+   * a test that produced unexpected CSP violations.
+   *
+   * @default false
+   */
+  ignoreCspViolations: boolean;
+}
+/**
+ * Playwright fixtures reporting Content Security Policy violations for every test.
+ *
+ * `cspCaptor` is installed automatically on the page fixture and, by default, fails
+ * a test if it produced any CSP violation. Disable this for an individual test with
+ * `test.use({ ignoreCspViolations: true })`, and inspect `cspCaptor.violations`
+ * manually for tests targeting CSP behavior specifically.
+ *
+ * @example
+ * ```ts
+ * import { cspFixtures, type CspFixtures } from "@cronn/playwright-utils";
+ * import { test as base } from "@playwright/test";
+ *
+ * export const test = base.extend<CspFixtures>({
+ *   ...cspFixtures,
+ *   // ...other fixtures
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * test.use({ ignoreCspViolations: true });
+ *
+ * test("shows a warning banner on CSP violation", async ({ page, cspCaptor }) => {
+ *   await page.getByRole("button", { name: "Load untrusted script" }).click();
+ *   expect(cspCaptor.violations).toHaveLength(1);
+ * });
+ * ```
+ */
+export declare const cspFixtures: Fixtures<CspFixtures, object, PlaywrightTestArgs & PlaywrightTestOptions>;
+//#endregion
 //#region src/api/route-interceptor/filter.d.ts
 /**
  * HTTP Methods used by {@link RouteFilter}
@@ -462,7 +606,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;
@@ -529,4 +730,4 @@ export declare function maskedValueWithIndex(name: string): (index: number) => s
  */
 type PlaywrightTarget = Page | Locator;
 //#endregion
-export type { ConsoleMessageFilter, ConsoleMessageLevel, HttpMethod, PlaywrightTarget, ResponseHandler, RoleLocators, RouteFilter };
+export type { ConsoleMessageFilter, ConsoleMessageLevel, CspFixtures, CspViolation, ExtendedLocator, FormFields, HttpMethod, PlaywrightTarget, ResponseHandler, RoleLocators, RouteFilter };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { expect } from "@playwright/test";
 import path from "node:path";
 import { packageDirectorySync } from "package-directory";
 import { maskString, stringNormalizer } from "@cronn/playwright-file-snapshots";
@@ -210,9 +211,6 @@ var ConsoleCaptor = class {
 * @example
 * ```ts
 * const errorCaptor = captureConsole(page, "error");
-* const cspCaptor = captureConsole(page, message =>
-*     hasLogLevel(message, "warning", "error") && message.text().includes("Content Security Policy")
-* );
 * ```
 */
 function captureConsole(page, levelOrFilter) {
@@ -234,6 +232,188 @@ function hasLogLevel(message, ...level) {
 	return level.includes(message.type());
 }
 //#endregion
+//#region src/capturing/csp-captor.ts
+let nextBindingId = 0;
+/**
+* Collects the Content Security Policy violations of a page.
+*
+* Browsers report CSP violations through the `securitypolicyviolation` DOM event,
+* which is not otherwise exposed by Playwright. A captor registers a listener for
+* this event on every document of the page and collects the reported violations,
+* and can limit the capturing to a single action.
+*
+* Several captors can run on the same page at the same time, and every captor
+* receives all violations independently.
+*
+* @example
+* ```ts
+* const violations = captureCspViolations(page);
+*
+* await violations.during(() => page.goto("/users"));
+*
+* expect(violations.violations).toEqual([]);
+* ```
+*/
+var CspCaptor = class {
+	page;
+	bindingName = `__playwrightUtilsCspCaptor${nextBindingId++}__`;
+	initialized = false;
+	capturing = false;
+	/**
+	* The captured violations, in the order in which the page reported them.
+	*
+	* The array is filled while the captor is running, so it can also be
+	* inspected inside the action passed to {@link during}.
+	*/
+	violations = [];
+	/**
+	* Create a captor for the CSP violations of a page.
+	*
+	* The captor does not collect anything until it is started, either by
+	* {@link startCapture} or by {@link during}.
+	*
+	* @param page - The page to capture CSP violations of
+	*/
+	constructor(page) {
+		this.page = page;
+	}
+	async ensureInitialized() {
+		if (this.initialized) return;
+		this.initialized = true;
+		await this.page.exposeFunction(this.bindingName, (violation) => {
+			if (this.capturing) this.violations.push(violation);
+		});
+		await this.page.addInitScript((bindingName) => {
+			document.addEventListener("securitypolicyviolation", (event) => {
+				const report = window[bindingName];
+				report({
+					blockedURI: event.blockedURI,
+					disposition: event.disposition,
+					documentURI: event.documentURI,
+					effectiveDirective: event.effectiveDirective,
+					lineNumber: event.lineNumber,
+					columnNumber: event.columnNumber,
+					originalPolicy: event.originalPolicy,
+					referrer: event.referrer,
+					sample: event.sample,
+					sourceFile: event.sourceFile,
+					statusCode: event.statusCode,
+					violatedDirective: event.violatedDirective
+				});
+			});
+		}, this.bindingName);
+	}
+	/**
+	* Start collecting the CSP violations of the page.
+	*
+	* A captor can be started and stopped repeatedly; the collected violations are
+	* kept across restarts.
+	*
+	* Because violations are captured through an init script, {@link startCapture}
+	* has to be called before the page navigates for violations of the initial
+	* load to be captured.
+	*/
+	async startCapture() {
+		await this.ensureInitialized();
+		this.capturing = true;
+	}
+	/**
+	* Stop collecting the CSP violations of the page.
+	*
+	* The already captured {@link violations} are kept.
+	*/
+	stopCapture() {
+		this.capturing = false;
+	}
+	/**
+	* Remove all captured {@link violations}.
+	*/
+	clearViolations() {
+		this.violations.length = 0;
+	}
+	/**
+	* Collect the CSP violations reported while the callback runs.
+	*
+	* The capturing is stopped once the action has finished, even if it throws.
+	* A promise returned by the action is awaited before the captor stops, no
+	* matter when it is awaited by the caller.
+	*
+	* @param action - The action to capture CSP violations during
+	* @returns The value of the action
+	*
+	* @example
+	* ```ts
+	* const captor = captureCspViolations(page);
+	*
+	* await captor.during(() => page.goto("/users"));
+	*
+	* expect(captor.violations).toEqual([]);
+	* ```
+	*/
+	async during(action) {
+		await this.startCapture();
+		try {
+			return await action();
+		} finally {
+			this.stopCapture();
+		}
+	}
+};
+/**
+* Factory method to create a {@link CspCaptor}.
+*
+* @param page - The page to capture CSP violations for
+* @returns CspCaptor
+*
+* @example
+* ```ts
+* const captor = captureCspViolations(page);
+* ```
+*/
+function captureCspViolations(page) {
+	return new CspCaptor(page);
+}
+async function provideCspCaptor({ page, ignoreCspViolations }, use) {
+	const captor = captureCspViolations(page);
+	await captor.startCapture();
+	await use(captor);
+	captor.stopCapture();
+	if (!ignoreCspViolations) expect(captor.violations, "Unexpected CSP violations").toEqual([]);
+}
+/**
+* Playwright fixtures reporting Content Security Policy violations for every test.
+*
+* `cspCaptor` is installed automatically on the page fixture and, by default, fails
+* a test if it produced any CSP violation. Disable this for an individual test with
+* `test.use({ ignoreCspViolations: true })`, and inspect `cspCaptor.violations`
+* manually for tests targeting CSP behavior specifically.
+*
+* @example
+* ```ts
+* import { cspFixtures, type CspFixtures } from "@cronn/playwright-utils";
+* import { test as base } from "@playwright/test";
+*
+* export const test = base.extend<CspFixtures>({
+*   ...cspFixtures,
+*   // ...other fixtures
+* });
+* ```
+*
+* @example
+* ```ts
+* test.use({ ignoreCspViolations: true });
+*
+* test("shows a warning banner on CSP violation", async ({ page, cspCaptor }) => {
+*   await page.getByRole("button", { name: "Load untrusted script" }).click();
+*   expect(cspCaptor.violations).toHaveLength(1);
+* });
+* ```
+*/
+const cspFixtures = {
+	ignoreCspViolations: [false, { option: true }],
+	cspCaptor: [provideCspCaptor, { auto: true }]
+};
+//#endregion
 //#region src/api/route-interceptor/interceptor.ts
 function isFiltered(filter, request) {
 	if (!filter.url(new URL(request.url()))) return false;
@@ -609,7 +789,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",
@@ -771,4 +1025,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { ConsoleCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, createFetchAdapter, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, roleLocators };
+export { ConsoleCaptor, CspCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, captureCspViolations, createFetchAdapter, cspFixtures, extendLocator, formFiller, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, roleLocators };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/playwright-utils",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",
@@ -33,29 +33,29 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
-    "@changesets/cli": "3.0.2",
+    "@changesets/cli": "3.0.3",
     "@cronn/element-snapshot": "0.30.0",
     "@cronn/playwright-file-snapshots": "2.2.2",
     "@playwright/test": "1.63.0",
-    "@types/node": "24.13.4",
+    "@types/node": "24.19.0",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "5.0.0",
-    "eslint": "10.10.0",
+    "@vitest/coverage-v8": "5.0.2",
+    "eslint": "10.11.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",
+    "knip": "6.38.0",
+    "oxc-minify": "0.151.0",
+    "oxfmt": "0.70.0",
     "publint": "0.3.24",
     "rimraf": "6.1.3",
     "tsdown": "0.23.0",
-    "turbo": "2.10.12",
+    "turbo": "2.11.5",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "8.70.0",
+    "typescript-eslint": "8.70.1",
     "vitepress": "2.0.0-alpha.20",
     "vitepress-plugin-group-icons": "1.7.6",
-    "vitest": "5.0.0"
+    "vitest": "5.0.2"
   },
   "peerDependencies": {
     "@cronn/playwright-file-snapshots": "^2",
@@ -64,7 +64,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.5.1",
+      "version": "12.9.1",
       "onFail": "download"
     },
     "runtime": {
@@ -90,9 +90,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",