pw-core 1.2.0 → 1.3.0

package/dist/page/types/proxy-methods.d.ts

@@ -1,60 +1,75 @@
 import { Locator } from '@playwright/test';
-import type { PageKeys, ChainedKeys } from '../config';
-/**
- * Playwright Locator methods proxied onto the page object.
- * Each method resolves a config key (or Locator) as the first argument.
- *
- * @example
- * ```ts
- * await page.click('submit');
- * await page.fill('username', 'alice', { nth: 1 });
- * ```
- *
- * pw-core adds `nth` to options — targets a specific match when multiple elements resolve.
- */
-type ProxyKeys = 'click' | 'dblclick' | 'hover' | 'focus' | 'blur' | 'check' | 'uncheck' | 'clear' | 'waitFor' | 'isChecked' | 'isDisabled' | 'isVisible' | 'textContent' | 'innerText' | 'allInnerTexts' | 'allTextContents' | 'count' | 'scrollIntoViewIfNeeded' | 'boundingBox' | 'press' | 'pressSequentially' | 'selectOption' | 'setInputFiles' | 'getAttribute';
-type ModifyProxyArgs<Args extends any[]> = Args extends [] ? [options?: {
-    nth?: number;
-    hasText?: string | RegExp;
-}] : Args extends [any, any?] ? [Args[0], (Exclude<Args[1], undefined> & {
-    nth?: number;
-    hasText?: string | RegExp;
-})?] : Args extends [any?] ? Exclude<Args[0], undefined> extends object ? [(Exclude<Args[0], undefined> & {
-    nth?: number;
-    hasText?: string | RegExp;
-})?] : [Exclude<Args[0], undefined>, options?: {
-    nth?: number;
-    hasText?: string | RegExp;
-}] : [options?: {
-    nth?: number;
-    hasText?: string | RegExp;
-}];
-type BaseProxyLocatorMethods<T> = {
-    [K in keyof Locator as K extends ProxyKeys ? K : never]: (target: PageKeys<T> | ChainedKeys<T> | Locator, ...args: ModifyProxyArgs<Parameters<Locator[K]>>) => ReturnType<Locator[K]>;
-};
-/**
- * Playwright Locator methods proxied onto the page object.
- * Each method resolves a config key (or Locator) as the first argument.
- *
- * @example
- * ```ts
- * await page.click('submit');
- * await page.fill('username', 'alice', { nth: 1 });
- * ```
- *
- * pw-core adds `nth` and `hasText` to options — targets a specific match when multiple elements resolve.
- */
-export interface ProxyLocatorMethods<T> extends BaseProxyLocatorMethods<T> {
+import type { PageKeys, CheckableLocatorKeys, CheckboxLocatorKeys, EditableLocatorKeys, SelectableLocatorKeys, ModifyOptionsForTarget } from '../config';
+export interface ProxyLocatorMethods<T> {
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-click Locator.click} */
+    click<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['click']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-dblclick Locator.dblclick} */
+    dblclick<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['dblclick']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-hover Locator.hover} */
+    hover<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['hover']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-focus Locator.focus} */
+    focus<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['focus']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-blur Locator.blur} */
+    blur<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['blur']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-check Locator.check} */
+    check<Target extends CheckableLocatorKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['check']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-uncheck Locator.uncheck} */
+    uncheck<Target extends CheckboxLocatorKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['uncheck']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-clear Locator.clear} */
+    clear<Target extends EditableLocatorKeys<T> | (string & {}) | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['clear']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-wait-for Locator.waitFor} */
+    waitFor<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['waitFor']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-is-checked Locator.isChecked} */
+    isChecked<Target extends CheckableLocatorKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['isChecked']>[0]>): Promise<boolean>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-is-disabled Locator.isDisabled} */
+    isDisabled<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['isDisabled']>[0]>): Promise<boolean>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-is-visible Locator.isVisible} */
+    isVisible<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['isVisible']>[0]>): Promise<boolean>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-text-content Locator.textContent} */
+    textContent<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['textContent']>[0]>): Promise<string | null>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-inner-text Locator.innerText} */
+    innerText<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['innerText']>[0]>): Promise<string>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-all-inner-texts Locator.allInnerTexts} */
+    allInnerTexts<Target extends PageKeys<T> | Locator>(target: Target): Promise<string[]>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-all-text-contents Locator.allTextContents} */
+    allTextContents<Target extends PageKeys<T> | Locator>(target: Target): Promise<string[]>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-count Locator.count} */
+    count<Target extends PageKeys<T> | Locator>(target: Target): Promise<number>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-scroll-into-view-if-needed Locator.scrollIntoViewIfNeeded} */
+    scrollIntoViewIfNeeded<Target extends PageKeys<T> | Locator>(target: Target, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['scrollIntoViewIfNeeded']>[0]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-bounding-box Locator.boundingBox} */
+    boundingBox<Target extends PageKeys<T> | Locator>(target: Target): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-press Locator.press} */
+    press<Target extends EditableLocatorKeys<T> | (string & {}) | Locator>(target: Target, key: string, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['press']>[1]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-press-sequentially Locator.pressSequentially} */
+    pressSequentially<Target extends EditableLocatorKeys<T> | (string & {}) | Locator>(target: Target, value: string, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['pressSequentially']>[1]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-select-option Locator.selectOption} */
+    selectOption<Target extends SelectableLocatorKeys<T> | (string & {}) | Locator>(target: Target, values: string | string[] | {
+        value?: string;
+        label?: string;
+        index?: number;
+    } | null, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['selectOption']>[1]>): Promise<string[]>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-set-input-files Locator.setInputFiles} */
+    setInputFiles<Target extends PageKeys<T> | Locator>(target: Target, files: string | string[] | {
+        name: string;
+        mimeType: string;
+        buffer: Buffer;
+    } | {
+        name: string;
+        mimeType: string;
+        buffer: Buffer;
+    }[], options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['setInputFiles']>[1]>): Promise<void>;
+    /** @see {@link https://playwright.dev/docs/api/class-locator#locator-get-attribute Locator.getAttribute} */
+    getAttribute<Target extends PageKeys<T> | Locator>(target: Target, name: string, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['getAttribute']>[1]>): Promise<string | null>;
     /** @see {@link https://playwright.dev/docs/api/class-locator#locator-fill Locator.fill} */
-    fill(target: PageKeys<T> | ChainedKeys<T> | Locator, value: string, options?: Parameters<Locator['fill']>[1] & {
-        nth?: number;
-        hasText?: string | RegExp;
+    fill<Target extends EditableLocatorKeys<T> | (string & {}) | Locator>(target: Target, value: string, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['fill']>[1]> & {
         mask?: boolean;
     }): Promise<void>;
     /** @see {@link https://playwright.dev/docs/api/class-locator#locator-drag-to Locator.dragTo} */
-    dragTo(target: PageKeys<T> | ChainedKeys<T> | Locator, destination: PageKeys<T> | ChainedKeys<T> | Locator, options?: Parameters<Locator['dragTo']>[1] & {
-        nth?: number;
-        hasText?: string | RegExp;
-    }): Promise<void>;
+    dragTo<Target extends PageKeys<T> | Locator>(target: Target, destination: PageKeys<T> | Locator, options?: ModifyOptionsForTarget<T, Target, Parameters<Locator['dragTo']>[1]>): Promise<void>;
 }
-export {};

package/dist/page/types/validation.d.ts

@@ -18,5 +18,52 @@ export type MissingInTestId<TestId extends string, Placeholders extends string>
  * (e.g. on the wrong value or unknown key) instead of marking the entire object as invalid.
  */
 export type ValidateDynamicEntryProperties<Pattern extends string, Entry, TargetKey extends 'testId' | 'selector'> = {
-    [Key in (keyof Entry | ExtractPlaceholders<Pattern> | TargetKey)]: Key extends TargetKey ? Entry extends Record<TargetKey, infer TPat> ? TPat extends string ? [MissingInTestId<TPat, ExtractPlaceholders<Pattern>>] extends [never] ? string : `Error: ${TargetKey} must contain all placeholder names` : `Error: ${TargetKey} must be a string` : `Error: Dynamic entry must include a ${TargetKey} property` : Key extends ExtractPlaceholders<Pattern> ? Key extends keyof Entry ? Entry[Key] extends readonly string[] ? readonly string[] : `Error: Placeholder key must be an array: ${Key & string}` : `Error: Missing placeholder key: ${Key & string}` : `Error: Only placeholder keys and '${TargetKey}' are allowed`;
+    [Key in keyof Entry | ExtractPlaceholders<Pattern> | TargetKey]: Key extends TargetKey ? Entry extends Record<TargetKey, infer TPat> ? TPat extends string ? [MissingInTestId<TPat, ExtractPlaceholders<Pattern>>] extends [never] ? [Exclude<ExtractPlaceholders<TPat>, ExtractPlaceholders<Pattern>>] extends [never] ? string : {
+        [P in `Error: ${TargetKey} contains unknown placeholder(s): ${Exclude<ExtractPlaceholders<TPat>, ExtractPlaceholders<Pattern>> & string}`]: never;
+    } : {
+        [P in `Error: ${TargetKey} must contain all placeholder names: missing ${MissingInTestId<TPat, ExtractPlaceholders<Pattern>> & string}`]: never;
+    } : {
+        [P in `Error: ${TargetKey} must be a string`]: never;
+    } : {
+        [P in `Error: Dynamic entry must include a ${TargetKey} property`]: never;
+    } : Key extends ExtractPlaceholders<Pattern> ? Key extends keyof Entry ? Entry[Key] extends readonly string[] ? readonly string[] : {
+        [P in `Error: Placeholder key must be an array: ${Key & string}`]: never;
+    } : {
+        [P in `Error: Missing placeholder key: ${Key & string}`]: never;
+    } : {
+        [P in `Error: Only placeholder keys and '${TargetKey}' are allowed`]: never;
+    };
+};
+/**
+ * Replaces every `{Name}` placeholder in `Pattern` with `Capitalize<Value>`
+ * where `Value` is drawn from the corresponding array in `Entry`.
+ * Template-literal unions distribute automatically, producing the full cartesian product.
+ */
+export type ReplacePattern<Pattern extends string, Entry> = Pattern extends `${infer Before}{${infer Name}}${infer After}` ? Name extends keyof Entry ? Entry[Name] extends readonly string[] ? `${Before}${Capitalize<Entry[Name][number]>}${ReplacePattern<After, Entry> & string}` : never : never : Pattern;
+/**
+ * Expands a dynamic key pattern into the union of all concrete (camelCased) keys.
+ */
+export type ExpandDynamicKey<Pattern extends string, Entry> = Uncapitalize<ReplacePattern<Pattern, Entry>>;
+/**
+ * Resolves every key in a testIds record:
+ * - string values → the key itself (static locator)
+ * - object values → the expanded dynamic key union
+ */
+export type ResolvedTestIdKeys<I> = {
+    [K in keyof I & string]: I[K] extends string ? K : ExpandDynamicKey<K, I[K]>;
+}[keyof I & string];
+export type AllExpandedTestIdKeys<I> = {
+    [P in keyof I & string]: I[P] extends string ? P : ExpandDynamicKey<P, I[P]>;
+}[keyof I & string];
+export type AllOtherExpandedTestIdKeys<I, K extends keyof I> = {
+    [P in Exclude<keyof I, K> & string]: I[P] extends string ? P : ExpandDynamicKey<P, I[P]>;
+}[Exclude<keyof I, K> & string];
+export type ValidateTestIds<I, TargetKey extends 'testId' | 'selector', S> = {
+    [K in keyof I & string]: I[K] extends string ? K extends AllOtherExpandedTestIdKeys<I, K> | AllExpandedTestIdKeys<S> ? {
+        [P in `Error: Duplicate key "${K}" is defined in multiple entries`]: never;
+    } : string : ExpandDynamicKey<K, I[K]> & (AllOtherExpandedTestIdKeys<I, K> | AllExpandedTestIdKeys<S>) extends never ? K extends `${string}{${string}}${string}` ? HasDuplicatePlaceholders<K> extends true ? {
+        [P in 'Error: Pattern contains duplicate placeholders']: never;
+    } : ValidateDynamicEntryProperties<K, I[K], TargetKey> : I[K] : {
+        [P in `Error: Dynamic locator "${K}" expands to duplicate key(s): ${ExpandDynamicKey<K, I[K]> & (AllOtherExpandedTestIdKeys<I, K> | AllExpandedTestIdKeys<S>) & string}`]: never;
+    };
 };

package/dist/page/utils/caller-location.js

@@ -6,7 +6,7 @@ exports.getCallerLocation = getCallerLocation;
 // directly to the user's project files instead of showing internal pw-core library paths.
 const originalPrepare = Error.prepareStackTrace;
 Error.prepareStackTrace = (err, stack) => {
-    const filteredStack = stack.filter(frame => {
+    const filteredStack = stack.filter((frame) => {
         const file = frame.getFileName();
         if (!file)
             return true;
@@ -27,14 +27,18 @@ Error.prepareStackTrace = (err, stack) => {
         }
     }
     const errString = err.toString ? err.toString() : String(err);
-    return errString + '\n' + filteredStack.map(frame => {
-        try {
-            return '    at ' + frame.toString();
-        }
-        catch {
-            return '    at <unknown>';
-        }
-    }).join('\n');
+    return (errString +
+        '\n' +
+        filteredStack
+            .map((frame) => {
+            try {
+                return '    at ' + frame.toString();
+            }
+            catch {
+                return '    at <unknown>';
+            }
+        })
+            .join('\n'));
 };
 function getCallerLocation() {
     const originalPrepareStackTrace = Error.prepareStackTrace;

package/dist/page/utils/formatter.js

@@ -37,7 +37,10 @@ function formatStepDescription(methodName, target, args) {
     if (methodName === 'uncheck')
         return `Uncheck "${targetStr}"`;
     const formattedMethod = methodName.charAt(0).toUpperCase() + methodName.slice(1);
-    const cleanArgs = args.filter(a => typeof a === 'string' || typeof a === 'number').map(a => `"${a}"`).join(', ');
+    const cleanArgs = args
+        .filter((a) => typeof a === 'string' || typeof a === 'number')
+        .map((a) => `"${a}"`)
+        .join(', ');
     return `${formattedMethod} "${targetStr}"${cleanArgs ? ' with ' + cleanArgs : ''}`;
 }
 function formatAssertionDescription(target, matcherName, isNegated, args) {
@@ -49,8 +52,8 @@ function formatAssertionDescription(target, matcherName, isNegated, args) {
         toBeEnabled: isNegated ? 'is not enabled' : 'is enabled',
         toBeDisabled: isNegated ? 'is not disabled' : 'is disabled',
         toBeChecked: isNegated ? 'is not checked' : 'is checked',
-        toHaveText: (isNegated ? 'does not have text "' : 'has text "') + args.map(a => String(a)).join(', ') + '"',
-        toContainText: (isNegated ? 'does not contain "' : 'contains "') + args.map(a => String(a)).join(', ') + '"',
+        toHaveText: (isNegated ? 'does not have text "' : 'has text "') + args.map((a) => String(a)).join(', ') + '"',
+        toContainText: (isNegated ? 'does not contain "' : 'contains "') + args.map((a) => String(a)).join(', ') + '"',
         toHaveCount: (isNegated ? 'does not have count of "' : 'has count of "') + args[0] + '"'
     };
     return `${prefix} ${matcherMap[matcherName] || `${isNegated ? 'not ' : ''}${matcherName}`}`;

package/dist/types/methods.d.ts

@@ -0,0 +1,4 @@
+import { zeroArgMethodsList, oneArgMethodsList } from '../constants/methods';
+export type AllowedZeroArgMethods = (typeof zeroArgMethodsList)[number];
+export type AllowedOneArgMethods = (typeof oneArgMethodsList)[number];
+export type AllowedMethodKeys = AllowedZeroArgMethods | AllowedOneArgMethods;

package/dist/types/methods.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/strategies.d.ts

@@ -0,0 +1,17 @@
+import { rolesList, strategyList } from '../constants/strategies';
+export type RoleType = (typeof rolesList)[number];
+export type StrategyType = (typeof strategyList)[number];
+export type PlaywrightRoleOptions = {
+    exact?: boolean;
+    checked?: boolean;
+    disabled?: boolean;
+    expanded?: boolean;
+    includeHidden?: boolean;
+    level?: number;
+    pressed?: boolean;
+    selected?: boolean;
+};
+export type PlaywrightTextOptions = {
+    exact?: boolean;
+};
+export type LocatorStrategyOptions<S extends string> = S extends RoleType ? PlaywrightRoleOptions : S extends 'text' | 'label' | 'title' | 'placeholder' | 'altText' ? PlaywrightTextOptions : {};

package/dist/types/strategies.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "workspaces": [
     "examples",
     "create-pw-core"
@@ -23,6 +23,9 @@
     "typescript"
   ],
   "main": "./dist/index.js",
+  "bin": {
+    "pw-core": "./dist/cli.js"
+  },
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
@@ -58,10 +61,14 @@
   "devDependencies": {
     "@playwright/test": "^1.61.0",
     "@types/node": "^20.11.0",
+    "prettier": "^3.9.4",
     "rimraf": "^6.0.1",
     "typescript": "^5.3.3"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "playwright-core": "^1.61.1"
   }
 }