@cronn/playwright-utils 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Normalizer } from "@cronn/playwright-file-snapshots";
-import { APIRequestContext, APIResponse, Locator, Page, Route } from "@playwright/test";
+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`
@@ -23,6 +23,151 @@ type FetchAPI = typeof fetch;
  */
 declare function createFetchAdapter(requestContext: APIRequestContext): FetchAPI;
 //#endregion
+//#region src/capturing/console-captor.d.ts
+/**
+ * Filter used to select the messages collected by a {@link ConsoleCaptor}.
+ */
+type ConsoleMessageFilter = (message: ConsoleMessage) => boolean;
+/**
+ * The log level of a {@link ConsoleMessage}, e.g. `log`, `warning` or `error`.
+ */
+type ConsoleMessageLevel = ReturnType<ConsoleMessage["type"]>;
+/**
+ * Collects the console messages of a page.
+ *
+ * Playwright reports the console output of a page through its `console` event,
+ * which has to be registered and removed again by hand. A captor bundles these
+ * steps, optionally filters the messages by level or a custom predicate and can
+ * limit the capturing to a single action.
+ *
+ * Several captors can run on the same page at the same time, each with its own
+ * filter, and every captor receives all matching messages independently.
+ *
+ * @example
+ * ```ts
+ * const logs = captureConsole(page);
+ *
+ * await logs.during(async () => {
+ *   await page.goto("/users");
+ *   await page.getByRole("button", { name: "Only enabled" }).click();
+ * });
+ *
+ * expect(logs.messages.map((message) => message.text())).toEqual([
+ *   "filter changed: enabled",
+ * ]);
+ * ```
+ */
+declare class ConsoleCaptor {
+  private readonly page;
+  private readonly consoleListener;
+  /**
+   * The captured messages, 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 messages: Array<ConsoleMessage>;
+  /**
+   * Create a captor for the console messages 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 console messages of
+   * @param filter - Optional. Decides which messages are captured, captures every message if omitted
+   *
+   * @example
+   * ```ts
+   * const captor = captureConsole(page, (message) =>
+   *   message.location().url.endsWith("/analytics.js"),
+   * );
+   * ```
+   */
+  constructor(page: Page, filter?: ConsoleMessageFilter);
+  /**
+   * Start collecting the console messages of the page.
+   *
+   * A captor can be started and stopped repeatedly; the collected messages are
+   * kept across restarts.
+   *
+   * @example
+   * ```ts
+   * export const test = baseTest.extend<{ consoleErrors: ConsoleCaptor }>({
+   *   consoleErrors: async ({ page }, use) => {
+   *     const captor = captureConsole(page, "error");
+   *     captor.start();
+   *
+   *     await use(captor);
+   *
+   *     captor.stop();
+   *     expect(captor.messages.map((message) => message.text())).toEqual([]);
+   *   },
+   * });
+   * ```
+   */
+  startCapture(): void;
+  /**
+   * Stop collecting the console messages of the page.
+   *
+   * The already captured {@link messages} are kept.
+   */
+  stopCapture(): void;
+  /**
+   * Collect the console messages 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.
+   *
+   * Only the returned value is awaited: asynchronous work which the action
+   * starts without returning it is not covered by the capturing.
+   *
+   * @param action - The action to capture console messages during
+   * @returns The value of the action
+   *
+   * @example
+   * ```ts
+   * const captor = captureConsole(page, "error");
+   *
+   * await captor.during(async () => {
+   *   await page.getByRole("button", { name: "Create user" }).click();
+   *   await expect(page.getByRole("alert")).toBeVisible();
+   * });
+   *
+   * expect(captor.messages).toHaveLength(1);
+   * ```
+   */
+  during<T>(action: () => Promise<T>): Promise<T>;
+}
+/**
+ * Factory method to create a {@link ConsoleCaptor} with the provided filter.
+ *
+ * The filter can be the log-level or a custom function on the message.
+ *
+ * @param page - The page to capture logs for
+ * @param levelOrFilter - The level or filter to filter out messages
+ * @returns ConsoleCaptor
+ *
+ * @example
+ * ```ts
+ * const errorCaptor = captureConsole(page, "error");
+ * const cspCaptor = captureConsole(page, message =>
+ *     hasLogLevel(message, "warning", "error") && message.text().includes("Content Security Policy")
+ * );
+ * ```
+ */
+declare function captureConsole(page: Page, levelOrFilter?: ConsoleMessageLevel | Array<ConsoleMessageLevel> | ConsoleMessageFilter): ConsoleCaptor;
+/**
+ * Tests whether the given console message has one of the specified log levels.
+ *
+ * This can be useful to define a filter with {@link captureConsole}.
+ *
+ * @param message - The console message to check
+ * @param level - The log level
+ * @returns True if the message has one of the given log levels
+ */
+declare function hasLogLevel(message: ConsoleMessage, ...level: Array<ConsoleMessageLevel>): boolean;
+//#endregion
 //#region src/api/route-interceptor/filter.d.ts
 /**
  * HTTP Methods used by {@link RouteFilter}
@@ -178,6 +323,20 @@ declare class RouteInterceptor {
    * ```
    */
   modifyResponse(modifier: ResponseHandler): ExecutableRouteInterceptor;
