@cronn/playwright-utils 0.6.0 → 0.7.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}
@@ -529,4 +673,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, 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;
@@ -771,4 +951,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, 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.7.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",