@cronn/playwright-utils 0.0.1 → 0.2.0

package/dist/index.d.mts

@@ -1,5 +1,14 @@
 import { Normalizer } from "@cronn/playwright-file-snapshots";
-import { APIRequestContext, Locator, Page } from "@playwright/test";
+import { APIRequestContext, APIResponse, Locator, Page, Route } from "@playwright/test";
+//#region src/environment.d.ts
+/**
+ * Whether the current process runs in a CI environment, based on the `CI`
+ * environment variable.
+ *
+ * Evaluated once when the module is loaded.
+ */
+declare const isCI: boolean;
+//#endregion
 //#region src/api/fetch-adapter.d.ts
 type FetchAPI = typeof fetch;
 /**
@@ -12,7 +21,272 @@ type FetchAPI = typeof fetch;
  * @param requestContext - Playwright request context to send requests with
  * @returns A function with the signature of the global `fetch`
  */
-declare function fetchAdapter(requestContext: APIRequestContext): FetchAPI;
+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;
+}
+/**
+ * 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
+ * package, i.e. the closest directory containing a `package.json`, searching
+ * upwards from the current working directory.
+ *
+ * Useful for referencing files independently of the directory a test run is
+ * started from, e.g. a subdirectory of the package.
+ *
+ * @param paths - Path segments to resolve against the package root
+ * @returns The absolute path to the resolved location
+ * @throws If no package root can be found
+ */
+declare function resolveFromPackageRoot(...paths: Array<string>): string;
 //#endregion
 //#region src/normalizers/mask-base-url.d.ts
 /**
@@ -46,5 +320,4 @@ declare function maskedValueWithIndex(name: string): (index: number) => string;
  */
 type PlaywrightTarget = Page | Locator;
 //#endregion
-export { type PlaywrightTarget, fetchAdapter, maskBaseURL, maskedValue, maskedValueWithIndex };
-//# sourceMappingURL=index.d.mts.map
+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

@@ -1,4 +1,15 @@
+import path from "node:path";
+import { packageDirectorySync } from "package-directory";
 import { maskString, stringNormalizer } from "@cronn/playwright-file-snapshots";
+//#region src/environment.ts
+/**
+* Whether the current process runs in a CI environment, based on the `CI`
+* environment variable.
+*
+* Evaluated once when the module is loaded.
+*/
+const isCI = process.env.CI === "true";
+//#endregion
 //#region src/api/fetch-adapter.ts
 /**
 * Creates a `fetch`-compatible function backed by a Playwright
@@ -10,7 +21,7 @@ import { maskString, stringNormalizer } from "@cronn/playwright-file-snapshots";
 * @param requestContext - Playwright request context to send requests with
 * @returns A function with the signature of the global `fetch`
 */
