Registration

add(path) returns a registration: the ten locator methods, one of which registers the path, then the steps filter, nth and describe. Its type is not exported. It ends at the next call on the registry, after which every method of it throws; see registered locators do not change.

registry.add("main").locator("main");
registry.add("main.list").locator("ul.orders");
registry.add("main.list.item").getByRole("listitem").filter({ hasText: "Open" }).nth(0);
// main.list.item: locator('main').locator('ul.orders').getByRole('listitem').filter({ hasText: 'Open' }).first()

The chains on this page are shown without the description, which is the path unless describe sets one. Guides: registering locators, filters and indices, reusing locators.

---

Locator methods

Each takes the arguments of the Playwright method it is named after and returns the registration, for filter, nth and describe. Each throws at the call, naming the method and the path, when its first argument is missing (from JavaScript) or is an empty string where Playwright cannot use one, when the path already has a locator, when the registration has ended, and, from JavaScript, when the path breaks the path rules:

getByRole requires a role value for "main.button@save".
A locator schema with the path "main" already exists.
A locator definition for "main" has already been provided; only one locator type can be set for a registration.
getByRole() cannot apply to "main.button@save": its registration has ended; give a registration all its steps in its add(…) chain, or query the path for one use.
LocatorSchemaPath string cannot contain consecutive dots: main..list

The second message goes on with the existing and the attempted locator; the third is a second locator method on one registration; the fourth a locator method of a registration kept in a variable after the registry was called again.

frameLocator()

Registers a frame segment: with a selector, the <iframe> element, whose descendants resolve inside the frame; without one, Playwright’s any-frame page.frameLocator(). See frames and any frame.

Usage

registry.add("shell").locator("div.shell");
registry.add("shell.frame@payment").frameLocator("iframe#payment");
registry.add("shell.frame@payment.button@pay").getByRole("button", { name: "Pay" });
// locator('div.shell').locator('iframe#payment').contentFrame().getByRole('button', { name: 'Pay' })

registry.add("anyFrame").frameLocator();
registry.add("anyFrame.button@accept").getByRole("button", { name: "Accept" });
// frameLocator().getByRole('button', { name: 'Accept' })

Arguments

• selector string (optional)

  The <iframe> element’s selector. Without it, the any-frame form, which must be the first segment of its chain and takes no steps.

Returns

• the registration, with a selector; undefined without one

Throws

frameLocator requires a non-empty selector for "shell.frame".

An any-frame segment that is not the first segment of its chain fails verify() and every resolution through it:

frameLocator() without a selector must be the first segment of the chain; "shell.anyFrame" has the ancestor "shell".

getByAltText()

Registers the path’s locator as Playwright’s page.getByAltText(): an element, usually an image, by its alt text.

Usage

registry.add("header.image@logo").getByAltText("Shop logo");
// getByAltText('Shop logo')

Arguments

• text string | RegExp
• options Object (optional): Playwright’s options, exact.

An empty string is a value Playwright matches and is stored as given.

Returns

• the registration

getById()

Registers a locator by the id attribute, which Playwright has no method for: a string as written, a RegExp with its flags. See locating by id.

Usage

registry.add("main.panel@settings").getById("settings.panel");
// selector: [id="settings.panel"]
registry.add("main.button@submit").getById(/^button\.submit\.[a-z0-9]{4}$/i);
// selector: internal:attr=[id=/^button\.submit\.[a-z0-9]{4}$/i]

Arguments

• id string | RegExp

  The id as written, without a #; or a pattern, unanchored unless you anchor it.

Returns

• the registration

Throws

getById requires a non-empty id for "main.panel@settings".

getByLabel()

Registers the path’s locator as Playwright’s page.getByLabel(): an input by its <label>, aria-labelledby or aria-label.

Usage

registry.add("main.form.input@email").getByLabel("Email", { exact: true });
// getByLabel('Email', { exact: true })

Arguments

• text string | RegExp
• options Object (optional): Playwright’s options, exact.

Returns

• the registration

getByPlaceholder()

Registers the path’s locator as Playwright’s page.getByPlaceholder(): an input by its placeholder.

Usage

registry.add("main.input@search").getByPlaceholder("Search");
// getByPlaceholder('Search')

Arguments

• text string | RegExp
• options Object (optional): Playwright’s options, exact.

Returns

• the registration

getByRole()

Registers the path’s locator as Playwright’s page.getByRole(): by ARIA role, accessible name and state. Which strings are roles is Playwright’s own type, with completion in the editor.

Usage

registry.add("main.button@save").getByRole("button", { name: "Save" });
// getByRole('button', { name: 'Save' })

Arguments