+  /**
+   * Wait until the target route was called and return the client request.
+   *
+   * @param options - Options for {@link Page#waitForRequest}
+   * @returns Response - The server response
+   */
+  waitForRequest(options?: Parameters<Page["waitForRequest"]>[1]): Promise<Request>;
+  /**
+   * Wait until the target route was called and return the server response.
+   *
+   * @param options - Options for {@link Page#waitForResponse}
+   * @returns Response - The server response
+   */
+  waitForResponse(options?: Parameters<Page["waitForResponse"]>[1]): Promise<Response>;
 }
 /**
  * Stub returned by {@link RouteInterceptor} used to intercept routes during a block.
@@ -320,4 +479,4 @@ declare function maskedValueWithIndex(name: string): (index: number) => string;
  */
 type PlaywrightTarget = Page | Locator;
 //#endregion
-export { type HttpMethod, type PlaywrightTarget, type ResponseHandler, type RouteFilter, RouteInterceptor, RouteInterceptorFixture, createFetchAdapter, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot };
+export { ConsoleCaptor, type ConsoleMessageFilter, type ConsoleMessageLevel, type HttpMethod, type PlaywrightTarget, type ResponseHandler, type RouteFilter, RouteInterceptor, RouteInterceptorFixture, captureConsole, createFetchAdapter, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot };

package/dist/index.mjs

@@ -54,6 +54,169 @@ function mapToRequestBody(body) {
 	return { data: body };
 }
 //#endregion
