pomwright 1.3.0 → 1.5.0

package/intTestV2/tests/locatorRegistry/add/add.getByRole.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+const errMsg = "No locator schema registered for path";
+
+test("add getByRole to registry", async ({ page }) => {
+	type LocatorSchemaPaths = "buttonByRole";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	expect(() => registry.get("buttonByRole")).toThrowError(`${errMsg} "buttonByRole".`);
+
+	registry.add("buttonByRole").getByRole("button", { name: "Submit" });
+
+	expect(registry.get("buttonByRole")).toEqual({
+		definition: { role: "button", options: { name: "Submit" }, type: "role" },
+		locatorSchemaPath: "buttonByRole",
+		steps: [],
+	});
+});

package/intTestV2/tests/locatorRegistry/add/add.getByTestId.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+const errMsg = "No locator schema registered for path";
+
+test("add getByTestId to registry", async ({ page }) => {
+	type LocatorSchemaPaths = "elementByTestId";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	expect(() => registry.get("elementByTestId")).toThrowError(`${errMsg} "elementByTestId".`);
+
+	registry.add("elementByTestId").getByTestId("login-button");
+
+	expect(registry.get("elementByTestId")).toEqual({
+		definition: { testId: "login-button", type: "testId" },
+		locatorSchemaPath: "elementByTestId",
+		steps: [],
+	});
+});

package/intTestV2/tests/locatorRegistry/add/add.getByText.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+const errMsg = "No locator schema registered for path";
+
+test("add getByText to registry", async ({ page }) => {
+	type LocatorSchemaPaths = "elementByText";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	expect(() => registry.get("elementByText")).toThrowError(`${errMsg} "elementByText".`);
+
+	registry.add("elementByText").getByText("Welcome");
+
+	expect(registry.get("elementByText")).toEqual({
+		definition: { text: "Welcome", type: "text" },
+		locatorSchemaPath: "elementByText",
+		steps: [],
+	});
+});

package/intTestV2/tests/locatorRegistry/add/add.getByTitle.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+const errMsg = "No locator schema registered for path";
+
+test("add getByTitle to registry", async ({ page }) => {
+	type LocatorSchemaPaths = "elementByTitle";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	expect(() => registry.get("elementByTitle")).toThrowError(`${errMsg} "elementByTitle".`);
+
+	registry.add("elementByTitle").getByTitle("Home Page");
+
+	expect(registry.get("elementByTitle")).toEqual({
+		definition: { text: "Home Page", type: "title" },
+		locatorSchemaPath: "elementByTitle",
+		steps: [],
+	});
+});

package/intTestV2/tests/locatorRegistry/add/add.locator.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+const errMsg = "No locator schema registered for path";
+
+test("add locator to registry", async ({ page }) => {
+	type LocatorSchemaPaths = "body";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	expect(() => registry.get("body")).toThrowError(`${errMsg} "body".`);
+
+	registry.add("body").locator("body");
+
+	expect(registry.get("body")).toEqual({
+		definition: { selector: "body", type: "locator" },
+		locatorSchemaPath: "body",
+		steps: [],
+	});
+});

