pomwright 1.5.0 → 2.0.0

package/docs/v2/session-storage.md

@@ -1,160 +0,0 @@
-# SessionStorage (v2)
-
-## Overview
-
-`SessionStorage` is a helper for setting, reading, and clearing `window.sessionStorage` in Playwright tests. It provides:
-
-- Step-wrapped operations using `test.step`.
-- Optional waiting for a navigation context (`waitForContext`).
-- A queueing API for setting data on the next navigation.
-
-It is available via `PageObject.sessionStorage` or direct instantiation.
-
----
-
-## Constructor
-
-```ts
-import { SessionStorage } from "pomwright";
-
-const storage = new SessionStorage(page, { label: "LoginPage" });
-```
-
-### Options
-
-- `label?: string` – optional prefix for step titles.
-
-Step titles are generated as:
-
-```html
-<label>.SessionStorage.<method>:
-```
-
----
-
-## Methods
-
-### `set(states, options?)`
-
-Writes key/value pairs to session storage. Optionally reloads the page after writing and/or waits for a usable context.
-
-```ts
-await storage.set({ token: "abc", theme: "dark" }, { reload: true });
-```
-
-#### **Options**
-
-- `reload?: boolean` – reload the page after setting values.
-- `waitForContext?: boolean` – wait for a main-frame execution context if not available.
-
-If `waitForContext` is not provided and no context exists, `set` throws.
-
----
-
-### `setOnNextNavigation(states)`
-
-Queues data for the next main-frame navigation. Multiple calls merge state until navigation occurs.
-
-```ts
-await storage.setOnNextNavigation({ theme: "dark" });
-await storage.setOnNextNavigation({ token: "abc" });
-```
-
-Behavior:
-
-- Uses a single `framenavigated` listener for the main frame.
-- Flushes queued states after the next navigation.
-- Clears the queue after writing.
-
----
-
-### `get(keys?, options?)`
-
-Reads session storage values.
-
-```ts
-const all = await storage.get();
-const subset = await storage.get(["token", "theme"]);
-```
-
-#### **Options**
-
-- `waitForContext?: boolean` – wait for a main-frame execution context if not available.
-
-If `waitForContext` is not provided and no context exists, `get` throws.
-
----
-
-### `clear(keysOrOptions?, options?)`
-
-Clears session storage. You can clear all entries or a subset of keys.
-
-```ts
-await storage.clear();
-await storage.clear(["token", "theme"]);
-await storage.clear("token");
-await storage.clear({ waitForContext: true });
-await storage.clear(["token"], { waitForContext: true });
-```
-
-#### **Options**
-
-- `waitForContext?: boolean` – wait for a main-frame execution context if not available.
-
----
-
-## Using `SessionStorage` through `PageObject`
-
-```ts
-import { test, expect } from "./fixtures";
-
-test("session storage via PageObject", async ({ loginPage }) => {
-  await loginPage.navigation.gotoThisPage();
-  await loginPage.sessionStorage.set({ token: "abc" }, { reload: true });
-  await loginPage.sessionStorage.setOnNextNavigation({ theme: "dark" });
-
-  const data = await loginPage.sessionStorage.get(["token", "theme"], { waitForContext: true });
-  await loginPage.sessionStorage.clear(["token"], { waitForContext: true });
-
-  expect(data.token).toBe("abc");
-});
-```
-
----
-
-## Using `SessionStorage` as a fixture
-
-```ts
-import { test as base } from "pomwright";
-import { SessionStorage } from "pomwright";
-
-type Fixtures = { sessionStorage: SessionStorage };
-
-export const test = base.extend<Fixtures>({
-  sessionStorage: async ({ page }, use) => {
-    await use(new SessionStorage(page, { label: "SessionStorage" }));
-  },
-});
-```
-
----
-
-## Context handling details
-
-Internally, `SessionStorage` checks for a main-frame execution context by evaluating `window.sessionStorage`. If the context is missing (e.g., before initial navigation or during reloads), you can pass `waitForContext: true` to wait for `framenavigated` and re-check availability.
-
-If you omit `waitForContext` and no context exists, the helper throws with:
-
-```text
-SessionStorage context is not available.
-```
-
----
-
-## v1 to v2 differences
-
-- v1 `set(states, reload: boolean)` becomes `set(states, { reload, waitForContext })`.
-- v1 `get(keys?)` and `clear()` did not accept context options.
-- v2 `clear` accepts optional keys and `waitForContext`.
-
-For migration guidance, see `docs/v1-to-v2-migration`.