• role string

  An ARIA role; an empty one is rejected.

• options Object (optional): Playwright’s getByRole options, such as name, exact and level.

Returns

• the registration

Throws

getByRole requires a non-empty role for "main.heading".

getByTestId()

Registers the path’s locator as Playwright’s page.getByTestId(), by the attribute the project’s testIdAttribute names.

Usage

registry.add("main.row@order").getByTestId("order-row");
// getByTestId('order-row')

Arguments

• testId string | RegExp

  An empty string is a value Playwright matches (data-testid="") and is stored as given.

Returns

• the registration

getByText()

Registers the path’s locator as Playwright’s page.getByText(): by the text an element contains.

Usage

registry.add("main.alert@error").getByText(/failed/i);
// getByText(/failed/i)

Arguments

• text string | RegExp
• options Object (optional): Playwright’s options, exact.

An empty string is a value Playwright matches and is stored as given.

Returns

• the registration

getByTitle()

Registers the path’s locator as Playwright’s page.getByTitle(): an element by its title attribute.

Usage

registry.add("main.icon@info").getByTitle("More information");
// getByTitle('More information')

Arguments

• text string | RegExp
• options Object (optional): Playwright’s options, exact.

Returns

• the registration

locator()

Registers the path’s locator as Playwright’s page.locator(): by a CSS or other Playwright selector.

Usage

registry.add("main.list").locator("ul.orders");
// locator('ul.orders')

Arguments

• selector string

  An empty selector is rejected: Playwright cannot parse it.

• options Object (optional): Playwright’s locator options, such as hasText and has.

Returns

• the registration

Throws

locator requires a non-empty selector for "main.list".

---

Steps

Available after a locator method, chained in any order and number, and applied in that order. A step of a registration kept in a variable, after the registry was called again, throws:

nth() cannot apply to "main.list.item": its registration has ended; give a registration all its steps in its add(…) chain, or query the path for one use.

From JavaScript, a step before the locator method throws:

filter() needs a locator strategy first for "main.list.item"; call getByRole, getByText, getByLabel, getByPlaceholder, getByAltText, getByTitle, locator, frameLocator, getByTestId or getById before it.

describe()

Sets the description of the resolved locator, instead of the path, as locator.describe() does; "" removes it. See descriptions.

Usage

registry.add("main.list.item@first").getByRole("listitem").nth("first").describe("First order");

Arguments

• description string

Returns

• the registration

Throws

describe requires a string for "main.list.item@first"; pass "" to remove the description.

filter()

Adds a locator.filter() step; has and hasNot also take a registered path. See filters.

Usage

registry.add("main.section@orders.heading").getByRole("heading", { name: "Orders" });
registry.add("main.section@orders").locator("section").filter({ has: "main.section@orders.heading" });

Arguments

• filter FilterDefinition

  Playwright’s filter options, hasText, hasNotText, has, hasNot and visible, with a registered path allowed for has and hasNot.

Returns

• the registration

A has path that is not registered, or a cycle of has paths, fails verify().

nth()

Adds an index step: "first" and "last" become Playwright’s first() and last(), and a number goes to nth() as given (-1 is the last element).

Usage

registry.add("main.list.item@last").getByRole("listitem").nth("last");
// getByRole('listitem').last()

Arguments

• index number | “first” | “last”

Returns

• the registration

---

After { reuse }

add(path, { reuse }) registers the path at once. What it returns depends on what is reused.

A registered path

The path is a copy of the reused one, which filter, nth and describe narrow; there is no locator method. See reuse by path.

registry.add("main").locator("main");
registry.add("main.list").locator("ul");
registry.add("main.list.items@open").getByRole("listitem").filter({ hasText: "Open" });
registry.add("main.list.item@lastOpen", { reuse: "main.list.items@open" }).nth("last").describe("Last open item");
// locator('main').locator('ul').getByRole('listitem').filter({ hasText: 'Open' }).last()

A seed

The seed is registered as it is. Its own locator method may patch it once, as update() does, then come filter, nth and describe. See changing a seed’s options.

const saveButton = registry.createReusable.getByRole("button", { name: "Save", exact: true });

registry.add("main.button@cancel", { reuse: saveButton }).getByRole({ name: "Cancel" });
// getByRole('button', { name: 'Cancel', exact: true })
registry.add("main.link@plain", { reuse: saveButton }).getByRole("link", null);
// getByRole('link')

Throws

The locator definition for "main.button@cancel" must use the "role" strategy when reusing a locator.
A locator definition for "main.link@help" was already provided from reuse; only one matching override is allowed.

The first for another strategy’s method, the second for a second change on a registration kept in a variable.