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 document

  getDocument(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 and waitForDomChange are not exposed. Consider using a find* 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 😀.