Repository navigation
[Feature] extend Locator API with helper methods #16785
Description
As an example, I would like to introduce findByRole method that is equivalent to:
page.locator(
`role=${role}[name="${name}"]`
)I have figured out how to add this to Page object,
This allows me to write code like:
await page.findByRole('link', 'Services').click();However, this breaks when chaining Locator instances, e.g.
await page
.locator('role=dialog')
- .locator('role=link[name="Create A Service"]')
+ .findByRole('link', 'Create A Service')
.click();The above is throwing an error since .locator('role=dialog') is returning an instance of a Locator that is not aware of findByRole.
Reacted by Emil Ong, Andrey Kuleshov, marc-guenther and Bryce Carr
Activity
yury-s commentedon Aug 23, 2022
Gajus Kuizinas (@gajus) do you have a particular API in mind that Playwright could expose to support such extensibility?
You can already wrap a locator in another object with the extended interface similar to how you did with the page (you'd need to override Page.locator to return a wrapper instead of the original locator). You'd also need to proxy all locator methods and also ensure that the methods that return a new instance of Locator also return wrapped objects. It will not work with the playwright API methods that accept Locator as argument (e..g. has option) so they'd have to be unwrapped before being passed into the method.
Related issue #13517
gajus commentedon Aug 24, 2022
Is there a reason we could not use the same pattern that we use for fixtures?
Internals would need to be rewritten to use refer to
locatorthat comes fromtest.yury-s commentedon Aug 24, 2022
The fixtures are a part of the test runner, the library doesn't know about them, so it would have to be implemented in the fixtures land which makes it essentially the same as what I described above (basically adding proxies to all affected objects).
gajus commentedon Aug 24, 2022
I would consider moving
expectfunction away from something we import at the top level to something that is initialized per test, i.e.import { - expect, test, } from '@playwright/test'; -test('foo', async ({ page }) => {}); +test('foo', async ({ expect, page }) => {});This would give a lot more control over
expect.mrmckeb commentedon Aug 26, 2022
I came here to ask the same thing, as we tried creating a custom fixture with a method that wrapped
locator, but that makes debugging a little messy - especially with the VSCode extension, as it points to the locator, not the line.Perhaps a simpler approach would be to allow users to register locator middleware, similar to custom selectors.
In our case, we have a custom function to build test IDs, so it might look something like this:
But I also like the idea of named functions, like
getByTestIdorgetByRole... and I think I'd prefer that if both were of equal cost.pavelfeldman commentedon Nov 5, 2022
Closing since we've introduced typed locators like getByRole.
marc-guenther commentedon Mar 10, 2025
Why was this closed? The feature request was not about adding
getByRole(), but about having a way to extend the Locator API.I stumbled upon this, because we are just evaluating migration from Cypress, and in Cypress you can define your own actions. Seems in Playwright, you can't.
DesselBane commentedon Oct 21, 2025
Vitest allows this and I think it would be beneficial for PW as well => https://vitest.dev/guide/browser/locators.html#custom-locators