package/intTestV2/tests/locatorRegistry/add/add.reuseExisting.spec.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+test("add reuses with existing record by path does not have chainable methods", async ({ page }) => {
+	type LocatorSchemaPaths = "button" | "button.copy";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.add("button").getByRole("button", { name: "Submit" }).filter({ hasText: "Submit" });
+
+	const builder = registry.add("button.copy", { reuse: "button" });
+
+	expect(builder).toBeUndefined();
+	expect(registry.get("button.copy")).toEqual({
+		definition: { role: "button", options: { name: "Submit" }, type: "role" },
+		locatorSchemaPath: "button.copy",
+		steps: [{ filter: { hasText: "Submit" }, kind: "filter" }],
+	});
+});
+
+test("add reuse by path clones records so mutations do not leak", async ({ page }) => {
+	type LocatorSchemaPaths = "button" | "button.copy";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.add("button").getByRole("button", { name: "Submit" }).filter({ hasText: "Submit" });
+
+	registry.add("button.copy", { reuse: "button" });
+
+	expect(registry.get("button.copy")).toEqual({
+		definition: { role: "button", options: { name: "Submit" }, type: "role" },
+		locatorSchemaPath: "button.copy",
+		steps: [{ filter: { hasText: "Submit" }, kind: "filter" }],
+	});
+
+	registry.replace("button.copy", {
+		definition: { role: "link", options: { name: "Copy" }, type: "role" },
+		locatorSchemaPath: "button.copy",
+		steps: [{ filter: { hasText: "Copy" }, kind: "filter" }],
+	});
+
+	expect(registry.get("button.copy")).toEqual({
+		definition: { role: "link", options: { name: "Copy" }, type: "role" },
+		locatorSchemaPath: "button.copy",
+		steps: [{ filter: { hasText: "Copy" }, kind: "filter" }],
+	});
+
+	expect(registry.get("button")).toEqual({
+		definition: { role: "button", options: { name: "Submit" }, type: "role" },
+		locatorSchemaPath: "button",
+		steps: [{ filter: { hasText: "Submit" }, kind: "filter" }],
+	});
+});
+
+test("add reuse by path throws when the source path is missing", async ({ page }) => {
+	type LocatorSchemaPaths = "button" | "button.copy";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	expect(() => registry.add("button.copy", { reuse: "button" })).toThrowError(
+		'No locator schema registered for path "button".',
+	);
+});

package/intTestV2/tests/locatorRegistry/add/add.reuseReusable.spec.ts

