From bc5cf93936f4ace3b5041566de3d72631207aa01 Mon Sep 17 00:00:00 2001 From: Jamie Rolfs Date: Tue, 20 Sep 2022 00:17:54 -0700 Subject: [PATCH 1/4] docs(readme): clarify the `findBy*` query methods a bit Closes #510 Closes #513 --- README.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e76a97f..bb1e568 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ All of your favorite user-centric querying functions from **@testing-library/react** and **@testing-library/dom** available from within Playwright! -- Playwright Test [fixture](https://playwright.dev/docs/test-fixtures) for **@playwright/test** via **@playwright-testing-library/test** +- Test [fixture](https://playwright.dev/docs/test-fixtures) for **@playwright/test** via **@playwright-testing-library/test** - ✨ **New** — `Locator` queries fixture (`locatorFixtures`) [↓](#playwright-test-locator-fixture) - `ElementHandle` queries fixture (`fixtures`) [↓](#legacy-playwright-test-fixture) - Standalone queries for **playwright** via **playwright-testing-library** @@ -88,6 +88,27 @@ test('my form', async ({screen, within}) => { }) ``` +#### Async Methods + +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` and are intended to be used to defer test execution until an element appears on the page. + +```ts +test('my modal', async ({screen, within}) => { + // Here we wait for a modal to appear asynchronously before continuing + // Note: the timeout for `findBy` queries is configured with `asyncUtilTimeout` + const modalLocator = await screen.findByRole('dialog') + + // Once the modal is visible, we can interact with its contents and assert + await expect(modalLocator).toHaveText(/My Modal/) + await within(modalLocator).getByRole('button', {name: 'Okay'}).click() + + // We can also use `queryBy` methods to take advantage of Playwright's `Locator` auto-waiting + // See: https://playwright.dev/docs/actionability + // Note: this will use Playwright's timeout, not `asyncUtilTimeout` + await expect(screen.queryByRole('dialog')).toBeHidden() +}) +``` + #### Configuration 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', () => { ### Testing Library -All queries from **[@testing-library/dom](https://github.com/testing-library/dom-testing-library#usage)** are supported. +All queries from **[@testing-library/dom](https://github.com/testing-library/dom-testing-library#usage)** are supported. > 📝 The **`find*`** queries for the `Locator` queries return `Promise` which resolves when the element is found before the timeout specified via `asyncUtilTimeout` From 311490b01d6757ea30bc6a0b7f68b8a557752753 Mon Sep 17 00:00:00 2001 From: Jamie Rolfs Date: Tue, 20 Sep 2022 00:23:26 -0700 Subject: [PATCH 2/4] test(fixture): add coverage for auto-waiting with `queryBy` --- test/fixture/locators.test.ts | 9 +++++++++ test/fixtures/late-page.html | 19 +++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/test/fixture/locators.test.ts b/test/fixture/locators.test.ts index 6666003..1076774 100644 --- a/test/fixture/locators.test.ts +++ b/test/fixture/locators.test.ts @@ -214,6 +214,15 @@ test.describe('lib/fixture.ts (locators)', () => { expect(await locator.textContent()).toEqual('Loaded!') }) + test("queryBy* methods can be used with Playwright's laziness", async ({screen, within}) => { + const modalLocator = await screen.findByRole('dialog', undefined, {timeout: 3000}) + + await expect(modalLocator).toHaveText(/My Modal/) + await within(modalLocator).getByRole('button', {name: 'Okay'}).click() + + await expect(screen.queryByRole('dialog')).toBeHidden() + }) + test('should handle the findAllBy* methods', async ({queries}) => { const locator = await queries.findAllByText(/Hello/, undefined, {timeout: 3000}) diff --git a/test/fixtures/late-page.html b/test/fixtures/late-page.html index ea0eae2..9ec77c3 100644 --- a/test/fixtures/late-page.html +++ b/test/fixtures/late-page.html @@ -25,6 +25,25 @@ attached.textContent = 'Attached' attached.style.visibility = 'hidden' document.body.appendChild(attached) + + const modal = document.createElement('dialog') + const modalButton = document.createElement('button') + const modalHeader = document.createElement('h1') + + modal.style.display = 'block' + + modalButton.innerText = 'Okay' + modalButton.onclick = () => { + modal.innerText = 'Doing a thing...' + setTimeout(() => document.querySelector('dialog').remove(), 1000) + } + + modalHeader.innerText = 'My Modal' + + modal.appendChild(modalButton) + modal.appendChild(modalHeader) + + document.body.appendChild(modal) }, 2000) From 5616c5d89108b961cb74ebfb9c27af4850f0e05b Mon Sep 17 00:00:00 2001 From: Jamie Rolfs Date: Tue, 20 Sep 2022 00:30:45 -0700 Subject: [PATCH 3/4] docs(readme): fix link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bb1e568..6fa9970 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ All of your favorite user-centric querying functions from **@testing-library/react** and **@testing-library/dom** available from within Playwright! - Test [fixture](https://playwright.dev/docs/test-fixtures) for **@playwright/test** via **@playwright-testing-library/test** - - ✨ **New** — `Locator` queries fixture (`locatorFixtures`) [↓](#playwright-test-locator-fixture) + - ✨ **New** — `Locator` queries fixture (`locatorFixtures`) [↓](#playwright-test-fixture) - `ElementHandle` queries fixture (`fixtures`) [↓](#legacy-playwright-test-fixture) - Standalone queries for **playwright** via **playwright-testing-library** - `ElementHandle` queries (`getDocument` + `queries`) [↓](#standalone-playwright-queries) From d32b24e66acb1286f3c8593ec076c4ed44e31fb2 Mon Sep 17 00:00:00 2001 From: Jamie Rolfs Date: Tue, 20 Sep 2022 00:31:02 -0700 Subject: [PATCH 4/4] docs(readme): fix usage summary/recommendation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6fa9970..31f5a70 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ npm install --save-dev playwright-testing-library ## 📝 Usage -There are currently a few different ways to use Playwright Testing Library, depending, however using the `Locator` queries fixture with Playwright Test (**@playwright/test**) is the recommended approach. +There are currently a few different ways to use Playwright Testing Library, depending on how you use Playwright. However, the recommended approach is using the `Locator` [queries fixture](#playwright-test-fixture) with Playwright Test (**@playwright/test**). > ⚠️ The `ElementHandle` query APIs were created before Playwright introduced its `Locator` API and will be replaced in the next major version of Playwright Testing Library. If you can't use **@playwright/test** at the moment, you'll need to use the `ElementHandle` query API, but a migration path will be provided when we switch to the new `Locator` APIs.