|
26 | 26 |
|
27 | 27 | All of your favorite user-centric querying functions from **@testing-library/react** and **@testing-library/dom** available from within Playwright! |
28 | 28 |
|
29 | | -- Playwright Test [fixture](https://playwright.dev/docs/test-fixtures) for **@playwright/test** via **@playwright-testing-library/test** |
| 29 | +- Test [fixture](https://playwright.dev/docs/test-fixtures) for **@playwright/test** via **@playwright-testing-library/test** |
30 | 30 | - ✨ **New** — `Locator` queries fixture (`locatorFixtures`) [↓](#playwright-test-locator-fixture) |
31 | 31 | - `ElementHandle` queries fixture (`fixtures`) [↓](#legacy-playwright-test-fixture) |
32 | 32 | - Standalone queries for **playwright** via **playwright-testing-library** |
@@ -88,6 +88,27 @@ test('my form', async ({screen, within}) => { |
88 | 88 | }) |
89 | 89 | ``` |
90 | 90 |
|
| 91 | +#### Async Methods |
| 92 | + |
| 93 | +The `findBy` queries work the same way as they do in [Testing Library core](https://testing-library.com/docs/dom-testing-library/api-async) in that they return `Promise<Locator>` and are intended to be used to defer test execution until an element appears on the page. |
| 94 | + |
| 95 | +```ts |
| 96 | +test('my modal', async ({screen, within}) => { |
| 97 | + // Here we wait for a modal to appear asynchronously before continuing |
| 98 | + // Note: the timeout for `findBy` queries is configured with `asyncUtilTimeout` |
| 99 | + const modalLocator = await screen.findByRole('dialog') |
| 100 | + |
| 101 | + // Once the modal is visible, we can interact with its contents and assert |
| 102 | + await expect(modalLocator).toHaveText(/My Modal/) |
| 103 | + await within(modalLocator).getByRole('button', {name: 'Okay'}).click() |
| 104 | + |
| 105 | + // We can also use `queryBy` methods to take advantage of Playwright's `Locator` auto-waiting |
| 106 | + // See: https://playwright.dev/docs/actionability |
| 107 | + // Note: this will use Playwright's timeout, not `asyncUtilTimeout` |
| 108 | + await expect(screen.queryByRole('dialog')).toBeHidden() |
| 109 | +}) |
| 110 | +``` |
| 111 | + |
91 | 112 | #### Configuration |
92 | 113 |
|
93 | 114 | 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). |
@@ -277,7 +298,7 @@ describe('my page', () => { |
277 | 298 |
|
278 | 299 | ### Testing Library |
279 | 300 |
|
280 | | -All queries from **[@testing-library/dom](https://github.com/testing-library/dom-testing-library#usage)** are supported. |
| 301 | +All queries from **[@testing-library/dom](https://github.com/testing-library/dom-testing-library#usage)** are supported. |
281 | 302 |
|
282 | 303 | > 📝 The **`find*`** queries for the `Locator` queries return `Promise<Locator>` which resolves when the element is found before the timeout specified via `asyncUtilTimeout` |
283 | 304 | |
|
0 commit comments