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

Build Status Test Coverage Code Style Package Version
MIT License Conventional Commits Maintenance

🎛 Features

🌱 Installation

# For use with Playwright Test (@playwright/test)
npm install --save-dev @playwright-testing-library/test
# For use with Playwright (playwright)
npm install --save-dev playwright-testing-library

📝 Usage

Playwright Test Fixture

Setup

import {test as base} from '@playwright/test'
import {
 locatorFixtures as fixtures,
 LocatorFixtures as TestingLibraryFixtures,
} from '@playwright-testing-library/test/fixture'
const test = base.extend<TestingLibraryFixtures>(fixtures)
const {expect} = test
test('my form', async ({screen, within}) => {
 // Screen provides `Locator` queries scoped to current Playwright `Page`
 const formLocator = screen.getByTestId('my-form')
 // Scope queries to `Locator` with `within`
 // (note that this is a fixture from `test`, not the `within` import)
 const emailInputLocator = within(formLocator).getByLabelText('Email')
 // Interact via `Locator` API 🥳
 await emailInputLocator.fill('email@playwright.dev')
 await emailInputLocator.press('Enter')
 // Screen also provides Playwright's `Page` API
 screen.goto('/account')
 const emailLocator = screen.getByRole('heading', {level: 2})
 // Assert via `Locator` APIs 🎉
 await expect(emailLocator).toHaveText('email@playwright.dev')
})

Async Methods

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(/MyModal/)
 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()
})

Chaining

Synchronous

test('chaining synchronous queries', async ({screen}) => {
 const locator = screen.getByRole('figure').within().findByRole('img')
 expect(await locator.getAttribute('alt')).toEqual('Some image')
})

Synchronous + Asynchronous

test('chaining synchronous queries + asynchronous queries', ({screen}) => {
 // ↓↓↓↓↓ including any `find*` queries makes the whole chain asynchronous
 const locator = await screen
 .getByTestId('modal-container') // Get "modal container" or throw (sync)
 .within()
 .findByRole('dialog') // Wait for modal to appear (async, until `asyncUtilTimeout`)
 .within()
 .getByRole('button', {name: 'Close'}) // Get close button within modal (sync)
 expect(await locator.textContent()).toEqual('Close')
})

Configuration

Global

import type {PlaywrightTestConfig} from '@playwright/test'
const config: PlaywrightTestConfig = {
 use: {
 // These are the defaults
 testIdAttribute: 'data-testid',
 asyncUtilTimeout: 1000,
 asyncUtilExpectedState: 'visible',
 },
}
export default config

Local

import {test as base} from '@playwright/test'
import {
 locatorFixtures as fixtures,
 LocatorFixtures as TestingLibraryFixtures,
} from '@playwright-testing-library/test/fixture'
const test = base.extend<TestingLibraryFixtures>(fixtures)
const {describe, expect, use} = test
// Entire test suite
use({testIdAttribute: 'data-custom-test-id'})
describe(() => {
 // Specific block
 use({
 testIdAttribute: 'some-other-test-id',
 asyncUtilsTimeout: 5000,
 asyncUtilExpectedState: 'attached',
 })
 test('my form', async ({screen}) => {
 // ...
 })
})

Legacy Playwright Test Fixture

Setup

import {test as base} from '@playwright/test'
import {fixtures, within, TestingLibraryFixtures} from '@playwright-testing-library/test/fixture'
const test = base.extend<TestingLibraryFixtures>(fixtures)
const {expect} = test
test('my form', async ({page, queries}) => {
 // Query methods are available in `test` blocks
 const formHandle = await queries.getByTestId('my-form')
 // Scope queries to an `ElementHandle` with `within`
 const emailInputHandle = await within(formHandle).getByLabelText('Email')
 // Interact via `ElementHandle` API
 await emailInputHandle.fill('email@playwright.dev')
 await emailInputHandle.press('Enter')
 page.goto('/account')
 const emailHandle = queries.getByRole('heading', {level: 2})
 // Assert via `ElementHandle` APIs
 expect(await emailHandle.textContent()).toEqual('email@playwright.dev')
})

Configuration

import {test as base} from '@playwright/test'
import {
 configure,
 fixtures,
 within,
 TestingLibraryFixtures,
} from '@playwright-testing-library/test/fixture'
const test = base.extend<TestingLibraryFixtures>(fixtures)
const {beforeEach, describe, expect} = test
// Global (these are the defaults)
configure({asyncUtilTimeout: 1000, testIdAttribute: 'data-testid'})
// Specific block
describe('my page', () => {
 beforeEach(() => configure({asyncUtilTimeout: 5000, testIdAttribute: 'data-custom-test-id'}))
 afterEach(() => configure({}))
 test('my form', async ({page, queries}) => {
 // ...
 })
})

Standalone Playwright Queries

import {beforeAll, expect, jest, test} from '@jest/globals'
import {webkit} from 'playwright' // or 'firefox' or 'chromium'
import {getDocument, queries, within} from 'playwright-testing-library'
let browser: playwright.Browser
let page: playwright.Page
beforeAll(() => {
 const browser = await webkit.launch()
 const page = await browser.newPage()
})
test('my form', () => {
 // Get `ElementHandle` for document from `Page`
 const documentHandle = await getDocument(page)
 // Global query methods take document handle as the first parameter
 const formHandle = await queries.getByTestId(documentHandle, 'my-form')
 // Scope queries to an `ElementHandle` with `within`
 const emailInputHandle = await within(formHandle).getByLabelText('Email')
 // Interact via `ElementHandle` API
 await emailInputHandle.fill('email@playwright.dev')
 await emailInputHandle.press('Enter')
 page.goto('/account')
 const accountHandle = getDocument(page)
 const emailHandle = queries.getByRole(accountHandle, 'heading', {level: 2})
 // Assert via `ElementHandle` APIs
 expect(await emailHandle.textContent()).toEqual('email@playwright.dev')
})

Configuration

import {beforeEach, afterEach, expect, jest, test} from '@jest/globals'
import {configure, getDocument, queries, within} from 'playwright-testing-library'
// Global (these are the defaults)
configure({asyncUtilTimeout: 1000, testIdAttribute: 'data-testid'})
// Specific block
describe('my page', () => {
 beforeEach(() => configure({asyncUtilTimeout: 5000, testIdAttribute: 'data-custom-test-id'}))
 afterEach(() => configure({}))
 test('my form', async ({page, queries}) => {
 // ...
 })
})

🔌 API

Testing Library

Additional

Known Limitations

Locator Queries

Special Thanks

Related Playwright Test Utilities

LICENSE

Maintenance