Descriptions

Introduction

Playwright lets you name a locator with locator.describe(): the report and some error messages then show the name instead of the selector chain. POMWright gives every locator it resolves a description, its path, so a report reads main.form@login.button@login where it would otherwise show a long chain.

The path by default

getNestedLocator and getLocator both describe the locator by its path:

registry.add("main").locator("main");
registry.add("main.button@login").getByRole("button", { name: "Log in" });

registry.getNestedLocator("main.button@login").description(); // "main.button@login"
registry.getLocator("main.button@login").description(); // "main.button@login"

Only the resolved path’s description is used; the descriptions of its ancestors never show.

Where Playwright shows it

where	with the description	without one
toString(), description()	main.button@login	the chain; description() is null
the HTML report’s row of an action or assertion	Click main.button@login	the chain
an assertion error’s Locator: line	Locator: main.button@login	the chain
the call log of every action and assertion	waiting for locator('main').getByRole('button', { name: 'Log in' })	the same
a strict mode error	strict mode violation: locator('main').getByRole('button', { name: 'Log in' }) resolved to 2 elements	the same

So a report stays readable, and a failure’s call log still shows the chain Playwright waited for.

Your own description

describe on a registration replaces the path with your text for every use:

registry.add("main.button@submit").getByRole("button", { name: "Submit" }).describe("Primary submit button");

registry.getLocator("main.button@submit").description(); // "Primary submit button"

On a query it replaces the registered description or the path for that one use, and leaves the registry as it is:

registry.getLocatorSchema("main.button@submit").describe("Submit after editing").getLocator();

A seed and a path reuse carry an explicit description to the paths they are registered at; without one, the new path describes itself (see Reusing locators).

No description

describe("") removes the description, as Playwright’s own describe("") does: the locator prints as its chain. That is the quickest way to see what a path resolves to:

registry.getLocatorSchema("main.button@submit").describe("").getLocator().toString();
// getByRole('button', { name: 'Submit' })

The argument is a string. From JavaScript, describe(null) or describe(undefined) throws: describe requires a string for "main.button@submit"; pass "" to remove the description.

Chaining further

A locator you chain further yourself is a new Playwright locator, and Playwright gives it no description: registry.getNestedLocator("main").locator("li") prints locator('main').locator('li'). Register the path instead when it is worth a name.

Reference

• describe() on the registration builder, on a query and on a seed
• Playwright: locator.describe(), locator.description()