Stop writing waitFors — use web-first assertions

Thanks to auto-waiting, your recorded test cases already cover a lot of functionality and critical user flows. To test the details and check that the data is correct, you need to add assertions.

Generic vs async assertions (web-first assertions)

Playwright Test provides an assertion library out of the box.

import { test, expect } from "@playwright/test";

expect provides generic and (!) async assertions.

Generic matchers are synchronous and work well for simple comparisons such as comparing two numbers.

// a synchronous generic assertion
expect(number).toBe(2);

To test web functionality, though, async assertions are the handier alternative.

Playwright's asynchronous web-first assertions are tailored to the web. They're based on the same auto-waiting principles you already know and wait / retry until a condition is met or the timeout is reached.

// an asynchronous web-first assertion
// this assertion waits / retries until the located element becomes visible
await expect(page.getByText("welcome")).toBeVisible();

If you're testing websites, web-first assertions are more convenient to write and build on PWT's auto-waiting.

expect(await page.getByText("welcome").isVisible()).toBe(true);

await expect(page.getByText("welcome")).toBeVisible();

Common web-first matchers

expect ships with a long list of matchers. The most common ones fall into three groups.

A handful of these matchers (toHaveText, toContainText, toHaveCount) work against locators that match multiple elements. This lets you check multiple elements with a single assertion.

const container = page.getByTestId("multi-element-assertions");
const productsContainer = container.getByRole("region", { name: "Products" });
const products = productsContainer.getByRole("listitem");

await expect(products).toHaveCount(3);
await expect(products).toHaveText([/Product 1/, /Product 2/, /Product 3/]);

There are a few more things to know about assertions.

Configurable timeouts

Web-first assertions accept a timeout option if things take longer.

await expect(page.getByText("welcome")).toBeVisible({ timeout: 10_000 });

Soft assertions

Soft assertions (expect.soft) are a handy way to fail a test case but still run the following actions.

test("has title", async ({ page }) => {
  await page.goto("https://playwright.dev/");

  // If this assertion fails the test case will be marked as failed
  await expect.soft(page.getByTestId("status")).toHaveText("Success");

  // But all the following actions will still be executed and tested
  // ...
});

Soft assertions are particularly helpful in longer tests. A failed soft assertion marks the test as failed, but the test keeps running.

Assertions can be negated

Assertions also provide a quick way to flip their meaning.

await expect(locator).toBeVisible();
await expect(locator).not.toBeVisible();

Custom assertion messages

To make your assertions more readable in your test reports, you can also define a custom message.

await expect
  .soft(page, "should have an awesome title")
  .toHaveTitle("wrong title");

❗ Auto-waiting is the most important core principle in Playwright Test

With the built-in auto-waiting mechanisms, you rarely have to implement manual waitFor statements. If your tests consist of actions and toBe assertions, you're fine!

// click() waits for the element to be actionable
await locator.click();

// wait for the assertion to become truthy or time out
await expect(anotherLocator).toBeVisible();

Depending on the site you want to test, you might want to tweak the timeout configuration. These are Playwright's default timeouts: