Reference · Cheat Sheet

Playwright Test — the runner

Saving a live check as a re-runnable file. This is @playwright/test, a different tool from the Playwright MCP.

MCP vs. the test runner — don't confuse them

Playwright MCP

Claude drives a browser live, deciding each step. Great for exploring & one-off checks. Ephemeral — ends with the session. (Lessons 01–03.)

Playwright Test (@playwright/test)

A saved file of steps + assertions, run by a CLI. Repeatable, version-controlled, CI-friendly. Runs without Claude. (This sheet.)

Workflow: use the MCP to explore and get a check passing, then have Claude write the equivalent test file. Best of both — agentic discovery, durable persistence.

Setup (once per project)

Command	Does
`npm init playwright@latest`	Scaffolds the project: installs `@playwright/test`, browsers, a `playwright.config`, and a sample `tests/example.spec.ts`.

Anatomy of a test file

import { test, expect } from '@playwright/test';

test('valid signup succeeds', async ({ page }) => {
  // 1. go to the app
  await page.goto('http://localhost:8000');

  // 2. act — using stable locators (see selector cheat sheet)
  await page.getByLabel('Email address').fill('a@b.com');
  await page.getByLabel('Age').fill('30');
  await page.getByRole('button', { name: 'Subscribe' }).click();

  // 3. assert — the verdict. Auto-waits until true or times out.
  await expect(page.getByText('subscribed')).toBeVisible();
});

Piece	Role
`test('name', async ({ page }) => {...})`	One test case. `page` is a fresh browser tab.
`await page.goto(url)`	Navigate.
`.fill()` / `.click()`	Actions, on locators from the selector sheet.
`await expect(locator).toBeVisible()`	The assertion = pass/fail. Web-first: auto-retries until true or times out — kills most flakiness.

Common web-first assertions

Assertion	Checks
`toBeVisible()`	Element is shown
`toHaveText('…')` / `toContainText('…')`	Exact / partial text
`toHaveValue('…')`	Input's current value
`toBeChecked()` / `toBeDisabled()`	Checkbox / control state
`toHaveCount(n)`	How many elements match

Running tests

Command	Does
`npx playwright test`	Run all tests (headless).
`npx playwright test --headed`	Watch the browser do it.
`npx playwright test --ui`	Interactive UI mode — time-travel through each step. Best for debugging.
`npx playwright test tests/signup.spec.ts`	Run just one file.
`npx playwright show-report`	Open the HTML report (screenshots, traces) after a run.
`npx playwright codegen localhost:8000`	Record clicks → generates test code. Handy starting point.