This chapter covers the functions you will reach for in nearly every test. The guiding idea is that locators are lazy and assertions auto-wait, so you describe what you want and let Playwright handle timing.
Navigation: page.goto()
page.goto() navigates and waits for the load event by default.
await page.goto("https://example.com");
await page.goto("/dashboard"); // relative to baseURL from the config
Set a baseURL in playwright.config.ts so specs can use relative paths:
import { defineConfig } from "@playwright/test";
export default defineConfig({
use: {
baseURL: "http://localhost:3000",
trace: "on-first-retry",
},
});
Finding elements: page.locator()
locator() describes how to find an element; it does not query until you act on
it. This is what enables retries.
page.locator("css=button.submit");
page.getByRole("button", { name: "Submit" });
page.getByLabel("Email");
page.getByTestId("cart-total");
page.getByText("Welcome back");
Prefer user-facing locators (getByRole, getByLabel, getByText) over CSS. They
match how assistive technology sees the page, so they both improve accessibility
and make tests less brittle.
You can chain and filter:
const firstRow = page.getByRole("row").filter({ hasText: "Alice" });
await firstRow.getByRole("button", { name: "Edit" }).click();
Interacting: click() and fill()
await page.getByRole("button", { name: "Add to cart" }).click();
await page.getByLabel("Email").fill("alice@example.com");
await page.getByLabel("Password").fill("secret");
await page.getByRole("button", { name: "Sign in" }).click();
Other common interactions:
await page.getByLabel("Country").selectOption("ID");
await page.getByRole("checkbox").check();
await page.getByRole("link", { name: "Docs" }).hover();
await page.keyboard.press("Enter");
Every one of these auto-waits for the element to be actionable before performing the action.
Taking a screenshot
await page.screenshot({ path: "artifacts/home.png", fullPage: true });
// screenshot a single element
await page.getByTestId("invoice").screenshot({ path: "artifacts/invoice.png" });
Screenshots are useful as CI artifacts. Configure Playwright to capture them automatically on failure:
export default defineConfig({
use: { screenshot: "only-on-failure", video: "retain-on-failure" },
});
Assertions that auto-wait
The web-first matchers retry until they pass. The most-used ones:
// visibility and state
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
await expect(page.getByRole("button", { name: "Save" })).toBeEnabled();
await expect(page.getByText("Loading...")).toBeHidden();
// exact content
await expect(page.getByTestId("total")).toHaveText("$42.00");
await expect(page.getByRole("alert")).toContainText("invalid");
// counts and values
await expect(page.locator("li.todo")).toHaveCount(3);
await expect(page.getByLabel("Email")).toHaveValue("alice@example.com");
// page-level
await expect(page).toHaveURL(/\/dashboard$/);
await expect(page).toHaveTitle(/Dashboard/);
Putting it together
import { test, expect } from "@playwright/test";
test("a user can add an item to the cart", async ({ page }) => {
await page.goto("/shop");
await page.getByRole("button", { name: "Add to cart" }).first().click();
await expect(page.getByTestId("cart-count")).toHaveText("1");
await expect(page.getByRole("alert")).toContainText("added to cart");
await page.screenshot({ path: "artifacts/cart.png" });
});
Common pitfalls
- Using
page.$()/page.$$()— these query once and do not auto-wait. Avoid them; uselocator()instead. - Manual waits —
page.waitForTimeout(1000)makes suites slow and flaky. Use a web-first assertion for the condition you actually care about. - Brittle selectors — long CSS chains (
.a > .b > div:nth-child(2)) break on every layout change. Reach for roles, labels, and test ids.
Next: Chapter 4 moves beyond single tests into the Page Object Model, fixtures, network mocking, parallel execution, and CI.