package/index.ts

@@ -1,75 +0,0 @@
-/*
- * V1 Exports
- */
-
-import { type AriaRoleType, GetByMethod, type LocatorSchema } from "./src/helpers/locatorSchema.interface";
-export { GetByMethod, type LocatorSchema, type AriaRoleType };
-
-import { BaseApi } from "./src/api/baseApi";
-export { BaseApi };
-
-import {
-	BasePage,
-	type BasePageOptions,
-	type ExtractBaseUrlType,
-	type ExtractFullUrlType,
-	type ExtractUrlPathType,
-} from "./src/basePage";
-export { BasePage, type BasePageOptions, type ExtractBaseUrlType, type ExtractFullUrlType, type ExtractUrlPathType };
-
-import { GetLocatorBase, type LocatorSchemaWithoutPath } from "./src/helpers/getLocatorBase";
-export { GetLocatorBase, type LocatorSchemaWithoutPath };
-
-import { BasePageV1toV2 } from "./src/basePageV1toV2";
-export { BasePageV1toV2 };
-
-/*
- * V2 Exports
- */
-
-import {
-	type AddAccessor,
-	createRegistryWithAccessors,
-	type GetLocatorAccessor,
-	type GetLocatorSchemaAccessor,
-	type GetNestedLocatorAccessor,
-	type LocatorRegistry,
-} from "./srcV2/locators";
-export {
-	createRegistryWithAccessors,
-	type LocatorRegistry,
-	type AddAccessor,
-	type GetLocatorAccessor,
-	type GetLocatorSchemaAccessor,
-	type GetNestedLocatorAccessor,
-};
-
-import {
-	type BaseUrlTypeFromOptions,
-	type FullUrlTypeFromOptions,
-	PageObject,
-	type UrlPathTypeFromOptions,
-	type UrlTypeOptions,
-} from "./srcV2/pageObject";
-export {
-	PageObject,
-	type BaseUrlTypeFromOptions,
-	type FullUrlTypeFromOptions,
-	type UrlPathTypeFromOptions,
-	type UrlTypeOptions,
-};
-
-import { test } from "./srcV2/fixture/base.fixtures";
-export { test };
-
-import { step } from "./srcV2/helpers/stepDecorator";
-export { step };
-
-import type { NavigationOptions } from "./srcV2/helpers/navigation";
-export type { NavigationOptions };
-
-import { SessionStorage } from "./srcV2/helpers/sessionStorage";
-export { SessionStorage };
-
-import { type LogEntry, type LogLevel, PlaywrightReportLogger } from "./srcV2/helpers/playwrightReportLogger";
-export { type LogEntry, type LogLevel, PlaywrightReportLogger };

package/intTestV2/fixtures/testApp.fixtures.ts

@@ -1,43 +0,0 @@
-import IframePage from "@page-object-models-v2/testApp/pages/iframe/iframe.page";
-import TestFilters from "@page-object-models-v2/testApp/pages/testfilters/testfilters.page";
-import TestPage from "@page-object-models-v2/testApp/pages/testPage.page";
-import Color from "@page-object-models-v2/testApp/pages/testPath/[color]/color.page";
-import TestPath from "@page-object-models-v2/testApp/pages/testPath/testPath.page";
-import { expect } from "@playwright/test";
-import { test as base } from "pomwright";
-
-type Fixtures = {
-	iframePage: IframePage;
-	testPage: TestPage;
-	testPath: TestPath;
-	color: Color;
-	testFilters: TestFilters;
-};
-
-const test = base.extend<Fixtures>({
-	iframePage: async ({ page }, use) => {
-		const iframePage = new IframePage(page);
-		await use(iframePage);
-	},
-	testPage: async ({ page }, use) => {
-		const testPage = new TestPage(page);
-		await use(testPage);
-	},
-
-	testPath: async ({ page }, use) => {
-		const testPath = new TestPath(page);
-		await use(testPath);
-	},
-
-	color: async ({ page }, use) => {
-		const color = new Color(page);
-		await use(color);
-	},
-
-	testFilters: async ({ page }, use) => {
-		const testFilters = new TestFilters(page);
-		await use(testFilters);
-	},
-});
-
-export { expect, test };

package/intTestV2/package.json

@@ -1,22 +0,0 @@
-{
-	"name": "test-v2",
-	"version": "1.0.0",
-	"description": "",
-	"main": "index.js",
-	"scripts": {
-		"start": "node ./server.js",
-		"postinstall": "npx -y only-allow pnpm && npx playwright install-deps"
-	},
-	"keywords": [],
-	"devDependencies": {
-		"@playwright/test": "1.58.0",
-		"@types/express": "^5.0.3",
-		"@types/node": "^24.5.2",
-		"express": "^5.1.0",
-		"pomwright": "file:../pomwright-1.4.0.tgz"
-	},
-	"dependencies": {
-		"dotenv": "^17.2.2"
-	},
-	"packageManager": "pnpm@9.12.0"
-}

package/intTestV2/page-object-models/testApp/pages/iframe/iframe.locatorSchema.ts

@@ -1,24 +0,0 @@
-import type { LocatorRegistry } from "pomwright";
-
-export type Paths =
-	| "sectionA"
-	| "sectionA.frame"
-	| "sectionA.frame.toggle"
-	| "sectionB"
-	| "sectionB.frame"
-	| "sectionB.frame.toggle"
-	| "sectionB.frame.innerFrame"
-	| "sectionB.frame.innerFrame.toggle";
-
-export function defineLocators(locators: LocatorRegistry<Paths>) {
-	locators.add("sectionA").locator("#sectionA");
-	locators.add("sectionA.frame").frameLocator("#iframeA");
-	locators.add("sectionA.frame.toggle").getByTestId("toggle-a");
-
-	locators.add("sectionB").locator("#sectionB");
-	locators.add("sectionB.frame").frameLocator("#iframeB");
-	locators.add("sectionB.frame.toggle").getByTestId("toggle-b");
-
-	locators.add("sectionB.frame.innerFrame").frameLocator("#iframeC");
-	locators.add("sectionB.frame.innerFrame.toggle").getByTestId("toggle-c");
-}

package/intTestV2/page-object-models/testApp/pages/iframe/iframe.page.ts

@@ -1,17 +0,0 @@
-import type { Page } from "@playwright/test";
-import TestApp from "../../testApp.base";
-import { defineLocators, type Paths } from "./iframe.locatorSchema";
-
-export default class IframePage extends TestApp<Paths> {
-	constructor(page: Page) {
-		super(page, "/iframe");
-	}
-
-	protected defineLocators(): void {
-		defineLocators(this.locatorRegistry);
-	}
-
-	protected pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null {
-		return [];
-	}
-}

package/intTestV2/page-object-models/testApp/pages/testPage.locatorSchema.ts

@@ -1,32 +0,0 @@
-import type { LocatorRegistry } from "pomwright";
-
-export type Paths =
-	| "topMenu"
-	| "topMenu.logo"
-	| "topMenu.news"
-	| "topMenu.accountSettings"
-	| "topMenu.messages"
-	| "topMenu.notifications"
-	| "topMenu.notifications.button"
-	| "topMenu.notifications.button.countBadge"
-	| "topMenu.notifications.dropdown"
-	| "topMenu.notifications.dropdown.item"
-	| "topMenu.myAccount";
-
-export function defineLocators(registry: LocatorRegistry<Paths>) {
-	registry.add("topMenu").locator(".w3-top");
-
-	registry.add("topMenu.logo").getByRole("link", { name: /Logo/ });
-
-	registry.add("topMenu.news").getByTitle("News");
-	registry.add("topMenu.accountSettings").getByTitle("Account Settings");
-	registry.add("topMenu.messages").getByTitle("Messages");
-
-	registry.add("topMenu.notifications").locator(".w3-dropdown-hover");
-	registry.add("topMenu.notifications.button").getByRole("button");
-	registry.add("topMenu.notifications.button.countBadge").locator(".w3-badge");
-	registry.add("topMenu.notifications.dropdown").locator(".w3-dropdown-content");
-	registry.add("topMenu.notifications.dropdown.item").locator(".w3-bar-item");
-
-	registry.add("topMenu.myAccount").getByTitle("My Account");
-}

