@cronn/playwright-utils 0.7.0 → 0.8.0

package/dist/index.d.mts

@@ -606,7 +606,64 @@ export declare class RouteInterceptorFixture {
  */
 export declare function resolveFromPackageRoot(...paths: Array<string>): string;
 //#endregion
-//#region src/page-object-model/locator-extensions.d.ts
+//#region src/page-object-model/form-filler.d.ts
+interface Fillable<TValue> {
+  fill: Filler<TValue>;
+}
+type Filler<TValue> = (value: TValue) => Promise<void>;
+type FormFields<TData> = { [K in keyof TData]-?: Fillable<Exclude<TData[K], undefined>> | Filler<Exclude<TData[K], undefined>>; };
+/**
+ * Creates a filler function that fills a form declaratively from a data
+ * object, e.g. as the `fill` method of a page object.
+ *
+ * Each key of `fields` maps a key of the data to a form input: either an
+ * object with a `fill` method (such as a `Locator` or a nested page object) or
+ * a filler function receiving the value. Fields are filled one after another
+ * in the order of the keys in `fields`, and fields whose value is `undefined`
+ * are skipped.
+ *
+ * The type of the data is either given explicitly as type argument or inferred
+ * from `fields`. When inferred, filler functions need an explicit parameter
+ * type, otherwise their value is `unknown`. In both cases, the returned
+ * function accepts partial data.
+ *
+ * As the returned function is a filler itself, it can be used as a field of
+ * another form filler to fill nested data.
+ *
+ * @param fields - Mapping from each key of the data to the input to fill
+ * @returns A function filling the form with the given data
+ * @example
+ * ```ts
+ * const { checkbox, textbox } = roleLocators(page);
+ *
+ * const registrationForm = {
+ *   fill: formFiller<Registration>({
+ *     name: textbox("Name"),
+ *     acceptTerms: (accepted) => checkbox("Accept terms").setChecked(accepted),
+ *   }),
+ * };
+ * ```
+ */
+export declare function formFiller<TData extends object>(fields: FormFields<TData>): Filler<Partial<TData>>;
+//#endregion
+//#region src/page-object-model/extend-locator.d.ts
+type WithoutLocatorKeys = Partial<Record<Exclude<keyof Locator, "toString">, never>>;
+type ExtendedLocator<TExtensions extends WithoutLocatorKeys> = Locator & TExtensions;
+/**
+ * Extends a `Locator` with custom properties and functions while retaining the full `Locator` API.
+ *
+ * Extensions must not override members of `Locator`. Locators derived from the extended locator
+ * (e.g. via `first()`, `filter()` or `locator()`) are plain `Locator`s without the extensions.
+ *
+ * Methods of `Locator` are bound to the original locator on every access, so accessing the same method
+ * twice returns different function instances (e.g. `extended.click !== extended.click`).
+ *
+ * @param locator The locator to extend
+ * @param createExtensions Creates the extensions, receiving the original locator
+ */
+export declare function extendLocator<TExtensions extends object & WithoutLocatorKeys>(locator: Locator, createExtensions: (locator: Locator) => TExtensions): ExtendedLocator<TExtensions>;
+//#endregion
+//#region src/page-object-model/role-locators.d.ts
 type RoleLocators = Record<Role, RoleLocator>;
 interface RoleLocator {
   (options?: RoleLocatorOptions): Locator;
@@ -673,4 +730,4 @@ export declare function maskedValueWithIndex(name: string): (index: number) => s
  */
 type PlaywrightTarget = Page | Locator;
 //#endregion
-export type { ConsoleMessageFilter, ConsoleMessageLevel, CspFixtures, CspViolation, HttpMethod, PlaywrightTarget, ResponseHandler, RoleLocators, RouteFilter };
+export type { ConsoleMessageFilter, ConsoleMessageLevel, CspFixtures, CspViolation, ExtendedLocator, FormFields, HttpMethod, PlaywrightTarget, ResponseHandler, RoleLocators, RouteFilter };

package/dist/index.mjs

@@ -789,7 +789,81 @@ function resolveFromPackageRoot(...paths) {
 	return path.resolve(packageDir, ...paths);
 }
 //#endregion
-//#region src/page-object-model/locator-extensions.ts
+//#region src/page-object-model/form-filler.ts
+/**
+* Creates a filler function that fills a form declaratively from a data
+* object, e.g. as the `fill` method of a page object.
+*
+* Each key of `fields` maps a key of the data to a form input: either an
+* object with a `fill` method (such as a `Locator` or a nested page object) or
+* a filler function receiving the value. Fields are filled one after another
+* in the order of the keys in `fields`, and fields whose value is `undefined`
+* are skipped.
+*
+* The type of the data is either given explicitly as type argument or inferred
+* from `fields`. When inferred, filler functions need an explicit parameter
+* type, otherwise their value is `unknown`. In both cases, the returned
+* function accepts partial data.
+*
+* As the returned function is a filler itself, it can be used as a field of
+* another form filler to fill nested data.
+*
+* @param fields - Mapping from each key of the data to the input to fill
+* @returns A function filling the form with the given data
+* @example
+* ```ts
+* const { checkbox, textbox } = roleLocators(page);
+*
+* const registrationForm = {
+*   fill: formFiller<Registration>({
+*     name: textbox("Name"),
+*     acceptTerms: (accepted) => checkbox("Accept terms").setChecked(accepted),
+*   }),
+* };
+* ```
+*/
+function formFiller(fields) {
+	return async (data) => {
+		for (const [key, filler] of Object.entries(fields)) {
+			const value = data[key];
+			if (value === void 0) continue;
+			if (typeof filler === "function") await filler(value);
+			else await filler.fill(value);
+		}
+	};
+}
+//#endregion
+//#region src/page-object-model/extend-locator.ts
+/**
+* Extends a `Locator` with custom properties and functions while retaining the full `Locator` API.
+*
+* Extensions must not override members of `Locator`. Locators derived from the extended locator
+* (e.g. via `first()`, `filter()` or `locator()`) are plain `Locator`s without the extensions.
+*
+* Methods of `Locator` are bound to the original locator on every access, so accessing the same method
+* twice returns different function instances (e.g. `extended.click !== extended.click`).
+*
+* @param locator The locator to extend
+* @param createExtensions Creates the extensions, receiving the original locator
+*/
+function extendLocator(locator, createExtensions) {
+	const extensions = createExtensions(locator);
+	return new Proxy(locator, {
+		get(target, property) {
+			if (isOwnKeyOf(extensions, property)) return extensions[property];
+			const value = Reflect.get(target, property, target);
+			return typeof value === "function" && property !== "constructor" ? value.bind(target) : value;
+		},
+		has(target, property) {
+			return isOwnKeyOf(extensions, property) || Reflect.has(target, property);
+		}
+	});
+}
+function isOwnKeyOf(object, key) {
+	return Object.hasOwn(object, key);
+}
+//#endregion
+//#region src/page-object-model/role-locators.ts
 const ROLES = [
 	"alert",
 	"alertdialog",
@@ -951,4 +1025,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { ConsoleCaptor, CspCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, captureCspViolations, createFetchAdapter, cspFixtures, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, roleLocators };
+export { ConsoleCaptor, CspCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, captureCspViolations, createFetchAdapter, cspFixtures, extendLocator, formFiller, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, roleLocators };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/playwright-utils",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",
@@ -33,29 +33,29 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
-    "@changesets/cli": "3.0.2",
+    "@changesets/cli": "3.0.3",
     "@cronn/element-snapshot": "0.30.0",
     "@cronn/playwright-file-snapshots": "2.2.2",
     "@playwright/test": "1.63.0",
-    "@types/node": "24.13.4",
+    "@types/node": "24.19.0",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "5.0.0",
-    "eslint": "10.10.0",
+    "@vitest/coverage-v8": "5.0.2",
+    "eslint": "10.11.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.2",
     "eslint-plugin-unused-imports": "4.4.1",
-    "knip": "6.35.1",
-    "oxc-minify": "0.149.0",
-    "oxfmt": "0.67.0",
+    "knip": "6.38.0",
+    "oxc-minify": "0.151.0",
+    "oxfmt": "0.70.0",
     "publint": "0.3.24",
     "rimraf": "6.1.3",
     "tsdown": "0.23.0",
-    "turbo": "2.10.12",
+    "turbo": "2.11.5",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "8.70.0",
+    "typescript-eslint": "8.70.1",
     "vitepress": "2.0.0-alpha.20",
     "vitepress-plugin-group-icons": "1.7.6",
-    "vitest": "5.0.0"
+    "vitest": "5.0.2"
   },
   "peerDependencies": {
     "@cronn/playwright-file-snapshots": "^2",
@@ -64,7 +64,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.5.1",
+      "version": "12.9.1",
       "onFail": "download"
     },
     "runtime": {
@@ -90,9 +90,7 @@
     "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",