This repository was archived by the owner on Aug 6, 2025. It is now read-only.

Commit f837a8e

committed

docs(readme): add chaining documentation

1 parent bacdc9d commit f837a8eCopy full SHA for f837a8e

File tree

1 file changed

+36

-0

lines changed

README.md

1 file changed

+36

-0

lines changed

`‎README.md`

Lines changed: 36 additions & 0 deletions

Original file line number	Diff line number	Diff line change
`@@ -111,6 +111,42 @@ test('my modal', async ({screen, within}) => {`
`111`	`111`	`})`
`112`	`112`	```
`113`	`113`
	`114`	`+#### Chaining`
	`115`	`+`
	`116`	`+> 🔖 Added in [4.5.0](https://github.com/testing-library/playwright-testing-library/releases/tag/v4.5.0)`
	`117`	`+`
	`118`	+As an alternative to the `within(locator: Locator)` function you're familiar with from Testing Library, Playwright Testing Library also supports chaining queries together.
	`119`	`+`
	`120`	+All synchronous queries (`get` + `query`) return `Locator` instances are augmented with a `.within()` method (`TestingLibraryLocator`). All asynchronous queries (`find`) return a special `LocatorPromise` that also supports `.within()`. This makes it possible to chain queries, including chaining `get`, `query` and `find` interchangeably.
	`121`	`+`
	`122`	+> ⚠️ Note that including any `find*` query in the chain will make the entire chain asynchronous
	`123`	`+`
	`124`	`+##### Synchronous`
	`125`	`+`
	`126`	+```ts
	`127`	`+test('chaining synchronous queries', async ({screen}) => {`
	`128`	`+ const locator = screen.getByRole('figure').within().findByRole('img')`
	`129`	`+`
	`130`	`+ expect(await locator.getAttribute('alt')).toEqual('Some image')`
	`131`	`+})`
	`132`	+```
	`133`	`+`
	`134`	`+##### Synchronous + Asynchronous`
	`135`	`+`
	`136`	+```ts
	`137`	`+test('chaining synchronous queries + asynchronous queries', ({screen}) => {`
	`138`	+ // ↓↓↓↓↓ including any `find*` queries makes the whole chain asynchronous
	`139`	`+ const locator = await screen`
	`140`	`+ .getByTestId('modal-container') // Get "modal container" or throw (sync)`
	`141`	`+ .within()`
	`142`	+ .findByRole('dialog') // Wait for modal to appear (async, until `asyncUtilTimeout`)
	`143`	`+ .within()`
	`144`	`+ .getByRole('button', {name: 'Close'}) // Get close button within modal (sync)`
	`145`	`+`
	`146`	`+ expect(await locator.textContent()).toEqual('Close')`
	`147`	`+})`
	`148`	+```
	`149`	`+`
`114`	`150`	`#### Configuration`
`115`	`151`
`116`	`152`	The `Locator` query API is configured using Playwright's `use` API. See Playwright's documentation for [global](https://playwright.dev/docs/api/class-testconfig#test-config-use), [project](https://playwright.dev/docs/api/class-testproject#test-project-use), and [test](https://playwright.dev/docs/api/class-test#test-use).

0 commit comments

Comments

(0)

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Commit f837a8e

File tree

1 file changed

1 file changed

`‎README.md`

0 commit comments