pomwright 1.3.0 → 1.5.0

package/srcV2/locators/utils.ts

@@ -0,0 +1,309 @@
+import type { Locator, Page } from "@playwright/test";
+import type {
+	AltTextDefinition,
+	FrameLocatorDefinition,
+	IdDefinition,
+	IndexSelector,
+	LabelDefinition,
+	LocatorBuilderTarget,
+	LocatorDefinition,
+	LocatorStep,
+	LocatorStrategyDefinition,
+	LocatorStrategyDefinitionPatch,
+	PlaceholderDefinition,
+	RoleDefinition,
+	TestIdDefinition,
+	TextDefinition,
+	TitleDefinition,
+} from "./types";
+
+// Used only at runtime for messages: escape all special chars so
+// whitespace, quotes, etc. are visible and testable.
+export const formatLocatorSchemaPathForError = (path: string): string => {
+	// JSON.stringify returns a quoted string literal; strip the outer quotes.
+	// Example:
+	//   path = "\n"         -> JSON.stringify -> "\"\\n\""      -> "\\n"
+	//   path = "a\u00A0b"   -> "\"a\\u00a0b\"" -> "a\\u00a0b"
+	const json = JSON.stringify(path);
+	return json.slice(1, -1);
+};
+
+// Precompiled regex for "any JS whitespace OR U+0085"
+const RUNTIME_WHITESPACE_REGEX = /[\s\u0085]/u;
+
+export const validateLocatorSchemaPath = (path: string) => {
+	if (!path) {
+		throw new Error("LocatorSchemaPath string cannot be empty");
+	}
+
+	// Runtime: reject any Unicode whitespace (aligned with compile-time)
+	if (RUNTIME_WHITESPACE_REGEX.test(path)) {
+		const escaped = formatLocatorSchemaPathForError(path);
+		throw new Error(`LocatorSchemaPath string cannot contain whitespace chars: ${escaped}`);
+	}
+
+	if (path.startsWith(".")) {
+		throw new Error(`LocatorSchemaPath string cannot start with a dot: ${path}`);
+	}
+
+	if (path.endsWith(".")) {
+		throw new Error(`LocatorSchemaPath string cannot end with a dot: ${path}`);
+	}
+
+	if (path.includes("..")) {
+		throw new Error(`LocatorSchemaPath string cannot contain consecutive dots: ${path}`);
+	}
+};
+
+export const expandSchemaPath = (path: string): string[] => {
+	validateLocatorSchemaPath(path);
+	const parts = path.split(".");
+	return parts.map((_part, index) => parts.slice(0, index + 1).join("."));
+};
+
+export const cssEscape = (value: string) => {
+	// Simple CSS escape implementation covering common cases.
+	return value.replace(/([\\"'#.:;,?*+<>{}[\\]()])/g, "\\$1");
+};
+
+export const normalizeSteps = <LocatorSchemaPathType extends string, AllowedPaths extends string>(
+	steps?: LocatorStep<LocatorSchemaPathType, AllowedPaths>[],
+) => (steps ? steps.map((step) => ({ ...step })) : []);
+
+export function normalizeIdValue(id: string): string;
+export function normalizeIdValue(id: RegExp): RegExp;
+export function normalizeIdValue(id: string | RegExp | undefined): string | RegExp | undefined;
+export function normalizeIdValue(id: string | RegExp | undefined) {
+	if (typeof id !== "string") {
+		return id;
+	}
+
+	if (id.startsWith("#")) {
+		return id.slice(1);
+	}
+
+	if (id.startsWith("id=")) {
+		return id.slice("id=".length);
+	}
+
+	return id;
+}
+
+export const stringifyForLog = (value: unknown) => {
+	const seen = new WeakSet();
+	return JSON.stringify(
+		value,
+		(_key, current) => {
+			if (typeof current === "object" && current !== null) {
+				if (seen.has(current)) {
+					return "[Circular]";
+				}
+				seen.add(current);
+			}
+			if (current instanceof RegExp) {
+				return { type: "RegExp", source: current.source, flags: current.flags };
+			}
+			return current;
+		},
+		2,
+	);
+};
+
+export const applyIndexSelector = (locator: Locator, selector: IndexSelector | null | undefined) => {
+	if (selector === undefined || selector === null) {
+		return locator;
+	}
+	if (selector === "first") {
+		return locator.first();
+	}
+	if (selector === "last") {
+		return locator.last();
+	}
+	return locator.nth(selector);
+};
+
+export const createLocator = (
+	target: LocatorBuilderTarget,
+	definition: LocatorStrategyDefinition,
+): Locator | ReturnType<Page["frameLocator"]> => {
+	switch (definition.type) {
+		case "role":
+			return target.getByRole(definition.role, definition.options);
+		case "text":
+			return target.getByText(definition.text, definition.options);
+		case "label":
+			return target.getByLabel(definition.text, definition.options);
+		case "placeholder":
+			return target.getByPlaceholder(definition.text, definition.options);
+		case "altText":
+			return target.getByAltText(definition.text, definition.options);
+		case "title":
+			return target.getByTitle(definition.text, definition.options);
+		case "locator":
+			return target.locator(definition.selector, definition.options);
+		case "frameLocator":
+			return target.frameLocator(definition.selector);
+		case "testId":
+			return target.getByTestId(definition.testId);
+		case "id": {
+			if (typeof definition.id === "string") {
+				const normalized = normalizeIdValue(definition.id);
+				return target.locator(`#${cssEscape(normalized ?? "")}`);
+			}
+			const pattern = definition.id.source;
+			const safePattern = cssEscape(pattern);
+			return target.locator(`[id*="${safePattern}"]`);
+		}
+		default: {
+			const exhaustive: never = definition;
+			return exhaustive;
+		}
+	}
+};
+
+export const cloneLocatorStrategyDefinition = (definition: LocatorStrategyDefinition): LocatorStrategyDefinition => {
+	switch (definition.type) {
+		case "role":
+			return {
+				type: "role",
+				role: definition.role,
+				...(definition.options ? { options: { ...definition.options } } : {}),
+			};
+		case "text":
+			return {
+				type: "text",
+				text: definition.text,
+				...(definition.options ? { options: { ...definition.options } } : {}),
+			};
+		case "label":
+			return {
+				type: "label",
+				text: definition.text,
+				...(definition.options ? { options: { ...definition.options } } : {}),
+			};
+		case "placeholder":
+			return {
+				type: "placeholder",
+				text: definition.text,
+				...(definition.options ? { options: { ...definition.options } } : {}),
+			};
+		case "altText":
+			return {
+				type: "altText",
+				text: definition.text,
+				...(definition.options ? { options: { ...definition.options } } : {}),
+			};
+		case "title":
+			return {
+				type: "title",
+				text: definition.text,
+				...(definition.options ? { options: { ...definition.options } } : {}),
+			};
+		case "locator":
+			return {
+				type: "locator",
+				selector: definition.selector,
+				...(definition.options ? { options: { ...definition.options } } : {}),
+			};
+		case "frameLocator":
+			return { type: "frameLocator", selector: definition.selector };
+		case "testId":
+			return { type: "testId", testId: definition.testId };
+		case "id":
+			return { type: "id", id: definition.id };
+		default: {
+			const exhaustive: never = definition;
+			return exhaustive;
+		}
+	}
+};
+
+export const applyDefinitionPatch = (
+	seed: LocatorStrategyDefinition,
+	patch: LocatorStrategyDefinition | LocatorStrategyDefinitionPatch,
+): LocatorStrategyDefinition => {
+	const base = cloneLocatorStrategyDefinition(seed);
+
+	switch (patch.type) {
+		case "locator": {
+			const selector = patch.selector !== undefined ? patch.selector : (base as LocatorDefinition).selector;
+			const options =
+				patch.options || (base as LocatorDefinition).options
+					? { ...(base as LocatorDefinition).options, ...patch.options }
+					: undefined;
+			return { type: "locator", selector, ...(options ? { options } : {}) } satisfies LocatorDefinition;
+		}
+		case "role": {
+			const role = patch.role ?? (base as RoleDefinition).role;
+			const options =
+				patch.options || (base as RoleDefinition).options
+					? { ...(base as RoleDefinition).options, ...patch.options }
+					: undefined;
+			return { type: "role", role, ...(options ? { options } : {}) } satisfies RoleDefinition;
+		}
+		case "text": {
+			const text = patch.text ?? (base as TextDefinition).text;
+			const options =
+				patch.options || (base as TextDefinition).options
+					? { ...(base as TextDefinition).options, ...patch.options }
+					: undefined;
+			return { type: "text", text, ...(options ? { options } : {}) } satisfies TextDefinition;
+		}
+		case "label": {
+			const text = patch.text ?? (base as LabelDefinition).text;
+			const options =
+				patch.options || (base as LabelDefinition).options
+					? { ...(base as LabelDefinition).options, ...patch.options }
+					: undefined;
+			return { type: "label", text, ...(options ? { options } : {}) } satisfies LabelDefinition;
+		}
+		case "placeholder": {
+			const text = patch.text ?? (base as PlaceholderDefinition).text;
+			const options =
+				patch.options || (base as PlaceholderDefinition).options
+					? { ...(base as PlaceholderDefinition).options, ...patch.options }
+					: undefined;
+			return { type: "placeholder", text, ...(options ? { options } : {}) } satisfies PlaceholderDefinition;
+		}
+		case "altText": {
+			const text = patch.text ?? (base as AltTextDefinition).text;
+			const options =
+				patch.options || (base as AltTextDefinition).options
+					? { ...(base as AltTextDefinition).options, ...patch.options }
+					: undefined;
+			return { type: "altText", text, ...(options ? { options } : {}) } satisfies AltTextDefinition;
+		}
+		case "title": {
+			const text = patch.text ?? (base as TitleDefinition).text;
+			const options =
+				patch.options || (base as TitleDefinition).options
+					? { ...(base as TitleDefinition).options, ...patch.options }
+					: undefined;
+			return { type: "title", text, ...(options ? { options } : {}) } satisfies TitleDefinition;
+		}
+		case "frameLocator": {
+			const selector = patch.selector !== undefined ? patch.selector : (base as FrameLocatorDefinition).selector;
+			return { type: "frameLocator", selector } satisfies FrameLocatorDefinition;
+		}
+		case "testId": {
+			const testId = patch.testId !== undefined ? patch.testId : (base as TestIdDefinition).testId;
+			return { type: "testId", testId } satisfies TestIdDefinition;
+		}
+		case "id": {
+			const id =
+				patch.id !== undefined ? (normalizeIdValue(patch.id) ?? (base as IdDefinition).id) : (base as IdDefinition).id;
+			return { type: "id", id } satisfies IdDefinition;
+		}
+		default: {
+			const exhaustive: never = patch;
+			return exhaustive;
+		}
+	}
+};
+
+export const isFrameLocatorDefinition = (definition: LocatorStrategyDefinition): definition is FrameLocatorDefinition =>
+	definition.type === "frameLocator";
+
+export const isLocatorInstance = (value: unknown): value is Locator => {
+	return !!value && typeof value === "object" && typeof (value as Locator).filter === "function";
+};

package/srcV2/locators/v1SchemaTranslator.ts

@@ -0,0 +1,178 @@
+import type { Locator } from "@playwright/test";
+import type { LocatorSchema } from "../../src/helpers/locatorSchema.interface";
+import { GetByMethod } from "../../src/helpers/locatorSchema.interface";
+import type { LocatorRegistry, LocatorRegistryInternal } from "./locatorRegistry";
+import type { RegistryPath } from "./types";
+import { isLocatorInstance, validateLocatorSchemaPath } from "./utils";
+
+type RegistryWithLookup<LocatorSchemaPathType extends string> = LocatorRegistryInternal<LocatorSchemaPathType> & {
+	getIfExists?: (path: RegistryPath<LocatorSchemaPathType>) => unknown;
+};
+
+const getRegistryLookup = <LocatorSchemaPathType extends string>(
+	registry: LocatorRegistry<LocatorSchemaPathType>,
+): RegistryWithLookup<LocatorSchemaPathType> => registry as RegistryWithLookup<LocatorSchemaPathType>;
+
+const logMissingDefinition = (path: string, field: string) => {
+	console.warn(
+		`[POMWright] Skipping v2 translation for "${path}" because "${field}" is missing. ` +
+			"Rewrite this locator in defineLocators() using the v2 registry.",
+	);
+};
+
+const logLocatorInstanceWarning = (path: string) => {
+	console.warn(
+		`[POMWright] Skipping v2 translation for "${path}" because v1 LocatorSchema.locator is a Locator instance. ` +
+			"Rewrite this path in defineLocators() to avoid runtime gaps during migration.",
+	);
+};
+
+export const addV1SchemaToV2Registry = <LocatorSchemaPathType extends string>(
+	registry: LocatorRegistry<LocatorSchemaPathType>,
+	locatorSchema: LocatorSchema,
+) => {
+	const path = locatorSchema.locatorSchemaPath;
+	validateLocatorSchemaPath(path);
+
+	const registryWithLookup = getRegistryLookup(registry);
+	const existing = registryWithLookup.getIfExists?.(path as RegistryPath<LocatorSchemaPathType>);
+	if (existing) {
+		return;
+	}
+
+	console.info(
+		`[POMWright] LocatorSchemaPath "${path}" is not registered in the v2 registry. ` +
+			"Translating and adding v1 schema to v2 Locator Registry; update this path to use registry.add in defineLocators().",
+	);
+
+	const registration = registry.add(path as RegistryPath<LocatorSchemaPathType>);
+	if (!registration) {
+		return;
+	}
+
+	let postDefinition:
+		| ReturnType<typeof registration.getByRole>
+		| ReturnType<typeof registration.getByText>
+		| ReturnType<typeof registration.getByLabel>
+		| ReturnType<typeof registration.getByPlaceholder>
+		| ReturnType<typeof registration.getByAltText>
+		| ReturnType<typeof registration.getByTitle>
+		| ReturnType<typeof registration.locator>
+		| ReturnType<typeof registration.frameLocator>
+		| ReturnType<typeof registration.getByTestId>
+		| ReturnType<typeof registration.getById>
+		| null = null;
+
+	switch (locatorSchema.locatorMethod) {
+		case GetByMethod.role: {
+			if (!locatorSchema.role) {
+				logMissingDefinition(path, "role");
+				return;
+			}
+			postDefinition = registration.getByRole(locatorSchema.role, locatorSchema.roleOptions);
+			break;
+		}
+		case GetByMethod.text: {
+			if (!locatorSchema.text) {
+				logMissingDefinition(path, "text");
+				return;
+			}
+			postDefinition = registration.getByText(locatorSchema.text, locatorSchema.textOptions);
+			break;
+		}
+		case GetByMethod.label: {
+			if (!locatorSchema.label) {
+				logMissingDefinition(path, "label");
+				return;
+			}
+			postDefinition = registration.getByLabel(locatorSchema.label, locatorSchema.labelOptions);
+			break;
+		}
+		case GetByMethod.placeholder: {
+			if (!locatorSchema.placeholder) {
+				logMissingDefinition(path, "placeholder");
+				return;
+			}
+			postDefinition = registration.getByPlaceholder(locatorSchema.placeholder, locatorSchema.placeholderOptions);
+			break;
+		}
+		case GetByMethod.altText: {
+			if (!locatorSchema.altText) {
+				logMissingDefinition(path, "altText");
+				return;
+			}
+			postDefinition = registration.getByAltText(locatorSchema.altText, locatorSchema.altTextOptions);
+			break;
+		}
+		case GetByMethod.title: {
+			if (!locatorSchema.title) {
+				logMissingDefinition(path, "title");
+				return;
+			}
+			postDefinition = registration.getByTitle(locatorSchema.title, locatorSchema.titleOptions);
+			break;
+		}
+		case GetByMethod.locator: {
+			if (!locatorSchema.locator) {
+				logMissingDefinition(path, "locator");
+				return;
+			}
+			if (isLocatorInstance(locatorSchema.locator)) {
+				logLocatorInstanceWarning(path);
+				return;
+			}
+			postDefinition = registration.locator(locatorSchema.locator, locatorSchema.locatorOptions);
+			break;
+		}
+		case GetByMethod.frameLocator: {
+			if (!locatorSchema.frameLocator) {
+				logMissingDefinition(path, "frameLocator");
+				return;
+			}
+			postDefinition = registration.frameLocator(locatorSchema.frameLocator);
+			break;
+		}
+		case GetByMethod.testId: {
+			if (!locatorSchema.testId) {
+				logMissingDefinition(path, "testId");
+				return;
+			}
+			postDefinition = registration.getByTestId(locatorSchema.testId);
+			break;
+		}
+		case GetByMethod.dataCy: {
+			if (!locatorSchema.dataCy) {
+				logMissingDefinition(path, "dataCy");
+				return;
+			}
+			postDefinition = registration.locator(`[data-cy="${locatorSchema.dataCy}"]`);
+			break;
+		}
+		case GetByMethod.id: {
+			if (!locatorSchema.id) {
+				logMissingDefinition(path, "id");
+				return;
+			}
+			postDefinition = registration.getById(locatorSchema.id);
+			break;
+		}
+		default: {
+			const exhaustive: never = locatorSchema.locatorMethod;
+			return exhaustive;
+		}
+	}
+
+	if (!postDefinition) {
+		return;
+	}
+
+	if (locatorSchema.filter && locatorSchema.locatorMethod !== GetByMethod.frameLocator) {
+		const filter = locatorSchema.filter as {
+			has?: Locator;
+			hasNot?: Locator;
+			hasText?: string | RegExp;
+			hasNotText?: string | RegExp;
+		};
+		postDefinition.filter(filter);
+	}
+};

package/srcV2/pageObject.ts

@@ -0,0 +1,105 @@
+import type { Page } from "@playwright/test";
+import { createNavigation, type ExtractNavigationType, type NavigationOptions } from "./helpers/navigation";
+import { SessionStorage } from "./helpers/sessionStorage";
+import {
+	type AddAccessor,
+	createRegistryWithAccessors,
+	type GetLocatorAccessor,
+	type GetLocatorSchemaAccessor,
+	type GetNestedLocatorAccessor,
+	type LocatorRegistry,
+} from "./locators";
+
+/**
+ * UrlTypeOptions define types for baseUrl and urlPath.
+ * string is the default type; The types can be overridden to RegExp, using the Extract...Type utility types. If either
+ * baseUrlType or urlPathType is set to RegExp, then fullUrlType will also be RegExp and can't be used for navigation,
+ * only validation through URL matching.
+ */
+export type UrlTypeOptions = {
+	baseUrlType?: string | RegExp;
+	urlPathType?: string | RegExp;
+};
+
+export type BaseUrlTypeFromOptions<T extends UrlTypeOptions> = T extends { baseUrlType: RegExp } ? RegExp : string;
+export type UrlPathTypeFromOptions<T extends UrlTypeOptions> = T extends { urlPathType: RegExp } ? RegExp : "" | string;
+export type FullUrlTypeFromOptions<T extends UrlTypeOptions> = T extends
+	| { baseUrlType: RegExp }
+	| { urlPathType: RegExp }
+	? RegExp
+	: string;
+
+export abstract class PageObject<
+	LocatorSchemaPathType extends string,
+	Options extends UrlTypeOptions = { baseUrlType: string; urlPathType: string },
+> {
+	readonly page: Page;
+	readonly baseUrl: BaseUrlTypeFromOptions<Options>;
+	readonly urlPath: UrlPathTypeFromOptions<Options>;
+	readonly fullUrl: FullUrlTypeFromOptions<Options>;
+	readonly label: string;
+	readonly sessionStorage: SessionStorage;
+	public readonly navigation: ExtractNavigationType<FullUrlTypeFromOptions<Options>>;
+	protected readonly locatorRegistry: LocatorRegistry<LocatorSchemaPathType>;
+	public readonly add: AddAccessor<LocatorSchemaPathType>;
+	public readonly getLocator: GetLocatorAccessor<LocatorSchemaPathType>;
+	public readonly getLocatorSchema: GetLocatorSchemaAccessor<LocatorSchemaPathType>;
+	public readonly getNestedLocator: GetNestedLocatorAccessor<LocatorSchemaPathType>;
+
+	protected constructor(
+		page: Page,
+		baseUrl: BaseUrlTypeFromOptions<Options>,
+		urlPath: UrlPathTypeFromOptions<Options>,
+		options?: { label?: string; navOptions?: NavigationOptions },
+	) {
+		this.page = page;
+		this.baseUrl = baseUrl;
+		this.urlPath = urlPath;
+		this.fullUrl = this.composeFullUrl(baseUrl, urlPath);
+		const label = options?.label ?? this.constructor.name;
+		this.label = label;
+		const { registry, add, getLocator, getNestedLocator, getLocatorSchema } =
+			createRegistryWithAccessors<LocatorSchemaPathType>(page);
+		this.locatorRegistry = registry;
+		this.add = add;
+		this.getLocator = getLocator;
+		this.getLocatorSchema = getLocatorSchema;
+		this.getNestedLocator = getNestedLocator;
+		this.sessionStorage = new SessionStorage(page, { label });
+
+		this.defineLocators();
+		this.navigation = createNavigation(
+			this.page,
+			this.baseUrl,
+			this.urlPath,
+			this.fullUrl,
+			this.label,
+			this.pageActionsToPerformAfterNavigation(),
+			options?.navOptions,
+		);
+	}
+
+	protected abstract defineLocators(): void;
+	protected abstract pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null;
+
+	private composeFullUrl(
+		baseUrl: BaseUrlTypeFromOptions<Options>,
+		urlPath: UrlPathTypeFromOptions<Options>,
+	): FullUrlTypeFromOptions<Options> {
+		const escapeRegex = (value: string) => value.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+
+		if (typeof baseUrl === "string" && typeof urlPath === "string") {
+			return `${baseUrl}${urlPath}` as FullUrlTypeFromOptions<Options>;
+		}
+		if (typeof baseUrl === "string" && urlPath instanceof RegExp) {
+			return new RegExp(`^${escapeRegex(baseUrl)}${urlPath.source}`) as FullUrlTypeFromOptions<Options>;
+		}
+		if (baseUrl instanceof RegExp && typeof urlPath === "string") {
+			return new RegExp(`${baseUrl.source}${escapeRegex(urlPath)}$`) as FullUrlTypeFromOptions<Options>;
+		}
+		if (baseUrl instanceof RegExp && urlPath instanceof RegExp) {
+			return new RegExp(`${baseUrl.source}${urlPath.source}`) as FullUrlTypeFromOptions<Options>;
+		}
+		throw new Error("Invalid baseUrl or urlPath types. Expected string or RegExp.");
+	}
+}