Test like a user

So far, you should have at least two test cases in your shop.spec.ts:

• add a product to cart from home
• navigate to login and check that the heading is visible

So far, we've only recorded tests without knowing how Playwright works under the hood. Let's look at how Playwright locators and interactions work!

Playwright interactions are based on locators.

import { test, expect } from "@playwright/test";test("has title", async ({ page }) => {  await page.goto("https://playwright.dev/");  await page.getByRole("link").click();});

But what are locators?

Locators

A locator is a "blueprint" of the elements you want to interact with.

The Playwright team strongly encourages using "user-first" locators that are as close to the end-user experience as possible. The recommended locators are:

In a real-world codebase, you'll quickly discover that 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

Locators have three core characteristics you should know.

Locators are strict

A locator throws an exception if it matches multiple DOM elements when used with an action or assertion.

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

If multiple elements match a 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();

// There's nothing to `await`, a locator is only a definition.
// So don't do this.
//                👇
const locator = await page.getByRole("button", { name: "Sign in" });

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 `getByTestId` with semantic locators for tighter scoping
const productGrid = page.getByTestId("hero-product-grid");
const productLink = productGrid.getByRole("link", {
  name: "The Collection Snowboard:",
});

This is very handy when a site includes some data-testid attributes. Chain locators to narrow things down to exactly the element you want.

const container = page.getByTestId("locator-chaining");
const listContainer = container
  .getByRole("listitem")
  .filter({ hasText: "Product 2" });

await listContainer.getByRole("button", { name: "Add to cart" }).click();

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.

A click() call isn't only a click. Actions are asynchronous operations.

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

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

// Concept 1:
// Click will wait for the element to be actionable
await page.getByText("Login").click();

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

Avoid manual waitFor statements

Auto-waiting lets you drop many manual waitFor statements because you don't have to check if an element exists or is visible. Playwright will do that for you and wait / retry until an element is "ready for action" or throw a timeout error in your test.

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

It's best if you let Playwright do its job. 🫣

await expect(page.getByText("Login")).toBeVisible();
await page.getByText("Login").click();

await page.getByText("Login").click();