@cronn/playwright-utils 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -7,7 +7,7 @@ import { APIRequestContext, APIResponse, ConsoleMessage, Locator, Page, Request,
  *
  * Evaluated once when the module is loaded.
  */
-declare const isCI: boolean;
+export declare const isCI: boolean;
 //#endregion
 //#region src/api/fetch-adapter.d.ts
 type FetchAPI = typeof fetch;
@@ -21,7 +21,7 @@ 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 createFetchAdapter(requestContext: APIRequestContext): FetchAPI;
+export declare function createFetchAdapter(requestContext: APIRequestContext): FetchAPI;
 //#endregion
 //#region src/capturing/console-captor.d.ts
 /**
@@ -57,7 +57,7 @@ type ConsoleMessageLevel = ReturnType<ConsoleMessage["type"]>;
  * ]);
  * ```
  */
-declare class ConsoleCaptor {
+export declare class ConsoleCaptor {
   private readonly page;
   private readonly consoleListener;
   /**
@@ -112,6 +112,21 @@ declare class ConsoleCaptor {
    * The already captured {@link messages} are kept.
    */
   stopCapture(): void;
+  /**
+   * Remove all captured {@link messages}.
+   *
+   * @example
+   * ```ts
+   * captor.startCapture();
+   *
+   * await page.goto("/users");
+   * captor.clearMessages();
+   *
+   * await page.getByRole("button", { name: "Only enabled" }).click();
+   * expect(captor.messages).toHaveLength(1);
+   * ```
+   */
+  clearMessages(): void;
   /**
    * Collect the console messages reported while the callback runs.
    *
@@ -156,7 +171,7 @@ declare class ConsoleCaptor {
  * );
  * ```
  */
-declare function captureConsole(page: Page, levelOrFilter?: ConsoleMessageLevel | Array<ConsoleMessageLevel> | ConsoleMessageFilter): ConsoleCaptor;
+export declare function captureConsole(page: Page, levelOrFilter?: ConsoleMessageLevel | Array<ConsoleMessageLevel> | ConsoleMessageFilter): ConsoleCaptor;
 /**
  * Tests whether the given console message has one of the specified log levels.
  *
@@ -166,7 +181,7 @@ declare function captureConsole(page: Page, levelOrFilter?: ConsoleMessageLevel
  * @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;
+export declare function hasLogLevel(message: ConsoleMessage, ...level: Array<ConsoleMessageLevel>): boolean;
 //#endregion
 //#region src/api/route-interceptor/filter.d.ts
 /**
@@ -196,7 +211,7 @@ interface RouteFilter {
  *   });
  * ```
  */
-declare function matchPath(pattern: RegExp | string): RouteFilter;
+export declare function matchPath(pattern: RegExp | string): RouteFilter;
 //#endregion
 //#region src/api/route-interceptor/response-handler.d.ts
 /**
@@ -221,7 +236,7 @@ type ResponseHandler = (response: APIResponse) => Promise<FulfillOptions> | Fulf
  *   });
  * ```
  */
-declare function modifyJsonBody<T>(modifier: (body: T) => T): ResponseHandler;
+export declare function modifyJsonBody<T>(modifier: (body: T) => T): ResponseHandler;
 /**
  * Helper to create a {@link ResponseHandler} that modifies the response body as a plaintext string.
  *
@@ -237,7 +252,7 @@ declare function modifyJsonBody<T>(modifier: (body: T) => T): ResponseHandler;
  *   });
  * ```
  */
-declare function modifyTextBody(modifier: (body: string) => string): ResponseHandler;
+export declare function modifyTextBody(modifier: (body: string) => string): ResponseHandler;
 //#endregion
 //#region src/api/route-interceptor/interceptor.d.ts
 type Action<T> = () => Promise<T> | T;
@@ -245,7 +260,7 @@ type FulfillOptions = Parameters<Route["fulfill"]>[0];
 /**
  * Entrypoint to create various network interceptors using the {@link Page#route} API.
  */
-declare class RouteInterceptor {
+export declare class RouteInterceptor {
   readonly page: Page;
   readonly filter: RouteFilter;
   constructor(page: Page, filter: RouteFilter);
@@ -383,7 +398,7 @@ declare class ExecutableRouteInterceptor {
  *   });
  * ```
  */
-declare function interceptRoute(page: Page, filter: RouteFilter): RouteInterceptor;
+export declare function interceptRoute(page: Page, filter: RouteFilter): RouteInterceptor;
 /**
  * Base class to build re-usable route interceptors.
  *
@@ -413,7 +428,7 @@ declare function interceptRoute(page: Page, filter: RouteFilter): RouteIntercept
  * });
  * ```
  */
-declare class RouteInterceptorFixture {
+export declare class RouteInterceptorFixture {
   private readonly page;
   constructor(page: Page);
   /**
@@ -445,7 +460,42 @@ declare class RouteInterceptorFixture {
  * @returns The absolute path to the resolved location
  * @throws If no package root can be found
  */
-declare function resolveFromPackageRoot(...paths: Array<string>): string;
+export declare function resolveFromPackageRoot(...paths: Array<string>): string;
+//#endregion
+//#region src/page-object-model/locator-extensions.d.ts
+type RoleLocators = Record<Role, RoleLocator>;
+interface RoleLocator {
+  (options?: RoleLocatorOptions): Locator;
+  (name: string | RegExp, options?: RoleLocatorOptions): Locator;
+}
+type RoleLocatorOptions = Omit<GetByRoleOptions, "name">;
+type Role = Parameters<Locator["getByRole"]>[0];
+type GetByRoleOptions = Parameters<Locator["getByRole"]>[1];
+/**
+ * Creates a set of locator functions for every ARIA role, so tests don't
+ * have to repeat `getByRole` and its role string throughout a page object.
+ *
+ * Every generated locator applies `exact: true` by default, keeping name
+ * matches from accidentally matching unrelated elements with a similar
+ * accessible name. This can be overridden per call through `options`, or
+ * replaced entirely for every locator by passing a custom `defaultOptions`.
+ *
+ * The accessible name can be omitted when an element should be located by
+ * role alone, in which case `options` can be passed as the first argument.
+ *
+ * @param locator - The page or locator to scope the role locators to
+ * @param defaultOptions - Optional. Options applied to every generated locator, overridden by per-call options; defaults to `{ exact: true }`
+ * @returns A `RoleLocators` object with one locator function per ARIA role
+ *
+ * @example
+ * ```ts
+ * const { button, textbox } = roleLocators(page);
+ *
+ * await textbox("Email").fill("user@example.com");
+ * await button("Submit").click();
+ * ```
+ */
+export declare function roleLocators(locator: Pick<Locator, "getByRole">, defaultOptions?: GetByRoleOptions): RoleLocators;
 //#endregion
 //#region src/normalizers/mask-base-url.d.ts
 /**
@@ -454,7 +504,7 @@ declare function resolveFromPackageRoot(...paths: Array<string>): string;
  *
  * @param baseURL - Base URL to mask; if `undefined`, values are left unchanged
  */
-declare function maskBaseURL<TValue>(baseURL: string | undefined): Normalizer<TValue>;
+export declare function maskBaseURL<TValue>(baseURL: string | undefined): Normalizer<TValue>;
 //#endregion
 //#region src/normalizers/masked-value.d.ts
 /**
@@ -463,14 +513,14 @@ declare function maskBaseURL<TValue>(baseURL: string | undefined): Normalizer<TV
  *
  * @param name - Name of the masked value
  */
-declare function maskedValue(name: string): string;
+export declare function maskedValue(name: string): string;
 /**
  * Creates a factory for indexed masked placeholders, e.g. `[USER_1]`.
  *
  * @param name - Name of the masked value
  * @returns A function mapping an index to a masked placeholder
  */
-declare function maskedValueWithIndex(name: string): (index: number) => string;
+export declare function maskedValueWithIndex(name: string): (index: number) => string;
 //#endregion
 //#region src/types/playwright.d.ts
 /**
@@ -479,4 +529,4 @@ declare function maskedValueWithIndex(name: string): (index: number) => string;
  */
 type PlaywrightTarget = Page | Locator;
 //#endregion
-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 };
+export type { ConsoleMessageFilter, ConsoleMessageLevel, HttpMethod, PlaywrightTarget, ResponseHandler, RoleLocators, RouteFilter };

package/dist/index.mjs

@@ -148,6 +148,23 @@ var ConsoleCaptor = class {
 		this.page.off("console", this.consoleListener);
 	}
 	/**
+	* Remove all captured {@link messages}.
+	*
+	* @example
+	* ```ts
+	* captor.startCapture();
+	*
+	* await page.goto("/users");
+	* captor.clearMessages();
+	*
+	* await page.getByRole("button", { name: "Only enabled" }).click();
+	* expect(captor.messages).toHaveLength(1);
+	* ```
+	*/
+	clearMessages() {
+		this.messages.length = 0;
+	}
+	/**
 	* Collect the console messages reported while the callback runs.
 	*
 	* The capturing is stopped once the action has finished, even if it throws.
@@ -592,6 +609,133 @@ function resolveFromPackageRoot(...paths) {
 	return path.resolve(packageDir, ...paths);
 }
 //#endregion
+//#region src/page-object-model/locator-extensions.ts
+const ROLES = [
+	"alert",
+	"alertdialog",
+	"application",
+	"article",
+	"banner",
+	"blockquote",
+	"button",
+	"caption",
+	"cell",
+	"checkbox",
+	"code",
+	"columnheader",
+	"combobox",
+	"complementary",
+	"contentinfo",
+	"definition",
+	"deletion",
+	"dialog",
+	"directory",
+	"document",
+	"emphasis",
+	"feed",
+	"figure",
+	"form",
+	"generic",
+	"grid",
+	"gridcell",
+	"group",
+	"heading",
+	"img",
+	"insertion",
+	"link",
+	"list",
+	"listbox",
+	"listitem",
+	"log",
+	"main",
+	"marquee",
+	"math",
+	"meter",
+	"menu",
+	"menubar",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"navigation",
+	"none",
+	"note",
+	"option",
+	"paragraph",
+	"presentation",
+	"progressbar",
+	"radio",
+	"radiogroup",
+	"region",
+	"row",
+	"rowgroup",
+	"rowheader",
+	"scrollbar",
+	"search",
+	"searchbox",
+	"separator",
+	"slider",
+	"spinbutton",
+	"status",
+	"strong",
+	"subscript",
+	"superscript",
+	"switch",
+	"tab",
+	"table",
+	"tablist",
+	"tabpanel",
+	"term",
+	"textbox",
+	"time",
+	"timer",
+	"toolbar",
+	"tooltip",
+	"tree",
+	"treegrid",
+	"treeitem"
+];
+const DEFAULT_OPTIONS = { exact: true };
+/**
+* Creates a set of locator functions for every ARIA role, so tests don't
+* have to repeat `getByRole` and its role string throughout a page object.
+*
+* Every generated locator applies `exact: true` by default, keeping name
+* matches from accidentally matching unrelated elements with a similar
+* accessible name. This can be overridden per call through `options`, or
+* replaced entirely for every locator by passing a custom `defaultOptions`.
+*
+* The accessible name can be omitted when an element should be located by
+* role alone, in which case `options` can be passed as the first argument.
+*
+* @param locator - The page or locator to scope the role locators to
+* @param defaultOptions - Optional. Options applied to every generated locator, overridden by per-call options; defaults to `{ exact: true }`
+* @returns A `RoleLocators` object with one locator function per ARIA role
+*
+* @example
+* ```ts
+* const { button, textbox } = roleLocators(page);
+*
+* await textbox("Email").fill("user@example.com");
+* await button("Submit").click();
+* ```
+*/
+function roleLocators(locator, defaultOptions = DEFAULT_OPTIONS) {
+	function getByRole(role) {
+		return (nameOrOptions, options) => {
+			if (typeof nameOrOptions === "string" || nameOrOptions instanceof RegExp) return locator.getByRole(role, {
+				name: nameOrOptions,
+				...defaultOptions,
+				...options
+			});
+			return locator.getByRole(role, {
+				...defaultOptions,
+				...nameOrOptions
+			});
+		};
+	}
+	return Object.fromEntries(ROLES.map((role) => [role, getByRole(role)]));
+}
+//#endregion
 //#region src/normalizers/masked-value.ts
 /**
 * Formats a name as a masked placeholder, e.g. `maskedValue("base url")`
@@ -627,4 +771,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { ConsoleCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, createFetchAdapter, hasLogLevel, 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, roleLocators };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/playwright-utils",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",
@@ -33,30 +33,29 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
-    "@changesets/cli": "3.0.1",
-    "@cronn/element-snapshot": "0.28.0",
-    "@cronn/playwright-file-snapshots": "2.2.1",
-    "@playwright/test": "1.62.1",
-    "@types/node": "24.13.3",
+    "@changesets/cli": "3.0.2",
+    "@cronn/element-snapshot": "0.30.0",
+    "@cronn/playwright-file-snapshots": "2.2.2",
+    "@playwright/test": "1.63.0",
+    "@types/node": "24.13.4",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.9.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "eslint": "10.10.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.2",
     "eslint-plugin-unused-imports": "4.4.1",
-    "knip": "6.33.0",
-    "oxc-minify": "0.147.0",
-    "oxfmt": "0.65.0",
+    "knip": "6.35.1",
+    "oxc-minify": "0.149.0",
+    "oxfmt": "0.67.0",
     "publint": "0.3.24",
     "rimraf": "6.1.3",
-    "tsdown": "0.22.14",
+    "tsdown": "0.23.0",
     "turbo": "2.10.12",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "8.68.0",
-    "vitepress": "2.0.0-alpha.19",
+    "typescript-eslint": "8.70.0",
+    "vitepress": "2.0.0-alpha.20",
     "vitepress-plugin-group-icons": "1.7.6",
-    "vitest": "4.1.11",
-    "node": "runtime:24.20.0"
+    "vitest": "5.0.0"
   },
   "peerDependencies": {
     "@cronn/playwright-file-snapshots": "^2",
@@ -65,12 +64,12 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "11.25.0",
+      "version": "12.5.1",
       "onFail": "download"
     },
     "runtime": {
       "name": "node",
-      "version": "24.20.0",
+      "version": "24.21.0",
       "onFail": "download"
     }
   },