playwright-testing-library
playwright-testing-library copied to clipboard
🔍 Find elements in Playwright with queries from Testing Library
![](https://user-images.githubusercontent.com/288160/126050717-dd76eb80-ef06-40e0-97e8-72c20c9f8f20.png)
playwright-testing-library
🔍 Find elements in playwright like your users with queries from @testing-library/dom
✨ Features
All of your favorite user-centric querying functions from @testing-library/react and @testing-library/dom available from Playwright!
- Playwright Test fixture —
@playwright-testing-library/test/fixture
or... - Standalone queries —
playwright-testing-library
/@playwright-testing-library/test
- Asynchronous assertion helper (via wait-for-expect)
🌱 Getting Started
1. Install
# For use with Playwright
npm install --save-dev playwright-testing-library
# For use with Playwright Test
npm install --save-dev @playwright-testing-library/test
or
# For use with Playwright
yarn add --dev playwright-testing-library
# For use with Playwright Test
yarn add --dev @playwright-testing-library/test
2a. Use Playwright Test fixture
import {test as baseTest} from '@playwright/test'
import {fixtures, within, TestingLibraryFixtures} from '@playwright-testing-library/test/fixture'
// As only fixture
const test = baseTest.extend<TestingLibraryFixtures>(fixtures)
// Alternatively, with other fixtures
interface Fixtures extends TestingLibraryFixtures {
// ... additional fixture types
}
const test = baseTest.extend<Fixtures>({
...fixtures,
// ... additional fixtures
})
const {expect} = test
// Query methods are available in `test` blocks
test('my form', async ({queries: {getByTestId}}) => {
const $form = await getByTestId('my-form')
// Scope queries with `within`
const {getByLabelText} = within($form)
const $email = await getByLabelText('Email')
// Interact with Playwright like usual
await $email.type('[email protected]')
// ...
})
2b. Use standalone queries
const {webkit} = require('playwright') // or 'firefox' or 'chromium'
const {getDocument, queries} = require('playwright-testing-library')
const {getByTestId, getByLabelText} = queries
const browser = await webkit.launch()
const page = await browser.newPage()
// Grab ElementHandle for document
const $document = await getDocument(page)
// Your favorite query methods are available
const $form = await getByTestId($document, 'my-form')
// Returned elements are ElementHandles too!
const $email = await getByLabelText($form, 'Email')
// Interact with playwright like usual
await $email.type('[email protected]')
// ...
🔌 API
Unique methods, not part of @testing-library/dom
-
Get an
ElementHandle
for the documentgetDocument(page: playwright.Page): ElementHandle
-
Wait for an assertion (wrapper around wait-for-expect)
waitFor( expectation: () => void | Promise<void>, timeout?: number, interval?: number ): Promise<{}>
The @testing-library/dom — All get*
and query*
methods are supported.
-
getQueriesForElement(handle: ElementHandle): ElementHandle & QueryUtils
- extend the input object with the query API and return it -
getNodeText(handle: ElementHandle): Promise<string>
- get the text content of the element -
queries: QueryUtils
- the query subset of@testing-library/dom
exports-
queryByPlaceholderText
-
queryAllByPlaceholderText
-
getByPlaceholderText
-
getAllByPlaceholderText
-
findByPlaceholderText
-
findAllByPlaceholderText
-
queryByText
-
queryAllByText
-
getByText
-
getAllByText
-
findByText
-
findAllByText
-
queryByLabelText
-
queryAllByLabelText
-
getByLabelText
-
getAllByLabelText
-
findByLabelText
-
findAllByLabelText
-
queryByAltText
-
queryAllByAltText
-
getByAltText
-
getAllByAltText
-
findByAltText
-
findAllByAltText
-
queryByTestId
-
queryAllByTestId
-
getByTestId
-
getAllByTestId
-
findByTestId
-
findAllByTestId
-
queryByTitle
-
queryAllByTitle
-
getByTitle
-
getAllByTitle
-
findByTitle
-
findAllByTitle
-
queryByDisplayValue
, -
queryAllByDisplayValue
, -
getByDisplayValue
, -
getAllByDisplayValue
, -
findByDisplayValue
, -
findAllByDisplayValue
,
-
Known Limitations
- Async utilities
waitForElement
,waitForElementToBeRemoved
andwaitForDomChange
are not exposed. Consider using afind*
query. -
fireEvent
method is not exposed, use Playwright's built-ins instead. -
expect
assertion extensions are not available.
Special Thanks
- pptr-testing-library
- @testing-library/dom of course!
Related Playwright Test Utilities
- jest-playwright
- expect-playwright
- Yours! Name TBD, PR welcome ;)
LICENSE
MIT
Maintenance
This project is actively maintained by engineers at @hoverinc 😀.