playwright-testing-library

🔍 Find elements in playwright like your users with queries from @testing-library/dom

⚠️ Note: this is a fork of pptr-testing-library modified to accomodate for some subtle API differences.

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)

# 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

@playwright/test allows you to extend the selectors that are available when making a locator.

When using the locators it doesn't make sense to differentiate the queryBy and queryAllBy queries or use the get and find queries since we can leave it to playwright to be angry when you try to click a locator that matches multiple elements. This means that all the selectors added are backed by queryAll.

You can use a Regex in these selectors, but since they are strings remember to escape any special characters as normal.

You can use >> as normal to chain selectors in a locator.

import {test as baseTest} from '@playwright/test' import {fixtures} from '@playwright-testing-library/test/fixture' import {registerSelectorEngines} from '@playwright-testing-library/test/selectors' const test = mixinFixtures(baseTest) // registers all of the By... selector engines, you can skip this if you don't want to use Locators await registerSelectorEngines() const {expect} = test // Query methods are available in `test` blocks test('my form', ({page, queries: {getByTestId}}) => { // the selector engines integrate the queries into playwright locators // the advantage here is that they return locators, and not ElementHandles await page.locator('form >> ByLabelText=/username/i').type('Slartibartfast') const $form = await getByTestId('my-form') // Scope queries with `getQueriesForElement` const {getByLabelText} = $form.getQueriesForElement() const $email = await getByLabelText('Email') // Interact with Playwright like usual await $email.type('playwright@example.com') expect($email).toHaveValue('playwright@example.com') // ... })

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('playwright@example.com') // ...

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,

• 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.

• pptr-testing-library
• @testing-library/dom of course!

• jest-playwright
• expect-playwright
• Yours! Name TBD, PR welcome ;)

MIT