package/intTestV2/page-object-models/testApp/pages/testPage.page.ts

@@ -1,119 +0,0 @@
-import { expect, type Page } from "@playwright/test";
-import { step } from "pomwright";
-import TestApp from "../testApp.base";
-import { defineLocators, type Paths } from "./testPage.locatorSchema";
-
-export default class TestPageV2 extends TestApp<Paths> {
-	readonly navigationActionCount = { value: 0 };
-
-	constructor(page: Page) {
-		super(page, "/");
-	}
-
-	protected defineLocators(): void {
-		defineLocators(this.locatorRegistry);
-	}
-
-	protected pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null {
-		return [
-			async () => {
-				this.navigationActionCount.value += 1;
-			},
-		];
-	}
-
-	@step
-	async stepNoArgs(): Promise<string> {
-		expect(true).toBe(true);
-		return "Hello, World!";
-	}
-
-	@step("Step with title")
-	async stepWithTitle(): Promise<string> {
-		return "Hello, World!";
-	}
-
-	@step({ box: true })
-	async stepWithOptionBox(): Promise<string> {
-		return "Hello, World!";
-	}
-
-	@step({ timeout: 1000 })
-	async stepWithOptionTimeout(): Promise<string> {
-		return "Hello, World!";
-	}
-
-	@step({
-		location: {
-			file: "intTestV2/page-object-models/testApp/with-options/pages/testPage.page.ts",
-			line: 1,
-			column: 1,
-		},
-	})
-	async stepWithOptionLocation(): Promise<string> {
-		return "Hello, World!";
-	}
-
-	@step("Step with all options", {
-		box: true,
-		timeout: 1000,
-		location: {
-			file: "intTestV2/page-object-models/testApp/with-options/pages/testPage.page.ts",
-			line: 1,
-			column: 1,
-		},
-	})
-	async stepWithTitleAndAllOptions(): Promise<string> {
-		return "Hello, World!";
-	}
-
-	@step("Step with advanced return type")
-	async stepWithAdvancedReturnType(): Promise<
-		{
-			id: string;
-			metadata: {
-				flags: Set<"alpha" | "beta">;
-				versions: Map<string, { hash: string; tags: string[] }>;
-			};
-			payload: Array<{ index: number; values: ReadonlyArray<{ key: string; value: number }> }>;
-		} & {
-			readonly status: "ready";
-			readonly startedAt: Date;
-		}
-	> {
-		return {
-			id: "fixture-id",
-			metadata: {
-				flags: new Set(["alpha", "beta"]),
-				versions: new Map([
-					["v1", { hash: "abc123", tags: ["stable", "verified"] }],
-					["v2", { hash: "def456", tags: ["next"] }],
-				]),
-			},
-			payload: [
-				{ index: 1, values: [{ key: "alpha", value: 10 }] },
-				{ index: 2, values: [{ key: "beta", value: 20 }] },
-			],
-			status: "ready",
-			startedAt: new Date(0),
-		};
-	}
-
-	@step
-	async stepWithArgs(subscriptionTitle: string, clickCount = 1): Promise<string> {
-		return `${subscriptionTitle}:${clickCount}`;
-	}
-
-	@step("Step with args and object return")
-	async stepWithArgsAndObjectReturn(
-		input: { id: string; mode?: "basic" | "advanced" },
-		retry = 0,
-	): Promise<{ ok: true; id: string; mode: "basic" | "advanced"; retry: number }> {
-		return {
-			ok: true,
-			id: input.id,
-			mode: input.mode ?? "basic",
-			retry,
-		};
-	}
-}

package/intTestV2/page-object-models/testApp/pages/testPath/[color]/color.locatorSchema.ts

