A spec file is where your tests live. Playwright discovers files matching
*.spec.ts (or *.test.ts) by default. This chapter breaks down what goes inside
one.
The building blocks
import { test, expect } from "@playwright/test";
test("a descriptive test name", async ({ page }) => {
await page.goto("https://example.com");
await expect(page).toHaveTitle(/Example/);
});
test(name, fn)registers a single test. The callback receives fixtures — here, a freshpagecreated for this test only.async/awaitis required: every Playwright action returns a promise.expect()is the assertion entry point.
Grouping with describe()
describe() groups related tests. Groups can nest, and hooks can be scoped to a
group.
import { test, expect } from "@playwright/test";
test.describe("Login", () => {
test.beforeEach(async ({ page }) => {
await page.goto("/login");
});
test("rejects empty credentials", async ({ page }) => {
await page.getByRole("button", { name: "Sign in" }).click();
await expect(page.getByRole("alert")).toHaveText(
"Username is required"
);
});
test("rejects a wrong password", async ({ page }) => {
await page.getByLabel("Username").fill("alice");
await page.getByLabel("Password").fill("wrong");
await page.getByRole("button", { name: "Sign in" }).click();
await expect(page).toHaveURL(/\/login\?error=invalid/);
});
});
Hooks
Hooks run code before or after tests:
| Hook | Runs |
|---|---|
test.beforeAll | Once before all tests in the file/group |
test.beforeEach | Before every test |
test.afterEach | After every test |
test.afterAll | Once after all tests in the file/group |
Hooks receive the same fixtures as tests. beforeEach is the right place for
navigation to a starting state; keep it small so tests stay independent.
Assertions with expect()
The most common web-first assertions:
await expect(page).toHaveURL(/dashboard/);
await expect(page).toHaveTitle("Dashboard");
await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
await expect(page.locator(".item")).toHaveCount(3);
await expect(page.getByTestId("total")).toHaveText("$42.00");
Web-first assertions retry until they pass or time out, so you rarely need to wait manually.
Running tests
# everything
pnpm exec playwright test
# one file
pnpm exec playwright test tests/login.spec.ts
# tests whose title matches a string
pnpm exec playwright test -g "wrong password"
# headed with a single worker, for debugging
pnpm exec playwright test --headed --workers=1
Reading the report
After a run, Playwright writes results plus an HTML report. Open it with:
pnpm exec playwright show-report
The report shows each test, its duration, the error message, and — when a test fails — a trace. A trace is a recorded timeline of every action, network request, and DOM snapshot. Open it in the trace viewer to step backwards through the failure:
pnpm exec playwright show-trace test-results/.../trace.zip
In UI mode (--ui) you get the same timeline interactively while authoring tests.
Tips for a healthy spec
- One behaviour per test; the name should read like a sentence.
- Prefer role- and label-based locators over CSS classes — they survive refactors.
- Never assert on arbitrary timeouts; rely on web-first assertions.
- Keep
beforeEachfocused on reaching the starting state, not on asserting it.
Next: Chapter 3 covers the everyday locator and interaction APIs you will use in almost every test.