To be able to test elements you need to be able to select elements on the page. With Playwright there are so many different ways to select elements from role to text, css, x-path and more. With the old selectors it was difficult to know which selector you should be using and there was no type completion meaning you could easily create typos. Playwright users were asking us for good guidance on how to select and how to create locators.

Now Playwright has this guidance in the shape and form of these beautiful 7 methods. A designated API on how you create locators complete with type checking. If you use these methods exclusively then you will have really reliable and good tests.

page.getByRole(role, options)
page.getByLabel(label, options)
page.getByPlaceholder(placeholder, options)
page.getByText(text, options)
page.getByAltText(altText, options)
page.getByTitle(title, options)
page.getByTestId(testId)

The number one recommendation is to use the getByRole query first. This will search through the accessibility tree and allows you to specify an accessible name which helps a lot with the accessibility of your application and testing this aspect of it.

Instead of looking for something that has the text "Sign in" you are going to be looking for an element that has a role of "button" with the name of "Sign in". You don't have to specify the role yourself as the role for a button is an implicit role. For elements that don't have a specified role you can use getByText.

This is going to drastically improve the readability of your tests and the accessibility of your UI's.

Locator Best Practice

Prefer new getBy* API to select elements which are available on the page, locator and frameLocator classes. The old methods are still supported but the new API is much more readable and is now the recommended way to write locators.

Before:

page.locator('text=Submit');
page.locator('role=button');
page.locator('text=Password');
page.locator('[placeholder="Search Github"]');
page.locator('[alt="castle"]');
page.locator('[title="Place the order"]');
page.locator('data-testid="submit"]');

After:

page.getByText('Submit');
page.getByRole('button');
page.getByLabel('Password')
page.getByPlaceholder('Search Github')
page.getByAltText('castle')
page.getByTitle('Place the order')
page.getByTestId('submit')

Choosing which Locators

When generating your tests with Codegen, Playwrights test generator, hover over an element on the page and it will show a black box under the cursor with the best locator for that element. Once you interact with the page by clicking or typing Codegen will write the test using these new API's.

When using the VS Code extension you can click on Pick Selector and hover over elements to see the locators. Clicking on the browser will save the locator to the pick selector box where you can press enter to copy the code into your clipboard so you can easily paste it into your code.

Check out the release video to learn more about the new API:

If you want to get started make sure you check out our getting started section in the docs or check out the VS Code Extension.