@@ -1,29 +0,0 @@
-import type { LocatorRegistry } from "pomwright";
-
-const tableVariants = ["body.table", "body.table@hexCode"] as const;
-
-type TableVariants = (typeof tableVariants)[number];
-type TableChildren = "row" | "row.rowheader" | "row.cell";
-
-export type Paths = "body" | "body.heading" | TableVariants | `${TableVariants}.${TableChildren}`;
-
-export function defineLocators(registry: LocatorRegistry<Paths>) {
-	registry.add("body").locator("body");
-
-	registry.add("body.heading").getByRole("heading", { name: "Your Random Color is:" });
-
-	const tableLocatorMap: Array<[Paths, { name?: string }]> = [
-		["body.table", {}],
-		["body.table@hexCode", { name: "Hex Code Information" }],
-	];
-
-	for (const [path, { name }] of tableLocatorMap) {
-		registry.add(path).getByRole("table", name ? { name } : undefined);
-	}
-
-	for (const tableVariant of tableVariants) {
-		registry.add(`${tableVariant}.row`).getByRole("row");
-		registry.add(`${tableVariant}.row.rowheader`).getByRole("rowheader");
-		registry.add(`${tableVariant}.row.cell`).getByRole("cell");
-	}
-}

package/intTestV2/page-object-models/testApp/pages/testPath/[color]/color.page.ts

@@ -1,48 +0,0 @@
-import { expect, type Page, test } from "@playwright/test";
-import TestApp from "../../../testApp.base";
-import { defineLocators, type Paths } from "./color.locatorSchema";
-
-export default class ColorV2 extends TestApp<Paths, { urlPathType: RegExp }> {
-	constructor(page: Page) {
-		const urlPathRegex = /\/testpath\/([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/;
-		super(page, urlPathRegex);
-	}
-
-	protected defineLocators(): void {
-		defineLocators(this.locatorRegistry);
-	}
-
-	protected pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null {
-		return [];
-	}
-
-	async expectThisPage() {
-		await test.step("Expect color page", async () => {
-			await this.page.waitForURL(this.fullUrl);
-
-			const heading = this.getNestedLocator("body.heading");
-			await heading.waitFor({ state: "visible" });
-		});
-	}
-
-	async validateColorPage() {
-		await test.step("Verify hex code", async () => {
-			const currentUrl = this.page.url();
-			const hexCode = currentUrl.split("/").pop();
-
-			await test.step("Verify hex code in table equals hex code in urlPath", async () => {
-				const hexCodeCell = this.getNestedLocator("body.table@hexCode.row.cell");
-				await expect(hexCodeCell).toContainText(`#${hexCode}`, {
-					useInnerText: true,
-					ignoreCase: true,
-				});
-			});
-
-			await test.step("Verify hex code in urlPath is the page background color", async () => {
-				const body = this.getNestedLocator("body");
-				const bgColor = await body.getAttribute("style");
-				expect(bgColor).toContain(`background-color: #${hexCode}`);
-			});
-		});
-	}
-}

package/intTestV2/page-object-models/testApp/pages/testPath/testPath.locatorSchema.ts

@@ -1,9 +0,0 @@
-import type { LocatorRegistry } from "pomwright";
-
-export type Paths = "body" | "body.link@color";
-
-export function defineLocators(registry: LocatorRegistry<Paths>) {
-	registry.add("body").locator("body");
-
-	registry.add("body.link@color").getByRole("link", { name: "Random Color Link" });
-}

package/intTestV2/page-object-models/testApp/pages/testPath/testPath.page.ts

@@ -1,23 +0,0 @@
-import { type Page, test } from "@playwright/test";
-import TestApp from "../../testApp.base";
-import { defineLocators, type Paths } from "./testPath.locatorSchema";
-
-export default class TestPathV2 extends TestApp<Paths> {
-	constructor(page: Page) {
-		super(page, "/testpath");
-	}
-
-	protected defineLocators(): void {
-		defineLocators(this.locatorRegistry);
-	}
-
-	protected pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null {
-		return [];
-	}
-
-	async expectThisPage() {
-		await test.step(`Expect Page: ${this.urlPath}`, async () => {
-			await this.page.waitForURL(this.fullUrl);
-		});
-	}
-}