Skip to main content

Puppeteer Testing Library

pptr-testing-library is a lightweight adapter allowing DOM Testing Library to be used with puppeteer.

npm install --save-dev puppeteer pptr-testing-library


const puppeteer = require('puppeteer')
const {getDocument, queries, waitFor} = require('pptr-testing-library')

const {getByTestId, getByLabelText} = queries

const browser = await puppeteer.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 Puppeteer ElementHandles too!
const $email = await getByLabelText($form, 'Email')
// interact with puppeteer like usual
await $email.type('')
// waiting works too!
await waitFor(() => getByText('Loading...'))

A little too un-puppeteer for you? You can attach all the DOM Testing Library methods directly onto puppeteer's ElementHandle instead!

const puppeteer = require('puppeteer')

const browser = await puppeteer.launch()
const page = await browser.newPage()

// getDocument is added to prototype of Page
const $document = await page.getDocument()
// query methods are added directly to prototype of ElementHandle
const $form = await $document.getByTestId('my-form')
// destructuring works if you explicitly call getQueriesForElement
const {getByLabelText} = $form.getQueriesForElement()
// ...
const $email = await getByLabelText('Email')


Unique methods, not part of DOM Testing Library.

  • getDocument(page: puppeteer.Page): ElementHandle - get an ElementHandle for the document

Forwarded methods

DOM Testing Library is injected into the page that puppeteer is controlling on each query, so all results will be async. It's still recommended that you use puppeteer's built-in methods for interaction rather than fireEvent.

Known Limitations

  • waitForElement method is not exposed. Puppeteer has its own set of wait utilities that somewhat conflict with the style used in DOM Testing Library. See the issue on GitHub.
  • fireEvent method is not exposed, use puppeteer's built-ins instead.
  • expect assertion extensions are not available.