Test like a user

So far, you should have at least two test cases:

• add a product to cart from home
• add a product to cart from the catalog

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.

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 highly encourages the usage of "user-first" locators that are as close to the end-user experience as possible. The recommended locators are:

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

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

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. 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)

// 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");

These auto-waiting concepts allow you to drop many manual waitFor statements because you don't have to check if an element exists or is visible. Actions will 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();

// 👎
// 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();