Stop writing waitFors — use web-first assertions

Thanks to auto-waiting mechanisms, your recorded test cases test many web functionality and critical user flows already. To nail down implementation details and test for data correctness, 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 are valuable for simple comparisons such as comparing two numbers.

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

To test web functionality, though, async assertions come as a handy alternative.

Playwright's asynchronous web-first assertions are tailored to the web. They're based on the same auto-waiting principles you already know about and wait / retry until a condition is met or the time out 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 leverage PWT's core functionality.

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

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

  // 👎
  // test a condition at a single moment in time
  // this approach introduces flakiness
  expect(await page.getByText("welcome").isVisible()).toBe(true);

  // 👍
  // wait for a condition to become truthy over time
  await expect(page.getByText("welcome")).toBeVisible();
});

Common web-first matchers

expect ships with a long list of matchers. The most common ones group into three buckets.

A handful of these matchers — toHaveText, toContainText, toHaveCount — work against locators that match multiple elements, no .first() / .nth() / .last() loop required.

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 some core things to know about assertions.

Configurable timeouts

Web-first assertions have a timeout config 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 your test case but still try to 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 assertion are particularly helpful when running longer tests. A soft assertion will lead to test failure but the test still continues running.

Assertions can be negated

Assertions also provide a quick way to flip around 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.

// click() waits for the element to be actionable
// click() waits for a triggered navigation to complete
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 for the mentioned auto-waiting concepts.