@cronn/playwright-utils 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Normalizer } from "@cronn/playwright-file-snapshots";
-import { APIRequestContext, Locator, Page } from "@playwright/test";
+import { APIRequestContext, APIResponse, 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,270 @@ type FetchAPI = typeof fetch;
  */
 declare function createFetchAdapter(requestContext: APIRequestContext): FetchAPI;
 //#endregion
+//#region src/api/route-interceptor/filter.d.ts
+/**
+ * HTTP Methods used by {@link RouteFilter}
+ */
+type HttpMethod = "GET" | "PATCH" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "QUERY" | "HEAD";
+/**
+ * Filters used to intercept routes with {@link RouteInterceptor}.
+ *
+ * @see matchPath
+ */
+interface RouteFilter {
+  method?: HttpMethod | Array<HttpMethod>;
+  url: (url: URL) => boolean;
+}
+/**
+ * Helper to create a {@link RouteFilter} that applies to the specified path.
+ *
+ * @param pattern - The regex or string matching the pathname of the URL
+ * @returns RouteFilter
+ * @example
+ * ```ts
+ * await interceptRoute(page, matchPath("/users/1"))
+ *   .respondWith({ status: 404 })
+ *   .during(() => {
+ *     // ...
+ *   });
+ * ```
+ */
+declare function matchPath(pattern: RegExp | string): RouteFilter;
+//#endregion
+//#region src/api/route-interceptor/response-handler.d.ts
+/**
+ * Interface used to modify responses with {@link RouteInterceptor#modifyResponse}.
+ *
+ * @see modifyJsonBody
+ * @see modifyTextBody
+ */
+type ResponseHandler = (response: APIResponse) => Promise<FulfillOptions> | FulfillOptions;
+/**
+ * Helper to create a {@link ResponseHandler} that modifies the response body, if it is a JSON object.
+ *
+ * @param modifier - The callback which modifies the response body before returning it to the client
+ * @returns ResponseHandler
+ *
+ * @example
+ * ```ts
+ * await interceptRoute(page, matchPath("/users/1"))
+ *   .modifyResponse(modifyJsonBody(user => ({...user, username: "modified_username"})))
+ *   .during(async() => {
+ *     // ... perform action to trigger request to /users/1 ...
+ *   });
+ * ```
+ */
+declare function modifyJsonBody<T>(modifier: (body: T) => T): ResponseHandler;
+/**
+ * Helper to create a {@link ResponseHandler} that modifies the response body as a plaintext string.
+ *
+ * @param modifier - The callback which modifies the response body before returning it to the client
+ * @returns ResponseHandler
+ *
+ * @example
+ * ```ts
+ * await interceptRoute(page, matchPath("/email/1/subject"))
+ *   .modifyResponse(modifyTextBody(body => body.toLowerCase()))
+ *   .during(async() => {
+ *     // ... perform action to trigger request to /email/1/subject ...
+ *   });
+ * ```
+ */
+declare function modifyTextBody(modifier: (body: string) => string): ResponseHandler;
+//#endregion
+//#region src/api/route-interceptor/interceptor.d.ts
+type Action<T> = () => Promise<T> | T;
+type FulfillOptions = Parameters<Route["fulfill"]>[0];
+/**
+ * Entrypoint to create various network interceptors using the {@link Page#route} API.
+ */
+declare class RouteInterceptor {
+  readonly page: Page;
+  readonly filter: RouteFilter;
+  constructor(page: Page, filter: RouteFilter);
+  /**
+   * Abort the target route for the duration of the callback.
+   *
+   * This method returns a stub to continue chaining with.
+   *
+   * @returns ExecutableRouteInterceptor
+   * @see {@link Route#abort}
+   *
+   * @example
+   * ```ts
+   * interceptor.abort().during(() => button.click())
+   * ```
+   */
+  abort(): ExecutableRouteInterceptor;
+  /**
+   * Suspend the target route for the duration of the callback.
+   *
+   * A suspended route will not serve the response until the callback completes,
+   * this is useful to validate loading indicators.
+   *
+   * This method returns a stub to continue chaining with.
+   *
+   * @returns ExecutableRouteInterceptor
+   *
+   * @example
+   * ```ts
+   * interceptor.suspend().during(async () => {
+   *   await button.click();
+   *   await expect(loadingOverlay).toBeVisisble();
+   * });
+   * ```
+   */
+  suspend(): ExecutableRouteInterceptor;
+  /**
+   * Replace the response on the target route for the duration of the callback.
+   *
+   * The request will not hit the server at all and instead immediately return the provided response.
+   *
+   * This method returns a stub to continue chaining with.
+   *
+   * @param options - The fixed response to return for the target route
+   * @returns ExecutableRouteInterceptor
+   * @see {@link Route#fulfill}
+   *
+   * @example
+   * ```ts
+   * interceptor.respondWith({ status: 500 }).during(async () => {
+   *   await button.click();
+   *   await expect(alert).toBeVisisble();
+   * });
+   * ```
+   */
+  respondWith(options: FulfillOptions): ExecutableRouteInterceptor;
+  /**
+   * Modify the response on the target route for the duration of the callback.
+   *
+   * The route will first process the request to the server
+   * and then apply the provided callback to modify the content before returning it to the client.
+   *
+   * This method returns a stub to continue chaining with.
+   *
+   * @param modifier - Callback to modify the response of the server before returning it to the client
+   * @returns ExecutableRouteInterceptor
+   * @see {@link Route#fetch}, {@link Route#fulfill}
+   *
+   * @example
+   * ```ts
+   * interceptor.respondWith({ status: 500 }).during(async () => {
+   *   await button.click();
+   *   await expect(alert).toBeVisisble();
+   * });
+   * ```
+   */
+  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.
+ *
+ * @example
+ * ```ts
+ * interceptor.respondWith({ status: 500 }).during(async () => {
+ *   await button.click();
+ *   await expect(alert).toBeVisisble();
+ * });
+ * ```
+ */
+declare class ExecutableRouteInterceptor {
+  private readonly runner;
+  constructor(runner: <T>(action: Action<T>) => Promise<T>);
+  /**
+   * Run the given callback and intercept the stubbed route.
+   *
+   * The route interceptor is automatically removed when this method returns.
+   *
+   * @param action - The action to run with an intercepted route
+   * @returns The result of the action
+   */
+  during<T>(action: Action<T>): Promise<T>;
+}
+/**
+ * Intercept a route using the provided filter.
+ *
+ * The returned {@link RouteInterceptor} can be used to declare how the route should be intercepted.
+ *
+ * @param page – The page object to intercept the route on
+ * @param filter - The route to intercept
+ * @returns RouteInterceptor
+ * @see {@link matchPath}
+ *
+ * @example
+ * ```ts
+ * await interceptRoute(page, matchPath("/api/notifications"))
+ *   .respondWith({ status: 500 })
+ *   .during(async () => {
+ *     await page.getByRole("button", {name: "View notifications"}).click();
+ *     await expect(page.getByRole("alert")).toBeVisible();
+ *     await expect(page.getByRole("alert")).toHaveText("Failed to load notification");
+ *   });
+ * ```
+ */
+declare function interceptRoute(page: Page, filter: RouteFilter): RouteInterceptor;
+/**
+ * Base class to build re-usable route interceptors.
+ *
+ * This is especially useful when combined with {@link test#extend} to create a custom fixture.
+ *
+ * @example
+ * ```ts
+ * class CustomRouteInterceptorFixture extends RouteInterceptorFixture {
+ *   public onGetUser(userId = 1): RouteInterceptor {
+ *     return this.intercept(matchPath(`/api/users/${userId}`));
+ *   }
+ * }
+ *
+ * const test = baseTest.extend<{ intercept: CustomRouteInterceptorFixture }>({
+ *   intercept: ({ page }, use) => use(new CustomRouteInterceptorFixture(page)),
+ * });
+ *
+ * test("Fail to get user", async ({ intercept, page }) => {
+ *   await page.goto("/users");
+ *   await intercept
+ *     .onGetUser()
+ *     .respondWith({ status: 404 })
+ *     .during(async () => {
+ *       await page.getByRole("button", {name: "View profile"});
+ *       await expect(page.getByRole("alert")).toHaveText("User not found");
+ *     });
+ * });
+ * ```
+ */
+declare class RouteInterceptorFixture {
+  private readonly page;
+  constructor(page: Page);
+  /**
+   * Create a {@link RouteInterceptor} for routes matching the provided filter.
+   *
+   * @param filter - The filter to intercept routes with
+   * @returns RouteInterceptor
+   *
+   * @example
+   * ```ts
+   * await intercept({ method: "POST", url: "/api/messages" })
+   *   .abort()
+   *   .during(() => sendButton.click());
+   * ```
+   */
+  intercept(filter: RouteFilter): RouteInterceptor;
+}
+//#endregion
 //#region src/file.d.ts
 /**
  * Resolves the given path segments against the root directory of the closest
@@ -70,4 +334,4 @@ declare function maskedValueWithIndex(name: string): (index: number) => string;
  */
 type PlaywrightTarget = Page | Locator;
 //#endregion
-export { type PlaywrightTarget, createFetchAdapter, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, resolveFromPackageRoot };
+export { type HttpMethod, type PlaywrightTarget, type ResponseHandler, type RouteFilter, RouteInterceptor, RouteInterceptorFixture, createFetchAdapter, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot };

package/dist/index.mjs

@@ -54,6 +54,362 @@ function mapToRequestBody(body) {
 	return { data: body };
 }
 //#endregion
+//#region src/api/route-interceptor/interceptor.ts
+function isFiltered(filter, request) {
+	if (!filter.url(new URL(request.url()))) return false;
+	const method = filter.method;
+	if (method === void 0) return true;
+	if (typeof method === "string") return method === request.method();
+	else return method.includes(request.method());
+}
+async function uninstallRoute(page, filter, handler) {
+	try {
+		await page.unroute(filter.url, handler);
+	} catch (error) {
+		if (!page.isClosed()) throw error;
+	}
+}
+async function withFulfilledRoute(page, filter, options, action) {
+	async function handler(route, request) {
+		if (isFiltered(filter, request)) await route.fulfill(options);
+		else await route.fallback();
+	}
+	await page.route(filter.url, handler);
+	try {
+		return await action();
+	} finally {
+		await uninstallRoute(page, filter, handler);
+	}
+}
+async function withAbortedRoute(page, filter, action) {
+	async function handler(route, request) {
+		if (isFiltered(filter, request)) await route.abort();
+		else await route.fallback();
+	}
+	await page.route(filter.url, handler);
+	try {
+		return await action();
+	} finally {
+		await uninstallRoute(page, filter, handler);
+	}
+}
+async function withSuspendedRoute(page, filter, action) {
+	const barrier = Promise.withResolvers();
+	const suspendedRoutes = /* @__PURE__ */ new Set();
+	async function handler(route, request) {
+		if (!isFiltered(filter, request)) {
+			await route.fallback();
+			return;
+		}
+		const suspendedRoute = barrier.promise.then(() => route.continue());
+		suspendedRoutes.add(suspendedRoute);
+		try {
+			await suspendedRoute;
+		} finally {
+			suspendedRoutes.delete(suspendedRoute);
+		}
+	}
+	await page.route(filter.url, handler);
+	try {
+		return await action();
+	} finally {
+		barrier.resolve();
+		await Promise.allSettled([...suspendedRoutes]);
+		await uninstallRoute(page, filter, handler);
+	}
+}
+async function withModifiedResponse(page, filter, interceptor, action) {
+	async function handler(route, request) {
+		if (isFiltered(filter, request)) {
+			const response = await route.fetch();
+			await route.fulfill(await interceptor(response));
+		} else await route.fallback();
+	}
+	await page.route(filter.url, handler);
+	try {
+		return await action();
+	} finally {
+		await uninstallRoute(page, filter, handler);
+	}
+}
+/**
+* Entrypoint to create various network interceptors using the {@link Page#route} API.
+*/
+var RouteInterceptor = class {
+	page;
+	filter;
+	constructor(page, filter) {
+		this.page = page;
+		this.filter = filter;
+	}
+	/**
+	* Abort the target route for the duration of the callback.
+	*
+	* This method returns a stub to continue chaining with.
+	*
+	* @returns ExecutableRouteInterceptor
+	* @see {@link Route#abort}
+	*
+	* @example
+	* ```ts
+	* interceptor.abort().during(() => button.click())
+	* ```
+	*/
+	abort() {
+		return new ExecutableRouteInterceptor((action) => withAbortedRoute(this.page, this.filter, action));
+	}
+	/**
+	* Suspend the target route for the duration of the callback.
+	*
+	* A suspended route will not serve the response until the callback completes,
+	* this is useful to validate loading indicators.
+	*
+	* This method returns a stub to continue chaining with.
+	*
+	* @returns ExecutableRouteInterceptor
+	*
+	* @example
+	* ```ts
+	* interceptor.suspend().during(async () => {
+	*   await button.click();
+	*   await expect(loadingOverlay).toBeVisisble();
+	* });
+	* ```
+	*/
+	suspend() {
+		return new ExecutableRouteInterceptor((action) => withSuspendedRoute(this.page, this.filter, action));
+	}
+	/**
+	* Replace the response on the target route for the duration of the callback.
+	*
+	* The request will not hit the server at all and instead immediately return the provided response.
+	*
+	* This method returns a stub to continue chaining with.
+	*
+	* @param options - The fixed response to return for the target route
+	* @returns ExecutableRouteInterceptor
+	* @see {@link Route#fulfill}
+	*
+	* @example
+	* ```ts
+	* interceptor.respondWith({ status: 500 }).during(async () => {
+	*   await button.click();
+	*   await expect(alert).toBeVisisble();
+	* });
+	* ```
+	*/
+	respondWith(options) {
+		return new ExecutableRouteInterceptor((action) => withFulfilledRoute(this.page, this.filter, options, action));
+	}
+	/**
+	* Modify the response on the target route for the duration of the callback.
+	*
+	* The route will first process the request to the server
+	* and then apply the provided callback to modify the content before returning it to the client.
+	*
+	* This method returns a stub to continue chaining with.
+	*
+	* @param modifier - Callback to modify the response of the server before returning it to the client
+	* @returns ExecutableRouteInterceptor
+	* @see {@link Route#fetch}, {@link Route#fulfill}
+	*
+	* @example
+	* ```ts
+	* interceptor.respondWith({ status: 500 }).during(async () => {
+	*   await button.click();
+	*   await expect(alert).toBeVisisble();
+	* });
+	* ```
+	*/
+	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.
+*
+* @example
+* ```ts
+* interceptor.respondWith({ status: 500 }).during(async () => {
+*   await button.click();
+*   await expect(alert).toBeVisisble();
+* });
+* ```
+*/
+var ExecutableRouteInterceptor = class {
+	runner;
+	constructor(runner) {
+		this.runner = runner;
+	}
+	/**
+	* Run the given callback and intercept the stubbed route.
+	*
+	* The route interceptor is automatically removed when this method returns.
+	*
+	* @param action - The action to run with an intercepted route
+	* @returns The result of the action
+	*/
+	async during(action) {
+		return await this.runner(action);
+	}
+};
+/**
+* Intercept a route using the provided filter.
+*
+* The returned {@link RouteInterceptor} can be used to declare how the route should be intercepted.
+*
+* @param page – The page object to intercept the route on
+* @param filter - The route to intercept
+* @returns RouteInterceptor
+* @see {@link matchPath}
+*
+* @example
+* ```ts
+* await interceptRoute(page, matchPath("/api/notifications"))
+*   .respondWith({ status: 500 })
+*   .during(async () => {
+*     await page.getByRole("button", {name: "View notifications"}).click();
+*     await expect(page.getByRole("alert")).toBeVisible();
+*     await expect(page.getByRole("alert")).toHaveText("Failed to load notification");
+*   });
+* ```
+*/
+function interceptRoute(page, filter) {
+	return new RouteInterceptor(page, filter);
+}
+/**
+* Base class to build re-usable route interceptors.
+*
+* This is especially useful when combined with {@link test#extend} to create a custom fixture.
+*
+* @example
+* ```ts
+* class CustomRouteInterceptorFixture extends RouteInterceptorFixture {
+*   public onGetUser(userId = 1): RouteInterceptor {
+*     return this.intercept(matchPath(`/api/users/${userId}`));
+*   }
+* }
+*
+* const test = baseTest.extend<{ intercept: CustomRouteInterceptorFixture }>({
+*   intercept: ({ page }, use) => use(new CustomRouteInterceptorFixture(page)),
+* });
+*
+* test("Fail to get user", async ({ intercept, page }) => {
+*   await page.goto("/users");
+*   await intercept
+*     .onGetUser()
+*     .respondWith({ status: 404 })
+*     .during(async () => {
+*       await page.getByRole("button", {name: "View profile"});
+*       await expect(page.getByRole("alert")).toHaveText("User not found");
+*     });
+* });
+* ```
+*/
+var RouteInterceptorFixture = class {
+	page;
+	constructor(page) {
+		this.page = page;
+	}
+	/**
+	* Create a {@link RouteInterceptor} for routes matching the provided filter.
+	*
+	* @param filter - The filter to intercept routes with
+	* @returns RouteInterceptor
+	*
+	* @example
+	* ```ts
+	* await intercept({ method: "POST", url: "/api/messages" })
+	*   .abort()
+	*   .during(() => sendButton.click());
+	* ```
+	*/
+	intercept(filter) {
+		return interceptRoute(this.page, filter);
+	}
+};
+//#endregion
+//#region src/api/route-interceptor/filter.ts
+/**
+* Helper to create a {@link RouteFilter} that applies to the specified path.
+*
+* @param pattern - The regex or string matching the pathname of the URL
+* @returns RouteFilter
+* @example
+* ```ts
+* await interceptRoute(page, matchPath("/users/1"))
+*   .respondWith({ status: 404 })
+*   .during(() => {
+*     // ...
+*   });
+* ```
+*/
+function matchPath(pattern) {
+	return { url: (url) => typeof pattern === "string" ? url.pathname === pattern : url.pathname.match(pattern) !== null };
+}
+//#endregion
+//#region src/api/route-interceptor/response-handler.ts
+/**
+* Helper to create a {@link ResponseHandler} that modifies the response body, if it is a JSON object.
+*
+* @param modifier - The callback which modifies the response body before returning it to the client
+* @returns ResponseHandler
+*
+* @example
+* ```ts
+* await interceptRoute(page, matchPath("/users/1"))
+*   .modifyResponse(modifyJsonBody(user => ({...user, username: "modified_username"})))
+*   .during(async() => {
+*     // ... perform action to trigger request to /users/1 ...
+*   });
+* ```
+*/
+function modifyJsonBody(modifier) {
+	return async (response) => ({
+		body: JSON.stringify(modifier(await response.json())),
+		response
+	});
+}
+/**
+* Helper to create a {@link ResponseHandler} that modifies the response body as a plaintext string.
+*
+* @param modifier - The callback which modifies the response body before returning it to the client
+* @returns ResponseHandler
+*
+* @example
+* ```ts
+* await interceptRoute(page, matchPath("/email/1/subject"))
+*   .modifyResponse(modifyTextBody(body => body.toLowerCase()))
+*   .during(async() => {
+*     // ... perform action to trigger request to /email/1/subject ...
+*   });
+* ```
+*/
+function modifyTextBody(modifier) {
+	return async (response) => ({
+		response,
+		body: modifier(await response.text())
+	});
+}
+//#endregion
 //#region src/file.ts
 /**
 * Resolves the given path segments against the root directory of the closest
@@ -108,4 +464,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { createFetchAdapter, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, resolveFromPackageRoot };
+export { RouteInterceptor, RouteInterceptorFixture, createFetchAdapter, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/playwright-utils",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",
@@ -33,29 +33,30 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
-    "@changesets/cli": "3.0.0",
+    "@changesets/cli": "3.0.1",
+    "@cronn/element-snapshot": "0.27.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.10",
-    "eslint": "10.8.1",
+    "@vitest/coverage-v8": "4.1.11",
+    "eslint": "10.9.0",
     "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.144.0",
-    "oxfmt": "0.63.0",
-    "publint": "0.3.23",
+    "oxc-minify": "0.146.0",
+    "oxfmt": "0.64.0",
+    "publint": "0.3.24",
     "rimraf": "6.1.3",
     "tsdown": "0.22.14",
-    "turbo": "2.10.10",
+    "turbo": "2.10.11",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "8.67.0",
     "vitepress": "2.0.0-alpha.19",
     "vitepress-plugin-group-icons": "1.7.6",
-    "vitest": "4.1.10",
-    "node": "runtime:24.19.0"
+    "vitest": "4.1.11",
+    "node": "runtime:24.20.0"
   },
   "peerDependencies": {
     "@cronn/playwright-file-snapshots": "^2",
@@ -64,12 +65,12 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "11.22.0",
+      "version": "11.25.0",
       "onFail": "download"
     },
     "runtime": {
       "name": "node",
-      "version": "24.19.0",
+      "version": "24.20.0",
       "onFail": "download"
     }
   },