Skip to content
SimplyMe
← Back to Playwright course

Chapter 3: Basic Playwright Functions

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.

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

Next: Chapter 4 moves beyond single tests into the Page Object Model, fixtures, network mocking, parallel execution, and CI.