expect-playwright

What is expect-playwright?

The expect-playwright npm package is an assertion library for Playwright, which extends the capabilities of Jest's expect function to work seamlessly with Playwright. It allows for more expressive and readable assertions when testing web applications.

What are expect-playwright's main functionalities?

Element Visibility

This feature allows you to assert that a specific element is present in the DOM. In this example, it checks if a button with the ID 'submit' is present on the page.

await expect(page).toHaveSelector('button#submit');

Element Text

This feature allows you to assert that a specific element contains the expected text. In this example, it checks if an <h1> element contains the text 'Welcome'.

await expect(page).toHaveText('h1', 'Welcome');

Element Count

This feature allows you to assert that a specific number of elements are present in the DOM. In this example, it checks if there are exactly 5 <li> elements on the page.

await expect(page).toHaveSelectorCount('li', 5);

Element Attribute

This feature allows you to assert that a specific element has a particular attribute with the expected value. In this example, it checks if an input element with the ID 'username' has a placeholder attribute with the value 'Enter your username'.

await expect(page).toHaveAttribute('input#username', 'placeholder', 'Enter your username');

Element State

This feature allows you to assert that a specific element is in a particular state, such as enabled or disabled. In this example, it checks if a button with the ID 'submit' is enabled.

await expect(page).toBeEnabled('button#submit');

Other packages similar to expect-playwright

jest-playwright

jest-playwright is a Jest extension that allows you to use Playwright with Jest. It provides a similar set of functionalities for writing end-to-end tests, but it focuses more on integrating Playwright with Jest's testing framework rather than extending Jest's expect function.

playwright-testing-library

playwright-testing-library is a library that brings the user-centric queries from Testing Library to Playwright. It allows you to write tests that are more focused on how users interact with your application, making your tests more readable and maintainable. It complements expect-playwright by providing a different approach to querying elements.

README

expect-playwright

This library provides utility matchers for Jest in combination with Playwright. All of them are exposed on the expect object. You can use them either directly or invert them via the .not property like shown in a example below.

npm install -D expect-playwright

Usage

With Playwright test runner

To activate with the Playwright test runner, use expect.extend() in the config to add the expect-playwright matchers.

// playwright.config.ts
import { expect } from "@playwright/test"
import { matchers } from "expect-playwright"

expect.extend(matchers)

// ...

With Jest

To activate it in your Jest environment you have to include it in your configuration.

{
  "setupFilesAfterEnv": ["expect-playwright"]
}

Why do I need it

The Playwright API is great, but it is low level and not designed for integration testing. So this package tries to provide a bunch of utility functions to perform the common checks easier.

Example which should wait and compare the text content of a paragraph on the page.

// before
await page.waitForSelector("#foo")
const textContent = await page.$eval("#foo", (el) => el.textContent)
expect(textContent).stringContaining("my text")

// after by using expect-playwright
await expect(page).toMatchText("#foo", "my text")

But that's not all! Our matchers also work inside of iframes and accept an ElementHandle which targets an iframe element or a Frame obtained by calling element.contentFrame(). Not only that, but if you pass a promise, we will automatically resolve it for you!

// before
const element = await page.$("iframe")
const frame = await element.contentFrame()
await expect(frame).toBeChecked("#foo")

// after
await expect(page.$("iframe")).toBeChecked("#foo")

API documentation

Table of Contents

• toBeChecked
• toBeDisabled
• toBeEnabled
• toHaveFocus
• toHaveSelector
• toHaveSelectorCount
• toMatchText
• toMatchTitle
• toMatchURL
• toMatchValue

toBeChecked

This function checks if a given element is checked.

You can do this via a selector on the whole page:

await expect(page).toBeChecked("#my-element")

Or by passing a Playwright ElementHandle:

const element = await page.$("#my-element")
await expect(element).toBeChecked()

toBeDisabled

This function checks if a given element is disabled.

You can do this via a selector on the whole page:

await expect(page).toBeDisabled("#my-element")

Or by passing a Playwright ElementHandle:

const element = await page.$("#my-element")
await expect(element).toBeDisabled()

toBeEnabled

This function checks if a given element is enabled.

You can do this via a selector on the whole page:

await expect(page).toBeEnabled("#my-element")

Or by passing a Playwright ElementHandle:

const element = await page.$("#my-element")
await expect(element).toBeEnabled()

toHaveFocus

This function checks if the given selector has focus.

await expect(page).toHaveFocus("#foobar")
// or via not, useful to only wait 1 second instead of for the default timeout by Playwright which is 30 seconds.
await expect(page).not.toHaveFocus("#foobar", {
  timeout: 1 * 1000,
})

toHaveSelector

This function waits as a maximum as the timeout exceeds for a given selector once it appears on the page.

await expect(page).toHaveSelector("#foobar")

When used with not, toHaveSelector will wait until the element is not visible or not attached. See the Playwright waitForSelector docs for more details.

await expect(page).not.toHaveSelector("#foobar")

toHaveSelectorCount

This function checks if the count of a given selector is the same as the provided value.

await expect(page).toHaveSelectorCount(".my-element", 3)

toMatchText

This function checks if the textContent of a given element matches the provided string or regex pattern.

You can do this via a selector on the whole page:

await expect(page).toMatchText("#my-element", "Playwright")
await expect(page).toMatchText("#my-element", /Play.+/)

Or without a selector which will use the body element:

await expect(page).toMatchText("Playwright")
await expect(page).toMatchText(/Play.+/)

Or by passing a Playwright ElementHandle:

const element = await page.$("#my-element")
await expect(element).toMatchText("Playwright")
await expect(element).toMatchText(/Play.+/)

toMatchTitle

This function checks if the page or frame title matches the provided string or regex pattern.

await expect(page).toMatchTitle("My app - page 1")
await expect(page).toMatchTitle(/My app - page \d/)

toMatchURL

This function checks if the current page's URL matches the provided string or regex pattern.

await expect(page).toMatchURL("https://github.com")
await expect(page).toMatchURL(/github\.com/)

toMatchValue

This function checks if the value of a given element is the same as the provided string or regex pattern.

You can do this via a selector or the element directly:

await expect(page).toMatchValue("#my-element", "Playwright")
await expect(page).toMatchValue("#my-element", /Play.+/)

Or by passing a Playwright ElementHandle:

const element = await page.$("#my-element")
await expect(element).toMatchValue("Playwright")
await expect(element).toMatchValue(/Play.+/)

Examples

import playwright from "playwright-chromium"

describe("GitHub Playwright project", () => {
  it("should should have Playwright in the README heading", async () => {
    const browser = await playwright.chromium.launch()
    const page = await browser.newPage()
    await page.goto("https://github.com/microsoft/playwright")
    await expect(page).toMatchText("#readme h1", "Playwright")
    // or also all of them via the not property
    await expect(page).not.toMatchText("this-is-no-anywhere", {
      timeout: 1 * 1000,
    })
    await browser.close()
  })
})

TypeScript

There are typings available. For that just import

import "expect-playwright"

at the top of your test file or include it globally in your tsconfig.json.

Inspired by

• expect-puppeteer