-function fetchAdapter(requestContext) {
+function createFetchAdapter(requestContext) {
 	return async (input, init) => {
 		const response = await requestContext.fetch(mapToUrl(input), await mapToOptions(input instanceof Request ? input : null, init));
 		const responseBody = await response.body();
@@ -43,6 +54,363 @@ 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));
+	}
+};
+/**
+* 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
+* package, i.e. the closest directory containing a `package.json`, searching
+* upwards from the current working directory.
+*
+* Useful for referencing files independently of the directory a test run is
+* started from, e.g. a subdirectory of the package.
+*
+* @param paths - Path segments to resolve against the package root
+* @returns The absolute path to the resolved location
+* @throws If no package root can be found
+*/
+function resolveFromPackageRoot(...paths) {
+	const packageDir = packageDirectorySync();
+	if (packageDir === void 0) throw new Error("Unable to resolve package directory");
+	return path.resolve(packageDir, ...paths);
+}
+//#endregion
 //#region src/normalizers/masked-value.ts
 /**
 * Formats a name as a masked placeholder, e.g. `maskedValue("base url")`
@@ -78,6 +446,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { fetchAdapter, maskBaseURL, maskedValue, maskedValueWithIndex };
-
-//# sourceMappingURL=index.mjs.map
+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.0.1",
+  "version": "0.2.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",
@@ -28,54 +28,35 @@
       "default": "./dist/index.mjs"
     }
   },
-  "scripts": {
-    "build": "tsdown",
-    "clean": "rimraf .turbo dist coverage playwright-report test-results docs/.vitepress/cache docs/.vitepress/dist && pnpm run pnpm:clean",
-    "compile": "tsc",
-    "docs:build": "vitepress build docs",
-    "docs:dev": "vitepress dev docs",
-    "docs:preview": "vitepress preview docs",
-    "format:check": "oxfmt --check",
-    "format:fix": "oxfmt",
-    "knip:check": "knip",
-    "knip:fix": "knip --fix",
-    "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",
-    "prepublishOnly": "pnpm turbo run ci",
-    "release": "pnpm turbo run build && pnpm changeset publish",
-    "test:integration": "playwright test",
-    "test:unit": "vitest run",
-    "test:unit:coverage": "vitest run --coverage",
-    "version": "pnpm changeset version && pnpm turbo run format:fix"
+  "dependencies": {
+    "package-directory": "8.2.0"
   },
   "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"
+    "vitest": "4.1.11",
+    "node": "runtime:24.20.0"
   },
   "peerDependencies": {
     "@cronn/playwright-file-snapshots": "^2",
@@ -84,16 +65,39 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "11.22.0",
-      "onFail": "ignore"
+      "version": "11.25.0",
+      "onFail": "download"
     },
     "runtime": {
       "name": "node",
-      "version": "24.19.0",
-      "onFail": "ignore"
+      "version": "24.20.0",
+      "onFail": "download"
     }
   },
   "engines": {
     "node": "^22 || ^24 || >=26"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rimraf .turbo dist coverage playwright-report test-results docs/.vitepress/cache docs/.vitepress/dist && pnpm run pnpm:clean",
+    "compile": "tsc",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
+    "format:check": "oxfmt --check",
+    "format:fix": "oxfmt",
+    "knip:check": "knip",
+    "knip:fix": "knip --fix",
+    "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",
+    "test:unit:coverage": "vitest run --coverage",
+    "version": "pnpm changeset version && pnpm turbo run format:fix"
   }
-}
+}

package/dist/index.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/api/fetch-adapter.ts","../src/normalizers/mask-base-url.ts","../src/normalizers/masked-value.ts","../src/types/playwright.ts"],"mappings":";;;KAEY,kBAAkB;;;;;;;;;;;iBAgBd,aAAa,gBAAgB,oBAAoB;;;;;;;;;iBCPjD,YAAY,QAC1B,8BACC,WAAW;;;;;;;;;iBCPE,YAAY;;;;;;;iBAWZ,qBAAqB,gBAAgB;;;;;;;KCXzC,mBAAmB,OAAO"}

package/dist/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/api/fetch-adapter.ts","../src/normalizers/masked-value.ts","../src/normalizers/mask-base-url.ts"],"sourcesContent":["import type { APIRequestContext } from \"@playwright/test\";\n\nexport type FetchAPI = typeof fetch;\n\ntype PlaywrightFetchOptions = NonNullable<\n  Parameters<APIRequestContext[\"fetch\"]>[1]\n>;\n\n/**\n * Creates a `fetch`-compatible function backed by a Playwright\n * {@link APIRequestContext}.\n *\n * Useful for passing Playwright's request context to API clients that expect\n * the standard Fetch API.\n *\n * @param requestContext - Playwright request context to send requests with\n * @returns A function with the signature of the global `fetch`\n */\nexport function fetchAdapter(requestContext: APIRequestContext): FetchAPI {\n  return async (input, init): Promise<Response> => {\n    const response = await requestContext.fetch(\n      mapToUrl(input),\n      await mapToOptions(input instanceof Request ? input : null, init),\n    );\n\n    const responseBody = await response.body();\n    return new Response(Buffer.from(responseBody), {\n      status: response.status(),\n      headers: response.headers(),\n    });\n  };\n}\n\nfunction mapToUrl(input: RequestInfo | URL): string {\n  if (typeof input === \"string\") {\n    return input;\n  }\n\n  if (input instanceof Request) {\n    return input.url;\n  }\n\n  return input.toString();\n}\n\nasync function mapToOptions(\n  request: Request | null,\n  init?: RequestInit,\n): Promise<PlaywrightFetchOptions> {\n  const requestBody =\n    request?.body !== null ? await request?.bytes() : undefined;\n  return {\n    method: request?.method ?? init?.method,\n    headers: mapToRequestHeaders(request?.headers ?? init?.headers),\n    ...mapToRequestBody(\n      requestBody !== undefined ? Buffer.from(requestBody) : init?.body,\n    ),\n  };\n}\n\nfunction mapToRequestHeaders(\n  headers: HeadersInit | undefined,\n): PlaywrightFetchOptions[\"headers\"] {\n  if (Array.isArray(headers)) {\n    return Object.fromEntries(headers);\n  }\n\n  if (headers instanceof Headers) {\n    return Object.fromEntries(headers.entries());\n  }\n\n  return headers;\n}\n\nfunction mapToRequestBody(\n  body: BodyInit | null | undefined,\n): Pick<PlaywrightFetchOptions, \"data\" | \"multipart\"> {\n  if (body instanceof FormData) {\n    return {\n      multipart: body,\n    };\n  }\n\n  return {\n    data: body,\n  };\n}\n","/**\n * Formats a name as a masked placeholder, e.g. `maskedValue(\"base url\")`\n * returns `[BASE_URL]`.\n *\n * @param name - Name of the masked value\n */\nexport function maskedValue(name: string): string {\n  const normalizedName = name.toUpperCase().replace(/[ -.:,;]/g, \"_\");\n  return `[${normalizedName}]`;\n}\n\n/**\n * Creates a factory for indexed masked placeholders, e.g. `[USER_1]`.\n *\n * @param name - Name of the masked value\n * @returns A function mapping an index to a masked placeholder\n */\nexport function maskedValueWithIndex(name: string): (index: number) => string {\n  return (index: number) => maskedValue(`${name}_${index}`);\n}\n","import type { Normalizer } from \"@cronn/playwright-file-snapshots\";\nimport { maskString, stringNormalizer } from \"@cronn/playwright-file-snapshots\";\n\nimport { maskedValue } from \"./masked-value\";\n\n/**\n * Creates a normalizer that replaces occurrences of the base URL with\n * `[BASE_URL]`, keeping file snapshots stable across environments.\n *\n * @param baseURL - Base URL to mask; if `undefined`, values are left unchanged\n */\nexport function maskBaseURL<TValue>(\n  baseURL: string | undefined,\n): Normalizer<TValue> {\n  if (baseURL === undefined) {\n    return identity<TValue>;\n  }\n\n  return stringNormalizer(maskString(baseURL, maskedValue(\"BASE_URL\")));\n}\n\nfunction identity<TValue>(value: TValue): TValue {\n  return value;\n}\n"],"mappings":";;;;;;;;;;;;AAkBA,SAAgB,aAAa,gBAA6C;CACxE,OAAO,OAAO,OAAO,SAA4B;EAC/C,MAAM,WAAW,MAAM,eAAe,MACpC,SAAS,KAAK,GACd,MAAM,aAAa,iBAAiB,UAAU,QAAQ,MAAM,IAAI,CAClE;EAEA,MAAM,eAAe,MAAM,SAAS,KAAK;EACzC,OAAO,IAAI,SAAS,OAAO,KAAK,YAAY,GAAG;GAC7C,QAAQ,SAAS,OAAO;GACxB,SAAS,SAAS,QAAQ;EAC5B,CAAC;CACH;AACF;AAEA,SAAS,SAAS,OAAkC;CAClD,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,iBAAiB,SACnB,OAAO,MAAM;CAGf,OAAO,MAAM,SAAS;AACxB;AAEA,eAAe,aACb,SACA,MACiC;CACjC,MAAM,cACJ,SAAS,SAAS,OAAO,MAAM,SAAS,MAAM,IAAI,KAAA;CACpD,OAAO;EACL,QAAQ,SAAS,UAAU,MAAM;EACjC,SAAS,oBAAoB,SAAS,WAAW,MAAM,OAAO;EAC9D,GAAG,iBACD,gBAAgB,KAAA,IAAY,OAAO,KAAK,WAAW,IAAI,MAAM,IAC/D;CACF;AACF;AAEA,SAAS,oBACP,SACmC;CACnC,IAAI,MAAM,QAAQ,OAAO,GACvB,OAAO,OAAO,YAAY,OAAO;CAGnC,IAAI,mBAAmB,SACrB,OAAO,OAAO,YAAY,QAAQ,QAAQ,CAAC;CAG7C,OAAO;AACT;AAEA,SAAS,iBACP,MACoD;CACpD,IAAI,gBAAgB,UAClB,OAAO,EACL,WAAW,KACb;CAGF,OAAO,EACL,MAAM,KACR;AACF;;;;;;;;;AChFA,SAAgB,YAAY,MAAsB;CAEhD,OAAO,IADgB,KAAK,YAAY,CAAC,CAAC,QAAQ,aAAa,GACvC,EAAE;AAC5B;;;;;;;AAQA,SAAgB,qBAAqB,MAAyC;CAC5E,QAAQ,UAAkB,YAAY,GAAG,KAAK,GAAG,OAAO;AAC1D;;;;;;;;;ACRA,SAAgB,YACd,SACoB;CACpB,IAAI,YAAY,KAAA,GACd,OAAO;CAGT,OAAO,iBAAiB,WAAW,SAAS,YAAY,UAAU,CAAC,CAAC;AACtE;AAEA,SAAS,SAAiB,OAAuB;CAC/C,OAAO;AACT"}