playwright-testing-library
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.1 • Public • Published


    playwright-testing-library

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

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


    Features

    ⚠️ 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)

    🌱 Getting Started

    1. Install

    # 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

    2a. Use Playwright Test fixture

    import {test as baseTest} from '@playwright/test'
    import {fixtures, TestingLibraryFixtures} from '@playwright-testing-library/test/fixture'
    
    // As only fixture
    const test = baseTest.extend<TestingLibraryFixtures>(fixtures)
    
    // Alternatively, with other fixtures
    interface Fixtures extends TestingLibraryFixtures {
      // ... additional fixture types
    }
    
    const test = baseTest.extend<Fixtures>({
      ...fixtures,
      // ... additional fixtures
    })
    
    const {expect} = test
    
    // Query methods are available in `test` blocks
    test('my form', ({queries: {getByTestId}}) => {
      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')
    
      // ...
    })

    2b. Use standalone queries

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

    🔌 API

    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,

    Known Limitations

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

    Special Thanks

    Related Playwright Test Utilities

    LICENSE

    MIT

    Install

    npm i playwright-testing-library

    DownloadsWeekly Downloads

    4,157

    Version

    4.0.1

    License

    MIT

    Unpacked Size

    601 kB

    Total Files

    40

    Last publish

    Collaborators

    • jrolfs