Skip to content
SimplyMe
← Back to Playwright course

Chapter 2: Introduction to Test Spec

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

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:

HookRuns
test.beforeAllOnce before all tests in the file/group
test.beforeEachBefore every test
test.afterEachAfter every test
test.afterAllOnce 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

Next: Chapter 3 covers the everyday locator and interaction APIs you will use in almost every test.