@@ -0,0 +1,311 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { type FilterDefinition, LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+test("add can reuse a reusable locator definition", async ({ page }) => {
+	type LocatorSchemaPaths = "heading" | "heading.first";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const h2 = registry.createReusable.getByRole("heading", { level: 2 }).filter({ hasText: /Summary/ });
+
+	registry.add("heading", { reuse: h2 });
+	registry.add("heading.first", { reuse: h2 }).nth(0);
+
+	expect(registry.get("heading")).toEqual({
+		definition: { role: "heading", options: { level: 2 }, type: "role" },
+		locatorSchemaPath: "heading",
+		steps: [{ filter: { hasText: /Summary/ }, kind: "filter" }],
+	});
+
+	expect(registry.get("heading.first")).toEqual({
+		definition: { role: "heading", options: { level: 2 }, type: "role" },
+		locatorSchemaPath: "heading.first",
+		steps: [
+			{ filter: { hasText: /Summary/ }, kind: "filter" },
+			{ index: 0, kind: "index" },
+		],
+	});
+});
+
+test("reusable builder yields the same locator chain as a direct definition", async ({ page }) => {
+	type LocatorSchemaPaths = "heading" | "heading.reused";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const reusable = registry.createReusable.getByRole("heading", { level: 2 }).filter({ hasText: "Intro" }).nth(1);
+
+	registry.add("heading").getByRole("heading", { level: 2 }).filter({ hasText: "Intro" }).nth(1);
+	registry.add("heading.reused", { reuse: reusable });
+
+	const direct = registry.getLocator("heading");
+	const reused = registry.getLocator("heading.reused");
+
+	expect(`${reused}`).toEqual(`${direct}`);
+});
+
+test("add reuse by reusable locator patches options while preserving selector", async ({ page }) => {
+	type LocatorSchemaPaths = "errorMessage" | "error.invalidPassword";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const errorMessage = registry.createReusable.locator("error-message");
+	registry.add("errorMessage", { reuse: errorMessage });
+	registry.add("error.invalidPassword", { reuse: errorMessage }).locator({ hasText: /invalid password/ });
+
+	expect(registry.get("errorMessage")).toEqual({
+		definition: { selector: "error-message", type: "locator" },
+		locatorSchemaPath: "errorMessage",
+		steps: [],
+	});
+
+	expect(registry.get("error.invalidPassword")).toEqual({
+		definition: { options: { hasText: /invalid password/ }, selector: "error-message", type: "locator" },
+		locatorSchemaPath: "error.invalidPassword",
+		steps: [],
+	});
+});
+
+test("add reuse by reusable locator inherits selector and discriminant", async ({ page }) => {
+	type LocatorSchemaPaths = "errorMessage" | "error.invalidPassword";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const errorMessage = registry.createReusable.locator("error-message", { hasText: /invalid password/ });
+	registry.add("errorMessage", { reuse: errorMessage });
+	registry.add("error.invalidPassword", { reuse: errorMessage }).locator({ hasText: /invalid email/ });
+
+	expect(registry.get("errorMessage")).toEqual({
+		definition: { options: { hasText: /invalid password/ }, selector: "error-message", type: "locator" },
+		locatorSchemaPath: "errorMessage",
+		steps: [],
+	});
+
+	expect(registry.get("error.invalidPassword")).toEqual({
+		definition: { options: { hasText: /invalid email/ }, selector: "error-message", type: "locator" },
+		locatorSchemaPath: "error.invalidPassword",
+		steps: [],
+	});
+});
+
+test("add reuse with a reusable locator does not mutate the reusable definition", async ({ page }) => {
+	type LocatorSchemaPaths = "heading" | "heading.first";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const reusable = registry.createReusable.getByRole("heading", { level: 2 }).filter({ hasText: /Summary/ });
+
+	registry.add("heading", { reuse: reusable });
+	registry.add("heading.first", { reuse: reusable }).nth(0);
+
+	expect(reusable.steps).toEqual([{ filter: { hasText: /Summary/ }, kind: "filter" }]);
+	expect(registry.get("heading")).toEqual({
+		definition: { role: "heading", options: { level: 2 }, type: "role" },
+		locatorSchemaPath: "heading",
+		steps: [{ filter: { hasText: /Summary/ }, kind: "filter" }],
+	});
+
+	expect(registry.get("heading.first")).toEqual({
+		definition: { role: "heading", options: { level: 2 }, type: "role" },
+		locatorSchemaPath: "heading.first",
+		steps: [
+			{ filter: { hasText: /Summary/ }, kind: "filter" },
+			{ index: 0, kind: "index" },
+		],
+	});
+});
+
+test("add reuse enforces matching locator type overrides", async ({ page }) => {
+	type LocatorSchemaPaths = "button" | "button.reuseLocator";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const button = registry.createReusable.getByRole("button", { name: "Submit" });
+
+	// @ts-expect-error mismatched locator strategies are not allowed when reusing a locator (getByText attempt on role locator)
+	expect(() => registry.add("button", { reuse: button }).getByText("text")).toThrowError(
+		'must use the "role" strategy',
+	);
+
+	registry.add("button", { reuse: button });
+
+	expect(registry.get("button")).toEqual({
+		definition: { role: "button", options: { name: "Submit" }, type: "role" },
+		locatorSchemaPath: "button",
+		steps: [],
+	});
+
+	// @ts-expect-error mismatched locator strategies are not allowed when reusing a locator (getById attempt on role locator)
+	expect(() => registry.add("button.reuseLocator", { reuse: button }).getById("Submit")).toThrowError(
+		'must use the "role" strategy',
+	);
+
+	registry.add("button.reuseLocator", { reuse: button }).getByRole({ name: "Submit" });
+
+	expect(registry.get("button.reuseLocator")).toEqual({
+		definition: { role: "button", options: { name: "Submit" }, type: "role" },
+		locatorSchemaPath: "button.reuseLocator",
+		steps: [],
+	});
+});
+
+test("add reuse patches role options while preserving role value", async ({ page }) => {
+	type LocatorSchemaPaths = "heading";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+	const h2 = registry.createReusable.getByRole("heading", { level: 2 });
+
+	registry.add("heading", { reuse: h2 }).getByRole({ name: "Summary" });
+
+	expect(registry.get("heading")).toEqual({
+		definition: { role: "heading", options: { level: 2, name: "Summary" }, type: "role" },
+		locatorSchemaPath: "heading",
+		steps: [],
+	});
+});
+
+test("add reuse typing narrows override methods to the matching strategy", async ({ page }) => {
+	type LocatorSchemaPaths = "button";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+	const button = registry.createReusable.getByRole("button", { name: "Submit" });
+	const builder = registry.add("button", { reuse: button });
+
+	// @ts-expect-error mismatched locator strategies are not exposed when reusing a locator
+	const _invalidOverrideMethod = builder.getByText;
+
+	builder.getByRole({ name: "Submit" });
+});
+
+test("add reuse allows only one matching locator override", async ({ page }) => {
+	type LocatorSchemaPaths = "heading";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+	const h2 = registry.createReusable.getByRole("heading", { level: 2 });
+
+	const builder = registry.add("heading", { reuse: h2 });
+
+	builder.getByRole("heading", { name: "Summary" });
+
+	expect(() => builder.getByRole("heading", { name: "Other" })).toThrowError("only one matching override is allowed");
+});
+
+test("createReusable.filter supports Playwright Locator instances for has/hasNot", async ({ page }) => {
+	type LocatorSchemaPaths = "item";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const seed = registry.createReusable
+		.getByRole("button")
+		.filter({ has: page.getByRole("heading", { level: 2 }) })
+		.filter({ hasNot: page.getByRole("heading", { level: 3 }) });
+
+	registry.add("item", { reuse: seed });
+
+	const locator = registry.getLocator("item");
+
+	expect(`${locator}`).toEqual(
+		"getByRole('button').filter({ has: getByRole('heading', { level: 2 }) }).filter({ hasNot: getByRole('heading', { level: 3 }) })",
+	);
+});
+
+test("createReusable.filter supports registry path strings for has/hasNot", async ({ page }) => {
+	type LocatorSchemaPaths = "item" | "heading.primary" | "heading.secondary";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.add("heading.primary").getByRole("heading", { level: 2 });
+	registry.add("heading.secondary").getByRole("heading", { level: 3 });
+
+	const seed = registry.createReusable
+		.getByRole("button")
+		.filter({ has: "heading.primary" })
+		.filter({ hasNot: "heading.secondary" });
+
+	registry.add("item", { reuse: seed });
+
+	const locator = registry.getLocator("item");
+
+	expect(`${locator}`).toEqual(
+		"getByRole('button').filter({ has: getByRole('heading', { level: 2 }) }).filter({ hasNot: getByRole('heading', { level: 3 }) })",
+	);
+});
+
+test("createReusable.filter rejects inline locator strategy definitions for has/hasNot", async ({ page }) => {
+	type LocatorSchemaPaths = "item";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.createReusable
+		.getByRole("button")
+		// @ts-expect-error inline locator definitions are no longer supported
+		.filter({ has: { type: "locator", selector: "section" } });
+
+	const unsafeFilter = {
+		has: { type: "locator", selector: "section" },
+	} as unknown as FilterDefinition<LocatorSchemaPaths, LocatorSchemaPaths>;
+
+	const unsafeSeed = registry.createReusable.getByRole("button").filter(unsafeFilter);
+
+	registry.add("item", { reuse: unsafeSeed });
+
+	expect(() => registry.getLocator("item")).toThrow(/Unsupported filter reference/);
+});
+
+test("createReusable.filter rejects locator wrappers for has/hasNot", async ({ page }) => {
+	type LocatorSchemaPaths = "item";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.createReusable
+		.getByRole("button")
+		// @ts-expect-error locator wrapper is no longer supported
+		.filter({ has: { locator: { type: "locator", selector: "section" } } });
+
+	const unsafeFilter = {
+		has: { locator: { type: "locator", selector: "section" } },
+	} as unknown as FilterDefinition<LocatorSchemaPaths, LocatorSchemaPaths>;
+
+	const unsafeSeed = registry.createReusable.getByRole("button").filter(unsafeFilter);
+
+	registry.add("item", { reuse: unsafeSeed });
+
+	expect(() => registry.getLocator("item")).toThrow(/Unsupported filter reference/);
+});
+
+test("createReusable.filter rejects locatorPath wrappers for has/hasNot", async ({ page }) => {
+	type LocatorSchemaPaths = "item";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.createReusable
+		.getByRole("button")
+		// @ts-expect-error locatorPath wrapper is no longer supported
+		.filter({ has: { locatorPath: "item" } });
+
+	const unsafeFilter = {
+		has: { locatorPath: "item" },
+	} as unknown as FilterDefinition<LocatorSchemaPaths, LocatorSchemaPaths>;
+
+	const unsafeSeed = registry.createReusable.getByRole("button").filter(unsafeFilter);
+
+	registry.add("item", { reuse: unsafeSeed });
+
+	expect(() => registry.getLocator("item")).toThrow(/Unsupported filter reference/);
+});
+
+test("createReusable.filter supports visible true/false", async ({ page }) => {
+	type LocatorSchemaPaths = "item";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const seed = registry.createReusable.getByRole("button").filter({ visible: true }).filter({ visible: false });
+
+	registry.add("item", { reuse: seed });
+
+	const locator = registry.getLocator("item");
+
+	expect(`${locator}`).toEqual("getByRole('button').filter({ visible: true }).filter({ visible: false })");
+});

package/intTestV2/tests/locatorRegistry/add/add.spec.ts

@@ -0,0 +1,159 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+test("add regex-driven getBy* registrations to registry", async ({ page }) => {
+	type LocatorSchemaPaths =
+		| "regex.text"
+		| "regex.label"
+		| "regex.placeholder"
+		| "regex.altText"
+		| "regex.title"
+		| "regex.reuse.text"
+		| "regex.reusePath.text";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.add("regex.text").getByText(/Welcome/i);
+	registry.add("regex.label").getByLabel(/Username/i);
+	registry.add("regex.placeholder").getByPlaceholder(/Enter your name/i);
+	registry.add("regex.altText").getByAltText(/Sample Image/i);
+	registry.add("regex.title").getByTitle(/Home Page/i);
+
+	const reusableText = registry.createReusable.getByText(/Seeded/i);
+	registry.add("regex.reuse.text", { reuse: reusableText }).getByText({ exact: true });
+	registry.add("regex.reusePath.text", { reuse: "regex.text" });
+
+	expect(registry.get("regex.text")).toEqual({
+		definition: { text: /Welcome/i, type: "text" },
+		locatorSchemaPath: "regex.text",
+		steps: [],
+	});
+	expect(registry.get("regex.label")).toEqual({
+		definition: { text: /Username/i, type: "label" },
+		locatorSchemaPath: "regex.label",
+		steps: [],
+	});
+	expect(registry.get("regex.placeholder")).toEqual({
+		definition: { text: /Enter your name/i, type: "placeholder" },
+		locatorSchemaPath: "regex.placeholder",
+		steps: [],
+	});
+	expect(registry.get("regex.altText")).toEqual({
+		definition: { text: /Sample Image/i, type: "altText" },
+		locatorSchemaPath: "regex.altText",
+		steps: [],
+	});
+	expect(registry.get("regex.title")).toEqual({
+		definition: { text: /Home Page/i, type: "title" },
+		locatorSchemaPath: "regex.title",
+		steps: [],
+	});
+	expect(registry.get("regex.reuse.text")).toEqual({
+		definition: { text: /Seeded/i, options: { exact: true }, type: "text" },
+		locatorSchemaPath: "regex.reuse.text",
+		steps: [],
+	});
+	expect(registry.get("regex.reusePath.text")).toEqual({
+		definition: { text: /Welcome/i, type: "text" },
+		locatorSchemaPath: "regex.reusePath.text",
+		steps: [],
+	});
+});
+
+test("add prevents multiple locator type definitions", async ({ page }) => {
+	type LocatorSchemaPaths = "heading";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const builder = registry.add("heading").getByRole("heading", { level: 2 });
+
+	expect((builder as { getByText?: unknown }).getByText).toBeUndefined();
+
+	builder.filter({ hasText: "Heading" }).nth(0);
+});
+
+test("add typing narrows locator methods after a definition is chosen", async ({ page }) => {
+	type LocatorSchemaPaths = "heading";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+	const postDefinition = registry.add("heading").getByRole("heading", { level: 2 });
+
+	// @ts-expect-error additional locator methods are not exposed after a definition is set
+	const _invalidLocatorMethod = postDefinition.getByText;
+
+	postDefinition.filter({ hasText: "Heading" }).nth(0);
+});
+
+test("A LocatorSchemaPath can only be added once", async ({ page }) => {
+	type LocatorSchemaPaths = "body";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.add("body").locator("body");
+
+	const errMsg = /A locator schema with the path "body" already exists*/;
+
+	expect(() => registry.add("body").locator("someone elses body")).toThrowError(errMsg);
+});
+
+test("add getByRole overloads accept optional options and support chained steps", async ({ page }) => {
+	type LocalPath = "root" | "root.options" | "root.minimal";
+	const registry = new LocatorRegistryInternal<LocalPath>(page);
+
+	registry.add("root").locator("body");
+
+	registry.add("root.options").getByRole("button", { name: "opts" }).filter({ hasText: "filtered" }).nth("last");
+	registry.add("root.minimal").getByRole("button");
+
+	expect(registry.get("root.options")).toEqual({
+		locatorSchemaPath: "root.options",
+		definition: { type: "role", role: "button", options: { name: "opts" } },
+		steps: [
+			{ kind: "filter", filter: { hasText: "filtered" } },
+			{ kind: "index", index: "last" },
+		],
+	});
+
+	expect(registry.get("root.minimal")).toEqual({
+		locatorSchemaPath: "root.minimal",
+		definition: { type: "role", role: "button" },
+		steps: [],
+	});
+});
+
+test("add overloads support other strategies with options and chained steps", async ({ page }) => {
+	type LocalPath = "root.text" | "root.locator" | "root.frame";
+
+	const registry = new LocatorRegistryInternal<LocalPath>(page);
+
+	registry.add("root.text").getByText("needle", { exact: true }).filter({ hasText: "filtered" }).nth(0);
+	registry.add("root.locator").locator(".selector", { hasText: "opt" }).filter({ hasText: "filtered" }).nth(0);
+	registry.add("root.frame").frameLocator("iframe[name=child]");
+
+	expect(registry.get("root.text")).toEqual({
+		locatorSchemaPath: "root.text",
+		definition: { type: "text", text: "needle", options: { exact: true } },
+		steps: [
+			{ kind: "filter", filter: { hasText: "filtered" } },
+			{ kind: "index", index: 0 },
+		],
+	});
+
+	expect(registry.get("root.locator")).toEqual({
+		locatorSchemaPath: "root.locator",
+		definition: { type: "locator", selector: ".selector", options: { hasText: "opt" } },
+		steps: [
+			{ kind: "filter", filter: { hasText: "filtered" } },
+			{ kind: "index", index: 0 },
+		],
+	});
+
+	expect(registry.get("root.frame")).toEqual({
+		locatorSchemaPath: "root.frame",
+		definition: { type: "frameLocator", selector: "iframe[name=child]" },
+		steps: [],
+	});
+});