Start testing things (for real)

So far, you should have three test cases:

• add a product to cart
• search for a product and add it to cart
• log in

We've only recorded tests without knowing how Playwright works under the hood. Let's understand how Playwright locators and interactions work!

Playwright interactions are based on locators available on the page fixture.

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

// The provided `page` object is called a test fixture
// and there are many more available...
// You can even add your own.
//                          👇
test("has title", async ({ page }) => {
  await page.goto("https://playwright.dev/");

  // Expect the page title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

Locators

The Playwright team highly encourages the usage of "user-first" locators to be as close to the end-user experience as possible. The recommended locators are:

• page.getByRole() (user-first)
• page.getByText() (user-first)
• page.getByLabel() (user-first)
• page.getByPlaceholder() (user-first)
• page.getByAltText() (user-first)
• page.getByTitle() (user-first)
• page.getByTestId() ("qa-first")

If these user-first locators don't fit your needs, CSS selector based locators work (page.locator('.cta')), too.

When dealing with a real-world codebase, not all DOM elements can be selected user-first. In practice, it's often a mix of different locators. Check other locators in the docs.

Important locator characteristics

Playwright Test's locators include core functionality you must be aware of.

Locators are strict

A locator throws an exception if it matches multiple DOM elements.

await page.getByRole("link").click();
// Error:
// locator.click: Error: strict mode violation: getByRole('link') resolved to 31 elements:
// ...

If there are multiple elements matching one locator you need to be more specific or use helper functions such as first(), nth() or last().

await page.getByRole("link").first().click();

Locators are lazy

Every time a locator is used for an action, an up-to-date DOM element is located on the page.

// the `locator` is only evaluated when it's used
const locator = page.getByRole("button", { name: "Sign in" });

// evaluate DOM elements matching the locator
await locator.hover();
// evaluate DOM elements matching the locator
await locator.click();

Locators can be chained

To narrow down your selection you can always filter and chain locators.

// The `button` locator reuses the `product` locator
const product = page.getByRole("listitem").filter({ hasText: "Product 2" });
const button = product.getByRole("button", { name: "Add to cart" });

// Mix of a class locator and a user-first locator
const detailContainer = page.locator(".detail-content");
const productHeading = detailContainer.getByRole("heading", { level: 2 });

This becomes very handy when sites include some data-testid attributes. Chaining locators will help to select the best elements.

page
  .getByRole("listitem")
  .filter({ hasText: "Product 2" })
  .getByRole("button", { name: "Add to cart" });

Actionability

Playwright provides action methods for all common user interactions.

• locator.fill()
• locator.check()
• locator.selectOption()
• locator.click()
• locator.dblclick()
• locator.hover()
• locator.type()
• locator.press()
• ...

The most important concept when it comes to PWT is that actions auto-wait. Note that you have to await a user action like click. A click isn't only a click.

Actions in Playwright tests are asynchronous operations — why?

For example, await locator.click() waits until the element is actionable:

• the matching element is attached to the DOM
• the matching element is visible
• the matching element is stable (not animating)
• the matching element is able to receive events (not obscured by other elements)
• the matching element is enabled (no disabled attribute)

Additionally, when an action was performed it'll wait until a possible navigation is completed.

// Concept 1:
// Click will wait for the element to be actionable
// Click will also auto-wait for a triggered navigation to complete
await page.getByText("Login").click();

// Concept 2:
// Fill will auto-wait for element to be actionable
await page.getByLabel("User Name").fill("John Doe");

await page.getByRole("button", { name: "Step 1" }).click();
await page.getByRole("button", { name: "Step 2" }).click();
await page.getByRole("button", { name: "Step 3" }).click();

// 👎
// Checking if an element is visible before interacting with it
await expect(page.getByText("Login")).toBeVisible();
await page.getByText("Login").click();

// 👍
// Just interact with it and let Playwright figure out the rest
await page.getByText("Login").click();