pw-core 0.0.1 → 0.0.3

package/README.md

@@ -6,17 +6,34 @@ A developer-first framework layer built on top of Playwright for creating readab
 
 ---
 
-## Installation
+## Documentation
+
+- **Online Documentation**: [qecore.github.io/pw-core](https://qecore.github.io/pw-core)
+- **Release Guide**: [releases/v1.0.0.md](./releases/v1.0.0.md)
+
+---
+
+## Installation & Setup
+
+### Quick Start (Recommended)
+To initialize a brand new test suite pre-configured with `pw-core`, run:
 
 ```bash
-npm install pw-core
+npm init pw-core
 ```
 
-### Requirements
+This will automatically:
+- Set up a clean folder structure with template examples in `src/pages` and `src/tests`
+- Create `playwright.config.ts` and `tsconfig.json` configurations
+- Install `pw-core`, `@playwright/test`, and `typescript` dependencies
+- Download required Playwright browser binaries
 
-- Existing Playwright project
-- TypeScript recommended
-- Compatible with supported Playwright versions defined by peer dependency requirements
+### Manual Installation
+If you want to add `pw-core` to an existing Playwright project, install it manually:
+
+```bash
+npm install pw-core
+```
 
 ---
 
@@ -34,546 +51,31 @@ npm install pw-core
 
 ---
 
-# Why pw-core?
-
-Most Playwright frameworks start small and manageable.
-
-As projects grow, they often become difficult to maintain:
-
-- Locators duplicated across files
-- Massive Page Objects
-- Repeated fixture definitions
-- Components recreated on every page
-- Multiple sources of truth
-- Inconsistent coding patterns
-
-The larger the framework becomes, the more expensive these problems become.
-
-`pw-core` solves this by introducing:
-
-- Configuration-driven pages
-- Typed Page Objects
-- Automatic Page Registry fixtures
-- Reusable Components
-- Chained Locators
-- Built-in Assertions
-- Browser Storage Helpers
-
----
-
-# Traditional Playwright vs pw-core
-
-## Traditional Approach
-
-```ts
-class LoginPage {
-  constructor(private page: Page) {}
-
-  username = this.page.getByTestId("username-input");
-  password = this.page.getByTestId("password-input");
-  loginButton = this.page.getByTestId("login-button");
-  errorMessage = this.page.getByTestId("login-error");
-}
-```
-
-Usage:
-
-```ts
-await loginPage.username.fill(user);
-await loginPage.password.fill(pass);
-await loginPage.loginButton.click();
-
-await expect(loginPage.errorMessage).toBeVisible();
-```
-
-Problems:
-
-- Locator definitions
-- Large Page Objects
-- Boilerplate code
-- Multiple maintenance points
-- Runtime locator mistakes
-
----
-
-## pw-core Approach
-
-```ts
-const config = createPageConfig({
-  url: "/login",
-
-  testIds: {
-    username: "username-input",
-    password: "password-input",
-    loginBtn: "login-button",
-    loginError: "login-error",
-  },
-});
-
-class LoginPage extends TypedPage<typeof config> {
-  constructor(page: Page) {
-    super(page, config);
-  }
-}
-```
-
-Usage:
-
-```ts
-await loginPage.fill("username", "admin");
-await loginPage.fill("password", "password");
-await loginPage.click("loginBtn");
-await login.verify("loginError");
-```
-
-Benefits:
-
-- Single source of truth
-- Strong typing
-- Less boilerplate
-- Cleaner tests
-- Easier maintenance
-
----
-
-# Single Source of Truth
-
-Everything begins with a page configuration.
-
-```ts
-const config = createPageConfig({
-  url: "/transactions",
-
-  testIds: {
-    table: "transactions-table",
-    next: "next-page",
-    prev: "prev-page",
-  },
-
-  selectors: {
-    pageTitle: "h1",
-  },
-});
-```
-
-This configuration owns:
-
-- URLs
-- testIds
-- selectors
-
-Everything else consumes this configuration.
-
-```ts
-await page.goto();
-
-await page.click("next");
-
-await page.verify("table");
-
-await page.verifyURL();
-```
-
-When a locator changes, update it once.
-
-Not across dozens of tests and page objects.
-
----
-
-# TypedPage
-
-`TypedPage` is the foundation of pw-core.
-
-It transforms page configurations into fully typed automation objects.
-
-```ts
-class SettingsPage extends TypedPage<typeof config> {
-  async toggleLogo() {
-    await this.click("logoToggle");
-  }
-}
-```
-
-Automatically provides:
-
-```ts
-await page.goto();
-
-await page.click("logoToggle");
-
-await page.fill("username", "admin");
-
-await page.check("rememberMe");
-
-await page.hover("profile");
-
-await page.textContent("message");
-
-await page.verify("submit");
-
-await page.verifyURL();
-```
-
-No locator declarations required.
-
----
-
-# Readable Assertions
-
-Traditional:
-
-```ts
-await expect(page.getByTestId("login-button")).toBeVisible();
-```
-
-pw-core:
-
-```ts
-await login.verify("loginBtn");
-```
-
-By default:
-
-```ts
-await login.verify("loginBtn");
-```
-
-is equivalent to:
-
-```ts
-await expect(page.getByTestId("login-button")).toBeVisible();
-```
-
-Custom assertions remain available:
-
-```ts
-await login.verify("loginBtn").toBeEnabled();
-
-await login.verify("errorMessage").toContainText("Invalid");
-```
-
----
-
-# Chained Locators
-
-Complex nested locators are common in large applications.
-
-Traditional:
-
-```ts
-await page
-  .getByTestId("transactions-table")
-  .getByTestId("transaction-row")
-  .nth(2)
-  .dblclick();
-```
-
-pw-core:
-
-```ts
-await transactions.dblclick("table.transactionRows", { nth: 2 });
-```
-
-Traditional:
-
-```ts
-await page
-  .locator('[data-testid="modal"]')
-  .locator('[data-testid="form"]')
-  .locator('[data-testid="submit"]')
-  .click();
-```
-
-pw-core:
-
-```ts
-await page.click("modal.form.submit");
-```
-
-Assertions work the same way:
-
-```ts
-await page.verify("table.transactionRows").toHaveCount(10);
-```
-
-Nested locator chains stay readable regardless of depth.
-
----
-
-# Components
-
-Most applications reuse the same UI patterns:
-
-- Tables
-- Sidebars
-- Filters
-- Menus
-- Forms
-- Modals
-
-Traditional frameworks often recreate these components repeatedly.
-
-```ts
-class UsersPage {
-  usersTable = ...
-}
-
-class OrdersPage {
-  ordersTable = ...
-}
-
-class ProductsPage {
-  productsTable = ...
-}
-```
-
-Same component.
-
-Different implementation.
-
-Duplicate maintenance.
-
----
-
-## Reusable Components
-
-With pw-core, components become first-class citizens.
-
-```ts
-export class TransactionsPage extends TypedPage<typeof config> {
-  constructor(page: Page) {
-    super(page, config);
-    this.transactionsTable = new Table<Transaction>(tableLocator);
-  }
-}
-```
-
-Use the same component across:
-
-- Users
-- Orders
-- Products
-- Reports
-
-Define once.
-
-Same methods across pages, Reuse everywhere.
-
-Exactly how frontend teams build reusable UI components.
-
----
-
-# Page Registry
-
-Not every page requires a custom Page Object.
-
-Many pages only contain:
-
-- URLs
-- testIds
-- selectors
-
-For those pages, use `createPageRegistry`.
-
-```ts
-import { createPageRegistry } from "pw-core/page";
-
-export const test = createPageRegistry({
-  loginPage: {
-    url: "/login",
-
-    testIds: {
-      username: "username-input",
-      password: "password-input",
-      submit: "login-button",
-    },
-  },
-});
-```
-
----
-
-## Automatic Fixtures
-
-Pages immediately become fixtures.
-
-```ts
-test("login", async ({ loginPage }) => {
-  await loginPage.fill("username", "admin");
-
-  await loginPage.fill("password", "password");
-
-  await loginPage.click("submit");
-});
-```
-
-No Page Object.
-
-No fixture setup.
-
-No boilerplate.
-
----
-
-# Extending Registry Pages
-
-As pages become more complex, you can extend them.
-
-```ts
-class LoginPage extends test.classes.loginPage {
-  async login() {
-    await this.fill("username", "admin");
-
-    await this.fill("password", "password");
-
-    await this.click("submit");
-  }
-}
-```
-
-Update the fixture:
-
-```ts
-export const test = registry.extend({
-  loginPage: LoginPage,
-});
-```
-
-Usage:
-
-```ts
-await loginPage.login();
-```
-
-Start simple.
-
-Extend only when needed.
-
----
-
-# AI-Friendly Automation
+## Available Custom Methods
 
-Most automation frameworks are inconsistent.
+The following custom methods are available on `TypedPage` objects:
 
-One page uses:
+### Navigation & Lifecycle
+- `goto(options?)`: Navigate to the configured page URL.
+- `reload(options?)`: Reload the current page.
+- `waitForLoadState(state?, options?)`: Wait for the page to reach the specified load state (e.g. `'load' | 'domcontentloaded' | 'networkidle'`).
+- `waitForURL(pattern?, options?)`: Wait for the page navigation to match the configured page URL or a custom pattern.
 
-```ts
-page.locator(...)
-```
+### Assertions
+- `verify(key, options?)`: Assertions chain wrapper (e.g. `await page.verify('submit').toBeVisible()`). Supports `nth` and `hasText` filtering.
+- `verifyURL(url?, options?)`: Assert the current URL matches the page configuration URL or a custom string/RegExp pattern.
+- `verifyTitle(title, options?)`: Assert the page title matches the expected title string or RegExp pattern.
+- `verifyHidden(key, options?)`: Shortcut assertion to verify a locator is hidden. Supports `nth` and `hasText` options.
+- `verifyEnabled(key, options?)`: Shortcut assertion to verify a locator is enabled. Supports `nth` and `hasText` options.
+- `verifyDisabled(key, options?)`: Shortcut assertion to verify a locator is disabled. Supports `nth` and `hasText` options.
 
-Another:
-
-```ts
-page.getByTestId(...)
-```
-
-Another:
-
-```ts
-page.getByRole(...)
-```
-
-Another:
-
-```ts
-page.locator(...).locator(...)
-```
-
-AI agents must understand every pattern.
-
-With pw-core:
-
-```ts
-page.click(...)
-page.fill(...)
-page.verify(...)
-page.locator(...)
-```
-
-Everything follows the same structure.
-
-Benefits:
-
-- Reduced context size
-- Reduced token usage
-- Better AI-generated automation
-- Easier reviews
-- Faster onboarding
+### Locators
+- `expect(key)`: Returns raw Playwright expectation: `expect(locator)`.
+- `resolveLocator(key, options?)`: Returns the raw Playwright Locator resolved from the page config. Options support `{ nth, hasText, raw }`.
+- `locator(key, options?)`: Returns a proxied, step-wrapped Playwright Locator. Options support `{ nth, hasText }`.
 
 ---
 
-# Package Overview
-
-| Import                    | Purpose                                                  |
-| ------------------------- | -------------------------------------------------------- |
-| `pw-core`                 | Browser storage helpers                                  |
-| `pw-core/page`            | TypedPage, Page Registry, assertions, page configuration |
-| `pw-core/component/table` | Reusable typed table component                           |
-
----
-
-# Documentation
-
-| Document             | Description                                            |
-| -------------------- | ------------------------------------------------------ |
-| `docs/page.md`       | TypedPage, Page Registry, locator chaining, assertions |
-| `docs/components.md` | Reusable UI components                                 |
-| `docs/helpers.md`    | Browser storage helpers                                |
-
----
-
-# When To Use TypedPage
-
-Use TypedPage when:
-
-- The page contains workflows
-- The page contains business logic
-- The page contains reusable actions
-- Multiple tests interact with the page
-
-Example:
-
-```ts
-await login.login();
-
-await settings.toggleLogo("enable");
-```
-
----
-
-# When To Use Page Registry
-
-Use Page Registry when:
-
-- Pages only contain locators
-- No custom methods are needed
-- You want automatic fixtures
-- You want minimal framework code
-
----
-
-# Summary
-
-pw-core is not a replacement for Playwright.
-
-It is an architectural layer designed to create:
-
-- Readable tests
-- Reusable components
-- Strongly typed pages
-- Automatic fixtures
-- Single source of truth configurations
-- AI-friendly automation frameworks
-- Scalable enterprise test suites
-
-The larger the framework becomes, the more value pw-core provides.
-
----
-
-More components, helpers, generators, and framework capabilities are planned.
-
-Stay tuned.
-
 ## License
 
 MIT

package/dist/page/actions/locator-actions.d.ts

@@ -2,9 +2,11 @@ import { Locator } from '@playwright/test';
 import { AllowedMethodKeys } from '../config';
 export declare function executeAction(prop: AllowedMethodKeys, resolveLocatorFn: (target: any, options?: {
     nth?: number;
+    hasText?: string | RegExp;
     raw?: boolean;
 }) => Locator, timeout: number | undefined, args: any[]): Promise<any>;
 export declare function defineActionMethods(instance: any, resolveLocatorFn: (target: any, options?: {
     nth?: number;
+    hasText?: string | RegExp;
     raw?: boolean;
 }) => Locator, timeout: number | undefined): void;

package/dist/page/actions/locator-actions.js

@@ -8,15 +8,21 @@ const formatter_1 = require("../utils/formatter");
 function executeAction(prop, resolveLocatorFn, timeout, args) {
     const [locatorKey, ...methodArgs] = args;
     let optNth = undefined;
+    let optHasText = undefined;
     const optionsIndex = (0, config_1.getOptionsArgumentIndex)(prop);
     if (optionsIndex !== -1 && methodArgs.length > optionsIndex) {
         const opts = methodArgs[optionsIndex];
-        if (opts && typeof opts === 'object' && 'nth' in opts) {
-            optNth = opts.nth;
+        if (opts && typeof opts === 'object') {
+            if ('nth' in opts) {
+                optNth = opts.nth;
+            }
+            if ('hasText' in opts) {
+                optHasText = opts.hasText;
+            }
         }
     }
     const isCount = prop === 'count';
-    const locator = resolveLocatorFn(locatorKey, { nth: optNth, raw: isCount });
+    const locator = resolveLocatorFn(locatorKey, { nth: optNth, hasText: optHasText, raw: isCount });
     const method = locator[prop];
     if (typeof method !== 'function') {
         throw new Error(`Property '${prop}' does not exist on Locator.`);

package/dist/page/assertions/verify-chain.d.ts

@@ -3,23 +3,29 @@ import { ChainedKeys, PageKeys } from '../config';
 export type VerifyOptions = {
     timeout?: number;
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 };
 type PlaywrightLocatorMatchers = ReturnType<typeof playwrightExpect<Locator>>;
 type ModifyMatcherArgs<Args extends any[]> = Args extends [] ? [options?: {
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 }] : Args extends [any, any?] ? [Args[0], (Exclude<Args[1], undefined> & {
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 })?] : Args extends [any?] ? Exclude<Args[0], undefined> extends object ? [(Exclude<Args[0], undefined> & {
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 })?] : [Exclude<Args[0], undefined>, options?: {
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 }] : [options?: {
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 }];
 type DynamicallyModifiedMatchers<T> = {
@@ -28,6 +34,7 @@ type DynamicallyModifiedMatchers<T> = {
 export type VerifyMatchers<T> = DynamicallyModifiedMatchers<T> & PromiseLike<void> & {
     (options?: Parameters<PlaywrightLocatorMatchers['toBeVisible']>[0] & {
         nth?: number;
+        hasText?: string | RegExp;
         message?: string;
     }): Promise<void>;
 };
@@ -38,14 +45,17 @@ export type AssertionsMethod<T> = {
     };
     verifyHidden(target: PageKeys<T> | ChainedKeys<T> | Locator, options?: Parameters<ReturnType<typeof playwrightExpect<Locator>>['toBeHidden']>[0] & {
         nth?: number;
+        hasText?: string | RegExp;
         message?: string;
     }): Promise<void>;
     verifyEnabled(target: PageKeys<T> | ChainedKeys<T> | Locator, options?: Parameters<ReturnType<typeof playwrightExpect<Locator>>['toBeEnabled']>[0] & {
         nth?: number;
+        hasText?: string | RegExp;
         message?: string;
     }): Promise<void>;
     verifyDisabled(target: PageKeys<T> | ChainedKeys<T> | Locator, options?: Parameters<ReturnType<typeof playwrightExpect<Locator>>['toBeDisabled']>[0] & {
         nth?: number;
+        hasText?: string | RegExp;
         message?: string;
     }): Promise<void>;
     expect(target: PageKeys<T> | ChainedKeys<T> | Locator, message?: string): ReturnType<typeof playwrightExpect<Locator>>;
@@ -58,6 +68,7 @@ export declare function createVerifyChain<T extends {
     selectors?: Record<string, string>;
 }>(resolveLocator: (target: any, options?: {
     nth?: number;
+    hasText?: string | RegExp;
     raw?: boolean;
 }) => Locator, target: PageKeys<T> | ChainedKeys<T> | Locator, verifyOptions: VerifyOptions | undefined, isSoft: boolean): VerifyMatchers<T>;
 export {};

package/dist/page/assertions/verify-chain.js

@@ -5,14 +5,16 @@ const test_1 = require("@playwright/test");
 const formatter_1 = require("../utils/formatter");
 function createVerifyChain(resolveLocator, target, verifyOptions, isSoft) {
     const defaultNth = verifyOptions?.nth;
+    const defaultHasText = verifyOptions?.hasText;
     const defaultMessage = verifyOptions?.message;
     const expectFn = isSoft ? test_1.expect.soft : test_1.expect;
     const createMatcher = (isNegated) => {
         const baseFn = async (options) => {
             const nth = options?.nth !== undefined ? options.nth : defaultNth;
+            const hasText = options?.hasText !== undefined ? options.hasText : defaultHasText;
             const stepName = options?.message ?? defaultMessage ?? (0, formatter_1.formatAssertionDescription)(target, 'toBeVisible', isNegated, [options]);
             await test_1.test.step(stepName, async () => {
-                const locator = resolveLocator(target, { nth });
+                const locator = resolveLocator(target, { nth, hasText });
                 const expectation = expectFn(locator, stepName);
                 const match = isNegated ? expectation.not : expectation;
                 await match.toBeVisible(options);
@@ -43,10 +45,11 @@ function createVerifyChain(resolveLocator, target, verifyOptions, isSoft) {
                     const valueArgs = lastIsOptions ? args.slice(0, args.length - 1) : args;
                     const options = lastIsOptions ? lastArg : undefined;
                     const nth = (options && 'nth' in options) ? options.nth : defaultNth;
+                    const hasText = (options && 'hasText' in options) ? options.hasText : defaultHasText;
                     const isHaveCount = prop === 'toHaveCount';
                     const stepName = options?.message ?? defaultMessage ?? (0, formatter_1.formatAssertionDescription)(target, String(prop), isNegated, valueArgs);
                     await test_1.test.step(stepName, async () => {
-                        const locator = resolveLocator(target, { nth, raw: isHaveCount });
+                        const locator = resolveLocator(target, { nth, hasText, raw: isHaveCount });
                         const expectation = expectFn(locator, stepName);
                         const match = isNegated ? expectation.not : expectation;
                         await match[prop](...args);

package/dist/page/assertions/verify-helpers.d.ts

@@ -1,22 +1,28 @@
 import { Locator, expect as playwrightExpect } from '@playwright/test';
 export declare function verifyHidden(resolveLocator: (target: any, options?: {
     nth?: number;
+    hasText?: string | RegExp;
     raw?: boolean;
 }) => Locator, target: any, options?: Parameters<ReturnType<typeof playwrightExpect<Locator>>['toBeHidden']>[0] & {
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 }): Promise<void>;
 export declare function verifyEnabled(resolveLocator: (target: any, options?: {
     nth?: number;
+    hasText?: string | RegExp;
     raw?: boolean;
 }) => Locator, target: any, options?: Parameters<ReturnType<typeof playwrightExpect<Locator>>['toBeEnabled']>[0] & {
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 }): Promise<void>;
 export declare function verifyDisabled(resolveLocator: (target: any, options?: {
     nth?: number;
+    hasText?: string | RegExp;
     raw?: boolean;
 }) => Locator, target: any, options?: Parameters<ReturnType<typeof playwrightExpect<Locator>>['toBeDisabled']>[0] & {
     nth?: number;
+    hasText?: string | RegExp;
     message?: string;
 }): Promise<void>;

package/dist/page/assertions/verify-helpers.js

@@ -8,21 +8,21 @@ const formatter_1 = require("../utils/formatter");
 async function verifyHidden(resolveLocator, target, options) {
     const stepName = options?.message ?? (0, formatter_1.formatAssertionDescription)(target, 'toBeHidden', false, [options]);
     await test_1.test.step(stepName, async () => {
-        const locator = resolveLocator(target, { nth: options?.nth });
+        const locator = resolveLocator(target, { nth: options?.nth, hasText: options?.hasText });
         await (0, test_1.expect)(locator, stepName).toBeHidden(options);
     });
 }
 async function verifyEnabled(resolveLocator, target, options) {
     const stepName = options?.message ?? (0, formatter_1.formatAssertionDescription)(target, 'toBeEnabled', false, [options]);
     await test_1.test.step(stepName, async () => {
-        const locator = resolveLocator(target, { nth: options?.nth });
+        const locator = resolveLocator(target, { nth: options?.nth, hasText: options?.hasText });
         await (0, test_1.expect)(locator, stepName).toBeEnabled(options);
     });
 }
 async function verifyDisabled(resolveLocator, target, options) {
     const stepName = options?.message ?? (0, formatter_1.formatAssertionDescription)(target, 'toBeDisabled', false, [options]);
     await test_1.test.step(stepName, async () => {
-        const locator = resolveLocator(target, { nth: options?.nth });
+        const locator = resolveLocator(target, { nth: options?.nth, hasText: options?.hasText });
         await (0, test_1.expect)(locator, stepName).toBeDisabled(options);
     });
 }

package/dist/page/config.d.ts

@@ -28,4 +28,24 @@ export type PageConfig<T = any> = {
     } : Record<string, string>;
     Class?: new (page: Page, config?: any) => any;
 };
+/**
+ * Creates a strongly-typed page configuration object containing URLs, testIds, and CSS selectors.
+ *
+ * @example
+ * ```ts
+ * import { createPageConfig } from 'pw-core/page';
+ *
+ * const config = createPageConfig({
+ *   url: '/login',
+ *   testIds: {
+ *     username: 'username-input',
+ *     password: 'password-input',
+ *     submitBtn: 'login-button',
+ *   },
+ *   selectors: {
+ *     errorAlert: '.alert-danger',
+ *   }
+ * });
+ * ```
+ */
 export declare function createPageConfig<T extends PageConfig<T>>(config: T): T;

package/dist/page/config.js

@@ -21,6 +21,26 @@ function getOptionsArgumentIndex(methodName) {
         return 1;
     return -1;
 }
+/**
+ * Creates a strongly-typed page configuration object containing URLs, testIds, and CSS selectors.
+ *
+ * @example
+ * ```ts
+ * import { createPageConfig } from 'pw-core/page';
+ *
+ * const config = createPageConfig({
+ *   url: '/login',
+ *   testIds: {
+ *     username: 'username-input',
+ *     password: 'password-input',
+ *     submitBtn: 'login-button',
+ *   },
+ *   selectors: {
+ *     errorAlert: '.alert-danger',
+ *   }
+ * });
+ * ```
+ */
 function createPageConfig(config) {
     return config;
 }

package/dist/page/locators/resolver.d.ts

@@ -10,6 +10,7 @@ export declare function resolveLocator<T extends {
 }>(context: Page | Locator, config: T, target: PageKeys<T> | ChainedKeys<T> | Locator, options?: {
     nth?: number;
     raw?: boolean;
+    hasText?: string | RegExp;
 }): Locator;
 /**
  * Resolve a config key to a proxied Locator with step-wrapped Playwright methods.

package/dist/page/locators/resolver.js

@@ -49,13 +49,17 @@ function resolveLocator(context, config, target, options) {
     for (let i = 1; i < parts.length; i++) {
         loc = resolveSingle(parts[i], loc);
     }
+    let resolved = loc;
+    if (options?.hasText !== undefined) {
+        resolved = resolved.filter({ hasText: options.hasText });
+    }
     if (options?.raw) {
-        return loc;
+        return resolved;
     }
     if (options?.nth !== undefined) {
-        return loc.nth(options.nth);
+        return resolved.nth(options.nth);
     }
-    return loc.first();
+    return resolved.first();
 }
 /**
  * Resolve a config key to a proxied Locator with step-wrapped Playwright methods.

package/dist/page/registry.d.ts

@@ -5,16 +5,52 @@ export type PageRegistry = Record<string, PageConfig>;
 export interface PageConstructor<C extends PageConfig<any>> {
     new (page: Page): TypedPage<C>;
 }
-export interface PageRegistryObject<T extends Record<string, PageConfig<any>>> {
+export type PageRegistryTest<T extends Record<string, PageConfig<any>>, P, W, O = {}> = TestType<P & {
+    [K in keyof T]: K extends keyof O ? O[K] extends new (page: Page, ...args: any[]) => infer R ? R : NonNullable<T[K]['Class']> extends new (page: Page, ...args: any[]) => infer R2 ? R2 : TypedPage<T[K]> : NonNullable<T[K]['Class']> extends new (page: Page, ...args: any[]) => infer R ? R : TypedPage<T[K]>;
+}, W & {
+    [K in keyof T as `worker${Capitalize<K & string>}`]: K extends keyof O ? O[K] extends new (page: Page, ...args: any[]) => infer R ? R : NonNullable<T[K]['Class']> extends new (page: Page, ...args: any[]) => infer R2 ? R2 : TypedPage<T[K]> : NonNullable<T[K]['Class']> extends new (page: Page, ...args: any[]) => infer R ? R : TypedPage<T[K]>;
+} & {
+    workerPage: Page;
+}> & {
+    pages: {
+        [K in keyof T]: K extends keyof O ? O[K] : NonNullable<T[K]['Class']> extends new (page: Page, ...args: any[]) => any ? NonNullable<T[K]['Class']> : PageConstructor<T[K]>;
+    };
     classes: {
-        [K in keyof T]: PageConstructor<T[K]>;
+        [K in keyof T]: K extends keyof O ? O[K] : NonNullable<T[K]['Class']> extends new (page: Page, ...args: any[]) => any ? NonNullable<T[K]['Class']> : PageConstructor<T[K]>;
     };
-    extend<O extends Partial<{
+    extend<O2 extends Partial<{
         [K in keyof T]: new (page: Page, ...args: any[]) => any;
-    }>, B extends TestType<any, any> = typeof test>(overrides: O, base?: B): B extends TestType<infer P, infer W> ? TestType<P & {
-        [K in keyof T]: K extends keyof O ? O[K] extends new (...args: any[]) => infer R ? R : TypedPage<T[K]> : TypedPage<T[K]>;
-    }, W> : never;
-}
+    }>, B extends TestType<any, any> = typeof test>(overrides: O2, base?: B): B extends TestType<infer BaseP, infer BaseW> ? PageRegistryTest<T, BaseP, BaseW, O2> : never;
+};
+/**
+ * Creates a page registry that registers page objects as Playwright fixtures,
+ * automatically creating both page-scoped fixtures and worker-scoped fixtures prefixed with 'worker'.
+ *
+ * @example
+ * ```ts
+ * import { createPageRegistry } from 'pw-core/page';
+ * import { LoginPage, config } from './login.page.js';
+ *
+ * // returns the extended test runner directly
+ * const test = createPageRegistry({
+ *   login: { ...config, Class: LoginPage },
+ * });
+ *
+ * // returns page classes only when accessing .pages
+ * const pages = createPageRegistry({
+ *   login: { ...config, Class: LoginPage },
+ * }).pages;
+ *
+ * // In your tests, you can use both the page-scoped and worker-scoped fixtures:
+ * test('login flow', async ({ login, workerLogin }) => {
+ *   await login.goto();
+ *   await login.login('alice', 'secret');
+ *
+ *   await workerLogin.goto();
+ *   await workerLogin.login('bob', 'secret');
+ * });
+ * ```
+ */
 export declare function createPageRegistry<T extends {
     [K in keyof T]: PageConfig<T[K]>;
-} & Record<string, PageConfig<any>>>(registry: T): PageRegistryObject<T>;
+} & Record<string, PageConfig<any>>>(registry: T): typeof test extends TestType<infer P, infer W> ? PageRegistryTest<T, P, W> : never;

package/dist/page/registry.js

@@ -6,6 +6,83 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPageRegistry = createPageRegistry;
 const test_1 = __importDefault(require("@playwright/test"));
 const typed_page_1 = require("./typed-page");
+function createPageRegistryWithClasses(registry, classes, base) {
+    const fixtures = {
+        // Shared worker context and page
+        workerContext: [async ({ browser }, use) => {
+                const context = await browser.newContext();
+                await use(context);
+                await context.close();
+            }, { scope: 'worker' }],
+        workerPage: [async ({ workerContext }, use) => {
+                const page = await workerContext.newPage();
+                await use(page);
+            }, { scope: 'worker' }]
+    };
+    for (const key of Object.keys(registry)) {
+        fixtures[key] = async ({ page }, use) => {
+            const PageClass = classes[key];
+            const instance = new PageClass(page);
+            await use(instance);
+        };
+        const workerKey = `worker${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+        fixtures[workerKey] = [async ({ workerPage }, use) => {
+                const PageClass = classes[key];
+                const instance = new PageClass(workerPage);
+                await use(instance);
+            }, { scope: 'worker' }];
+    }
+    const testRunner = base.extend(fixtures);
+    testRunner.pages = classes;
+    testRunner.classes = classes;
+    const originalExtend = testRunner.extend.bind(testRunner);
+    testRunner.extend = (overrides, customBase = test_1.default) => {
+        if (!overrides) {
+            return originalExtend();
+        }
+        const isPlaywrightFixtures = Object.values(overrides).every(val => (typeof val === 'function' && !val.toString().startsWith('class')) || Array.isArray(val));
+        if (isPlaywrightFixtures) {
+            return originalExtend(overrides);
+        }
+        const newClasses = { ...classes };
+        for (const key of Object.keys(overrides)) {
+            if (overrides[key]) {
+                newClasses[key] = overrides[key];
+            }
+        }
+        return createPageRegistryWithClasses(registry, newClasses, customBase);
+    };
+    return testRunner;
+}
+/**
+ * Creates a page registry that registers page objects as Playwright fixtures,
+ * automatically creating both page-scoped fixtures and worker-scoped fixtures prefixed with 'worker'.
+ *
+ * @example
+ * ```ts
+ * import { createPageRegistry } from 'pw-core/page';
+ * import { LoginPage, config } from './login.page.js';
+ *
+ * // returns the extended test runner directly
+ * const test = createPageRegistry({
+ *   login: { ...config, Class: LoginPage },
+ * });
+ *
+ * // returns page classes only when accessing .pages
+ * const pages = createPageRegistry({
+ *   login: { ...config, Class: LoginPage },
+ * }).pages;
+ *
+ * // In your tests, you can use both the page-scoped and worker-scoped fixtures:
+ * test('login flow', async ({ login, workerLogin }) => {
+ *   await login.goto();
+ *   await login.login('alice', 'secret');
+ *
+ *   await workerLogin.goto();
+ *   await workerLogin.login('bob', 'secret');
+ * });
+ * ```
+ */
 function createPageRegistry(registry) {
     const classes = {};
     for (const key of Object.keys(registry)) {
@@ -16,19 +93,5 @@ function createPageRegistry(registry) {
             }
         });
     }
-    return {
-        classes,
-        extend(overrides, base = test_1.default) {
-            const fixtures = {};
-            for (const key of Object.keys(registry)) {
-                fixtures[key] = async ({ page }, use) => {
-                    const config = registry[key];
-                    const PageClass = overrides[key] || classes[key];
-                    const instance = new PageClass(page);
-                    await use(instance);
-                };
-            }
-            return base.extend(fixtures);
-        }
-    };
+    return createPageRegistryWithClasses(registry, classes, test_1.default);
 }

package/dist/page/typed-page.d.ts

@@ -33,6 +33,7 @@ declare class TypedPageClass<T extends {
     resolveLocator(target: PageKeys<T> | ChainedKeys<T> | Locator, options?: {
         nth?: number;
         raw?: boolean;
+        hasText?: string | RegExp;
     }): Locator;
     /** Resolve a config key to a proxied Locator with step-wrapped methods. */
     locator(target: PageKeys<T> | ChainedKeys<T> | Locator, options?: Parameters<Locator['filter']>[0] & {

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

@@ -15,14 +15,19 @@ import type { PageKeys, ChainedKeys } from '../config';
 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]>;
@@ -37,17 +42,19 @@ type BaseProxyLocatorMethods<T> = {
  * await page.fill('username', 'alice', { nth: 1 });
  * ```
  *
- * pw-core adds `nth` to options — targets a specific match when multiple elements resolve.
+ * pw-core adds `nth` and `hasText` to options — targets a specific match when multiple elements resolve.
  */
 export interface ProxyLocatorMethods<T> extends BaseProxyLocatorMethods<T> {
     /** @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;
         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>;
 }
 export {};

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "pw-core",
-  "version": "0.0.1",
+  "version": "0.0.3",
+  "workspaces": [
+    "examples",
+    "create-pw-core"
+  ],
   "description": "Developer-first Playwright framework with typed page objects, components, assertions, and reusable automation utilities.",
   "author": {
     "name": "Shanmuka Chandra Teja Anem",
@@ -44,18 +48,20 @@
     }
   },
   "scripts": {
-    "build": "rimraf dist && tsc",
-    "prepare": "npm run build"
+    "build": "node -e \"const fs = require('fs'); fs.rmSync('dist', {recursive:true,force:true})\" && tsc && npm run build --prefix create-pw-core",
+    "prepare": "npm run build",
+    "test": "npm run test --workspace=pw-core-demo"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.60.0",
+    "@playwright/test": "^1.61.0",
+    "@types/node": "^20.11.0",
     "rimraf": "^6.0.1",
     "typescript": "^5.3.3"
   },
   "publishConfig": {
     "access": "public"
   }
-}
+}