+//#region src/capturing/console-captor.ts
+function defaultFilter(_message) {
+	return true;
+}
+/**
+* Collects the console messages of a page.
+*
+* Playwright reports the console output of a page through its `console` event,
+* which has to be registered and removed again by hand. A captor bundles these
+* steps, optionally filters the messages by level or a custom predicate and can
+* limit the capturing to a single action.
+*
+* Several captors can run on the same page at the same time, each with its own
+* filter, and every captor receives all matching messages independently.
+*
+* @example
+* ```ts
+* const logs = captureConsole(page);
+*
+* await logs.during(async () => {
+*   await page.goto("/users");
+*   await page.getByRole("button", { name: "Only enabled" }).click();
+* });
+*
+* expect(logs.messages.map((message) => message.text())).toEqual([
+*   "filter changed: enabled",
+* ]);
+* ```
+*/
+var ConsoleCaptor = class {
+	page;
+	consoleListener;
+	/**
+	* The captured messages, 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}.
+	*/
+	messages = [];
+	/**
+	* Create a captor for the console messages 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 console messages of
+	* @param filter - Optional. Decides which messages are captured, captures every message if omitted
+	*
+	* @example
+	* ```ts
+	* const captor = captureConsole(page, (message) =>
+	*   message.location().url.endsWith("/analytics.js"),
+	* );
+	* ```
+	*/
+	constructor(page, filter = defaultFilter) {
+		this.page = page;
+		this.consoleListener = (event) => {
+			if (filter(event)) this.messages.push(event);
+		};
+	}
+	/**
+	* Start collecting the console messages of the page.
+	*
+	* A captor can be started and stopped repeatedly; the collected messages are
+	* kept across restarts.
+	*
+	* @example
+	* ```ts
+	* export const test = baseTest.extend<{ consoleErrors: ConsoleCaptor }>({
+	*   consoleErrors: async ({ page }, use) => {
+	*     const captor = captureConsole(page, "error");
+	*     captor.start();
+	*
+	*     await use(captor);
+	*
+	*     captor.stop();
+	*     expect(captor.messages.map((message) => message.text())).toEqual([]);
+	*   },
+	* });
+	* ```
+	*/
+	startCapture() {
+		this.page.on("console", this.consoleListener);
+	}
+	/**
+	* Stop collecting the console messages of the page.
+	*
+	* The already captured {@link messages} are kept.
+	*/
+	stopCapture() {
+		this.page.off("console", this.consoleListener);
+	}
+	/**
+	* Collect the console messages 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.
+	*
+	* Only the returned value is awaited: asynchronous work which the action
+	* starts without returning it is not covered by the capturing.
+	*
+	* @param action - The action to capture console messages during
+	* @returns The value of the action
+	*
+	* @example
+	* ```ts
+	* const captor = captureConsole(page, "error");
+	*
+	* await captor.during(async () => {
+	*   await page.getByRole("button", { name: "Create user" }).click();
+	*   await expect(page.getByRole("alert")).toBeVisible();
+	* });
+	*
+	* expect(captor.messages).toHaveLength(1);
+	* ```
+	*/
+	async during(action) {
+		this.startCapture();
+		try {
+			return await action();
+		} finally {
+			this.stopCapture();
+		}
+	}
+};
+/**
+* Factory method to create a {@link ConsoleCaptor} with the provided filter.
+*
+* The filter can be the log-level or a custom function on the message.
+*
+* @param page - The page to capture logs for
+* @param levelOrFilter - The level or filter to filter out messages
+* @returns ConsoleCaptor
+*
+* @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) {
+	if (levelOrFilter === void 0) return new ConsoleCaptor(page);
+	if (typeof levelOrFilter === "function") return new ConsoleCaptor(page, levelOrFilter);
+	if (Array.isArray(levelOrFilter)) return new ConsoleCaptor(page, (message) => hasLogLevel(message, ...levelOrFilter));
+	return new ConsoleCaptor(page, (message) => hasLogLevel(message, levelOrFilter));
+}
+/**
+* Tests whether the given console message has one of the specified log levels.
+*
+* This can be useful to define a filter with {@link captureConsole}.
+*
+* @param message - The console message to check
+* @param level - The log level
+* @returns True if the message has one of the given log levels
+*/
+function hasLogLevel(message, ...level) {
+	return level.includes(message.type());
+}
+//#endregion
 //#region src/api/route-interceptor/interceptor.ts
 function isFiltered(filter, request) {
 	if (!filter.url(new URL(request.url()))) return false;
@@ -101,7 +264,7 @@ async function withSuspendedRoute(page, filter, action) {
 			await route.fallback();
 			return;
 		}
-		const suspendedRoute = barrier.promise.then(() => route.continue());
+		const suspendedRoute = barrier.promise.then(() => route.fallback());
 		suspendedRoutes.add(suspendedRoute);
 		try {
 			await suspendedRoute;
@@ -224,6 +387,24 @@ var RouteInterceptor = class {
 	modifyResponse(modifier) {
 		return new ExecutableRouteInterceptor((action) => withModifiedResponse(this.page, this.filter, modifier, action));
 	}
+	/**
+	* Wait until the target route was called and return the client request.
+	*
+	* @param options - Options for {@link Page#waitForRequest}
+	* @returns Response - The server response
+	*/
+	waitForRequest(options) {
+		return this.page.waitForRequest((request) => isFiltered(this.filter, request), options);
+	}
+	/**
+	* Wait until the target route was called and return the server response.
+	*
+	* @param options - Options for {@link Page#waitForResponse}
+	* @returns Response - The server response
+	*/
+	waitForResponse(options) {
+		return this.page.waitForResponse((response) => isFiltered(this.filter, response.request()), options);
+	}
 };
 /**
 * Stub returned by {@link RouteInterceptor} used to intercept routes during a block.
@@ -446,4 +627,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { RouteInterceptor, RouteInterceptorFixture, createFetchAdapter, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot };
+export { ConsoleCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, createFetchAdapter, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/playwright-utils",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",
@@ -29,30 +29,30 @@
     }
   },
   "dependencies": {
-    "package-directory": "8.2.0"
+    "package-directory": "^8.2.0"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
     "@changesets/cli": "3.0.1",
-    "@cronn/element-snapshot": "0.27.0",
+    "@cronn/element-snapshot": "0.28.0",
     "@cronn/playwright-file-snapshots": "2.2.1",
     "@playwright/test": "1.62.1",
     "@types/node": "24.13.3",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.9.0",
+    "eslint": "10.9.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.2",
     "eslint-plugin-unused-imports": "4.4.1",
-    "knip": "6.32.2",
-    "oxc-minify": "0.146.0",
-    "oxfmt": "0.64.0",
+    "knip": "6.33.0",
+    "oxc-minify": "0.147.0",
+    "oxfmt": "0.65.0",
     "publint": "0.3.24",
     "rimraf": "6.1.3",
     "tsdown": "0.22.14",
-    "turbo": "2.10.11",
+    "turbo": "2.10.12",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "8.67.0",
+    "typescript-eslint": "8.68.0",
     "vitepress": "2.0.0-alpha.19",
     "vitepress-plugin-group-icons": "1.7.6",
     "vitest": "4.1.11",