pptr-testing-library

puppeteer + @testing-library/dom = 💖

All your favorite user-centric querying functions from @testing-library/react & @testing-library/library available from Puppeteer!

Install

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

Use

constpuppeteer=require('puppeteer')const{getDocument, queries, waitFor}=require('pptr-testing-library')const{getByTestId, getByLabelText}=queriesconstbrowser=awaitpuppeteer.launch()constpage=awaitbrowser.newPage()// Grab ElementHandle for documentconst$document=awaitgetDocument(page)// Your favorite query methods are availableconst$form=awaitgetByTestId($document,'my-form')// returned elements are ElementHandles too!const$email=awaitgetByLabelText($form,'Email')// interact with puppeteer like usualawait$email.type('pptr@example.com')// waiting works too!awaitwaitFor(()=>getByText($document,'Loading...'))

A little too un-puppeteer for you? We've got prototype-mucking covered too :)

constpuppeteer=require('puppeteer')require('pptr-testing-library/extend')constbrowser=awaitpuppeteer.launch()constpage=awaitbrowser.newPage()// getDocument is added to prototype of Pageconst$document=awaitpage.getDocument()// query methods are added directly to prototype of ElementHandleconst$form=await$document.getByTestId('my-form')// destructing works if you explicitly call getQueriesForElementconst{getByText}=$form.getQueriesForElement()// ...

Version Compat

Puppeteer Version	pptr-testing-library Version
17+	>0.8.0
<17	0.7.x

API

Unique methods, not part of @testing-library/dom

• getDocument(page: puppeteer.Page): ElementHandle - get an ElementHandle for the document
• wait(conditionFn: () => {}): Promise<{}> - wait for the condition to not throw (wrapper around waitForExpect)

---

@testing-library/dom API. All get*/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
  • queryByRole
  • queryAllByRole
  • getByRole
  • getAllByRole
  • findByRole
  • findAllByRole
  • 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 puppeteer's built-ins instead.
• expect assertion extensions are not available.

Special Thanks

@testing-library/dom of course!

Related Puppeteer Test Utilities

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

LICENSE

MIT