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

Usage​

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('pptr@example.com')
// 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')
require('pptr-testing-library/extend')

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')

API​

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.