# The Playwright Guide β From "Wait, What?" to "Wait, That's It?"
> *"I'm gonna make him an offer he can't refuse." β The Godfather*
>
> Playwright makes testing so easy, you'll wonder why you ever did it any other way.
**The one consolidated guide.** Covers the basics, intermediate patterns, page objects, and the timeouts deep dive β all in one place.
Pick a rail β both share the same content, separated by how much you want to read right now.
### π€οΈ Rail A β Quick Path (ship today)
New to e2e, want green tests inside an hour.
1. [Chapter 1 β Your first test](#-chapter-1-your-first-test--the-hello-world-that-actually-does-something) β `test`, `await`, `expect`
2. [Chapter 4 β `test` vs `describe`](#chapter-4) β pick a style
3. [Chapter 11 β Locators](#-chapter-11-locators--finding-page-elements-with-x-ray-vision) β `getByRole` first
4. [Chapter 12 β Assertions](#-chapter-12-assertions--expect-with-superpowers) β auto-retry magic
5. [Chapter 13 β `playwright.config.ts`](#chapter-13) β browsers, retries, parallel
6. [Bonus Cheat Sheet](#-bonus-cheat-sheet-for-your-wall) β print, stick to monitor
### π€οΈ Rail B β Deep Path (understand every clock)
Tests work, but flakes are eating CI. You want root-cause literacy.
1. Everything in Rail A, plus:
2. [Chapter 6 β Hooks](#-chapter-6-hooks--the-beforeafter-magic) β `beforeAll` at file scope, shared-state trap
3. [Chapter 7 β Fixtures](#-chapter-7-fixtures--the-playwright-superpower) β isolation, not free parallelism
4. [Chapter 14 β Debugging](#-chapter-14-debugging--when-the-test-goes-rogue) β UI Mode, Inspector, Trace Viewer
5. [Chapter 15 β API testing](#-chapter-15-api-testing--the-backstage-pass) β seed via API, assert via UI
6. [Chapter 16 β Page Objects](#chapter-16) β one class per page
7. [Part III β Timeouts Deep Dive (Appendix AβK)](#part-iii--the-timeouts-deep-dive) β every clock, traced
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β WHAT'S INSIDE β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Part I β The Basics (Chapters 1β10): test, await, fixtures β
β Part II β Beyond the Basics (Chapters 11β16): locators, asserts, β
β config, debugging, API, POs β
β Part IIIβ Timeouts Deep Dive (Appendix AβK): every clock, explained β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## π¬ Scene Setting: Why Are We Here?
You've heard the buzz. "Playwright is the new hotness." "Cypress is so 2020." "Selenium? That's vintage."
You open the docs. You see `async`, `await`, `page.goto()`, `expect()`, `describe`, `test`, `it`, `beforeAll`, `afterEach`, **fixtures**...
And your brain goes: **"Excuse me what the actual fork?"**
*Relax. Grab coffee. We're doing this together β step by step, human to human. No capes required (but encouraged).*
---
## π― Chapter 1: Your First Test β The "Hello World" That Actually Does Something
### The Code
```typescript
import { test, expect } from '@playwright/test';
test('homepage has the expected title', async ({ page }) => {
await page.goto('https://playwright.dev/');
await expect(page).toHaveTitle(/Playwright/);
});
```
A real assertion on a real page. If you run this, it goes green. Let's pull it apart.
### What Just Happened? (In Plain English)
| Line | Translation |
|------|-------------|
| `import { test, expect }` | "Hey Playwright, give me your testing tools β and your assert hero." |
| `test('name', async ...)` | "Here's a test. It runs async stuff. Thanks." |
| `{ page }` | "Give me a browser tab. I'll call it `page`." |
| `await page.goto(...)` | "Go to this URL. **Wait until you're there.**" |
| `await expect(page).toHaveTitle(/Playwright/)` | "Keep retrying until the tab title matches β or 5s pass and we fail." |
A test without an `expect(...)` is not a test β it's a script that runs and reports nothing. The `expect()` line is what makes this go **green** or **red**. Don't skip it. (More on the auto-retry magic behind `expect` in [Chapter 12](#-chapter-12-assertions--expect-with-superpowers).)
### The Magic Words: `async` and `await`
With `async`/`await` comes... actually readable async code.
Think of it like preparing a utility belt:
```typescript
async function prepareUtilityBelt() {
const batarang = await forgeBatarang(); // Pause. Wait for forging.
const grapple = await buildGrappleGun(); // Pause. Wait for engineering.
const smoke = await mixSmokePellets(); // Pause. Wait for chemistry.
await attachToBelt(batarang, grapple, smoke); // Pause. Wait for mounting.
return utilityBelt;
}
```
**Without `await`**: You'd hand them a box of raw metal, chemicals, and a cold forge and call it "ready."
**With `await`**: Each gadget is *finished* before the next starts. No mid-air grapple failures.
#### The Cheat Sheet
| Keyword | Job | Analogy |
|---------|-----|---------|
| `async` on function | "I promise this function has pauses" | "This mission has wait times" |
| `await` on line | "Pause **this line** until done" | "Hold position. Don't move until signal." |
> **Rule**: If you use `await` anywhere, the function **must** say `async`. It's the law. JavaScript enforces it.
---
### π VISUAL: How `async`/`await` Flow Works
```mermaid
flowchart TD
A[async function starts] --> B[await step 1]
B -->|WAIT| C[step 1 completes]
C --> D[await step 2]
D -->|WAIT| E[step 2 completes]
E --> F[await step 3]
F -->|WAIT| G[step 3 completes]
G --> H[function returns]
style B fill:#fff3cd,stroke:#ffc107
style D fill:#fff3cd,stroke:#ffc107
style F fill:#fff3cd,stroke:#ffc107
style C fill:#d4edda,stroke:#28a745
style E fill:#d4edda,stroke:#28a745
style G fill:#d4edda,stroke:#28a745
```
> πΌοΈ **Illustration**: [`01-async-await-flow.png`](assets/posts/playwright-guide-illustrations/01-async-await-flow.png) β sequential, not simultaneous.
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β WITHOUT await (CHAOS) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Start β Step 1 β Step 2 β Step 3 β End (all at once!) β
β β β β β β
β βΌ βΌ βΌ βΌ β
β Raw Raw Raw Raw β
β metal chem forge belt = DISASTER β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β WITH await (ORDER) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Start ββwaitβββ Step 1 ββwaitβββ Step 2 ββwaitβββ Step 3 β End β
β β β β β β
β βΌ βΌ βΌ βΌ β
β Forge Complete Build Complete Mix Done! β
β batarang batarang! grapple grapple! smoke β
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## π Chapter 2: Two Ways to Get a Title β Old vs. New
### β The "Grandpa" Way (Promise `.then()`)
```typescript
// This works. But it's 2015 calling.
await page.title().then(title => {
console.log(title);
});
```
**Translation**: "Go get the title. When you *eventually* have it, run this callback function."
Problems:
- Callback hell awaits (pun intended)
- Harder to debug β breakpoints get weird
- Mixing `async`/`await` with `.then()` is like wearing your underwear outside your pants (Superman style, but not in a good way)
### β
The Modern Way (Just `await`)
```typescript
const title = await page.title();
console.log(title);
```
**Translation**: "Get the title. **Wait right here** until you have it. Then continue."
Benefits:
- Reads top-to-bottom like a comic book
- Debugger stops *exactly* where you expect
- Standard in all Playwright docs
- Easy to add `expect(title).toContain('Automation')` next line
---
### π VISUAL: `.then()` vs `await` β The Showdown
```mermaid
flowchart LR
subgraph OLD[β OLD WAY β .then() callback style]
A1[page.title()] --> B1[.then(title => {]
B1 --> C1[console.log(title)
C1 --> D1[});]
end
subgraph NEW[β
NEW WAY β await style]
A2[const title =] --> B2[await page.title()]
B2 --> C2[console.log(title)]
end
style OLD fill:#f8d7da,stroke:#f5c6cb
style NEW fill:#d4edda,stroke:#c3e6cb
```
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β CALLBACK HELL VISUALIZATION β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£
β β
β .then() STYLE (nested callbacks = pyramid of doom): β
β β
β getUser() β
β .then(user => getPosts(user.id)) β
β .then(posts => getComments(posts[0].id)) β
β .then(comments => getLikes(comments[0].id)) β
β .then(likes => console.log(likes)) β
β .catch(err => handleError(err)) β
β β
β βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ βΌ β
β β
β await STYLE (flat, readable, debuggable): β
β β
β const user = await getUser() β Debugger stops HERE β
β const posts = await getPosts(user.id) β Or HERE β
β const comments = await getComments(posts[0].id) β Or HERE β
β const likes = await getLikes(comments[0].id) β Or HERE β
β console.log(likes) β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## π§ Chapter 3: `const` vs `let` β The "I Promise Not to Change This" Rule
```typescript
const title = await page.title(); // "This value stays put β like Superman's moral compass"
let villainCount = 0; // "I might increment this later"
villainCount = villainCount + 1; // OK, we said we'd change it
```
**Golden Rule**: Default to `const`. Only use `let` when you *know* you'll reassign. It catches bugs early.
> *"I find your lack of `const` disturbing." β definitely a developer in another life*
---
### π VISUAL: When to Use Which
```mermaid
flowchart TD
A[Need a variable?] --> B{Will you reassign it?}
B -->|NO| C[Use const β
]
B -->|YES| D[Use let β οΈ]
B -->|NOT SURE| C
C --> E[Catches accidental changes]
C --> F[Signals intent: immutable]
C --> G[Better optimization]
D --> H[Only when loop counters]
D --> I[Or swapping values]
D --> J[Or accumulating results]
style C fill:#d4edda,stroke:#28a745
style D fill:#fff3cd,stroke:#ffc107
```
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β CONST VS LET β QUICK REFERENCE β
ββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββ€
β SCENARIO β CHOICE β
ββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββ€
β Page title β const title = await page.title() β
β Loop counter β let i = 0; i++ β
β Config object β const config = { url: '...', timeout: 5000 }β
β Accumulator β let total = 0; total += item.price β
β Swapping values β let temp = a; a = b; b = temp β
β Test data β const testUser = { name: 'Admin', role: 1 } β
ββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββ
π‘ PRO TIP: If you're not sure, use const. Change to let only when
TypeScript yells at you. It's like a safety net β free insurance.
```
---
## ποΈ Chapter 4: The Great Debate β `test` vs `describe`/`it`
### Style 1: Flat (Playwright's Way) β *Lone Wolf Style*
```typescript
import { test, expect } from '@playwright/test';
test('user can login', async ({ page }) => { ... });
test('user sees dashboard', async ({ page }) => { ... });
test('user can logout', async ({ page }) => { ... });
```
Think: lone wolf. Works alone. Gets the job done. No drama.
### Style 2: Nested (Jest/Jasmine Way)
```typescript
import { test, expect } from '@playwright/test';
test.describe('User authentication', () => {
test('user can login', async ({ page }) => { /* ... */ });
test('user sees dashboard', async ({ page }) => { /* ... */ });
test('user can logout', async ({ page }) => { /* ... */ });
});
```
Think: teamwork. Group photo at the end.
### Plot Twist: **They're the Same Thing**
```typescript
// Inside Playwright source code:
export const it = test; // β it IS test. Just an alias with a cooler name.
```
Playwright gives you `describe` for grouping. That's it. `it` is just `test` wearing a disguise.
---
### π VISUAL: The Two Styles Side by Side
```mermaid
graph TB
subgraph FLAT[FLAT STYLE β Playwright Default]
F1[test: login]
F2[test: dashboard]
F3[test: logout]
F1 -.-> F2
F2 -.-> F3
end
subgraph NESTED[NESTED STYLE β describe/it]
N1[describe: Auth]
N2[test: login]
N3[test: dashboard]
N4[test: logout]
N1 --> N2
N1 --> N3
N1 --> N4
end
subgraph REPORT[TEST REPORT OUTPUT]
R1[β login]
R2[β dashboard]
R3[β logout]
R4[Auth]
R5[ β login]
R6[ β dashboard]
R7[ β logout]
end
FLAT --> R1
FLAT --> R2
FLAT --> R3
NESTED --> R4
NESTED --> R5
NESTED --> R6
NESTED --> R7
style FLAT fill:#e3f2fd,stroke:#2196f3
style NESTED fill:#f3e5f5,stroke:#9c27b0
style REPORT fill:#e8f5e9,stroke:#4caf50
```
> πΌοΈ **Illustration**: [`02-flat-vs-nested.png`](assets/posts/playwright-guide-illustrations/02-flat-vs-nested.png) β two syntaxes, one parallelism engine.
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β FLAT vs NESTED β VISUAL COMPARISON β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£
β β
β FLAT (Playwright style) NESTED (Jest style) β
β βββββββββββββββββββββ βββββββββββββββββββ β
β test('login') βββββββΊ test.describe('Auth') β
β test('dashboard') ββ test('login') β
β test('logout') ββ test('dashboard') β
β ββ test('logout') β
β β
β REPORT: REPORT: β
β β login Auth β
β β dashboard β login β
β β logout β dashboard β
β β logout β
β β
β β
Files run in PARALLEL by default β
Visual grouping in reports β
β β
No shared state (per-test isolation) β οΈ Can share state (hooks) β
β β
Simpler mental model π Extra indentation β
β β No visual grouping β οΈ Tests in one file serial by default β
β β
β * Tests within a single file run serial unless fullyParallel or β
β test.describe.configure({ mode: 'parallel' }). Flat vs describe β
β is grouping, not the parallelism engine. β
β β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## βοΈ Chapter 5: When to Use Which? (The Decision Matrix)
| Situation | Use | Hero Equivalent |
|-----------|-----|-----------------|
| Starting fresh | Flat `test` + fixtures | build it right from scratch |
| Tests share login/setup | `describe` + hooks **or** fixtures | shared mission, shared resources |
| Migrating from Jest | `describe`/`it` (familiar) | friendly neighborhood, familiar vibes |
| Want pretty report folders | `describe` | organized, labeled, tidy |
| Need parallel within file | `test.describe.configure({ mode: 'parallel' })` or `fullyParallel` | files already parallel; speed within file requires opt-in |
| Different users per test | Fixtures (admin, user, guest) | shape-shifts per scenario |
> **My Take**: Start flat. Graduate to `describe` when you *feel the pain* of repeated setup. Don't pre-optimize β even Iron Man built Mark I in a cave before Mark L.
---
### π VISUAL: Decision Flowchart
```mermaid
flowchart TD
START([New Test File?]) --> Q1{Share setup\nacross tests?}
Q1 -->|NO| FLAT[Flat test + fixtures]
Q1 -->|YES| Q2{Setup complex\nor file-specific?}
Q2 -->|File-specific only| DESC[describe + hooks]
Q2 -->|Reusable across files| FIXTURES[Fixtures β¨]
Q2 -->|Migrating from Jest| DESC
Q2 -->|Want report folders| DESC
Q2 -->|Want tests in one file to run concurrently| CONFIGURE[fullyParallel / test.describe.configure({ mode: 'parallel' })]
FLAT --> END[π Happy Testing!]
DESC --> END
FIXTURES --> END
CONFIGURE --> END
style FLAT fill:#e3f2fd,stroke:#2196f3
style DESC fill:#f3e5f5,stroke:#9c27b0
style FIXTURES fill:#e8f5e9,stroke:#4caf50
style CONFIGURE fill:#fff3cd,stroke:#ffc107
style END fill:#fff3e0,stroke:#ff9800
```
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β QUICK DECISION GUIDE β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β βββββββββββββββ βββββββββββββββ βββββββββββββββ β
β β FLAT β β DESCRIBE β β FIXTURES β β
β β TEST β β + HOOKS β β (BEST) β β
β ββββββββ¬βββββββ ββββββββ¬βββββββ ββββββββ¬βββββββ β
β β β β β
β ββββββββΌββββββββββββββββββββΌββββββββββββββββββββΌβββββββ β
β β USE WHEN... β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€ β
β β β’ Simple tests, no shared setup β’ Familiar Jest β β
β β β’ Starting fresh β’ File-only setup β β
β β β’ Independent test cases β’ Visual reports β β
β β β’ Migration path β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β π‘ START HERE β Move right when you feel pain β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## πͺ Chapter 6: Hooks β The "Before/After" Magic
> Hooks live on `test` β there's no bare `beforeAll`/`afterAll` named export. You call `test.beforeAll`, `test.beforeEach`, etc. And they work **at file scope too**, not only inside `test.describe`. A `test.beforeAll(...)` written at the top of a file runs once before any test in that file.
```typescript
import { test, expect } from '@playwright/test';
test.describe('Logged-in dashboard', () => {
let userToken: string;
// Runs ONCE before everything in this describe block
test.beforeAll(async ({ browser }) => {
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('/login');
await page.fill('#user', 'admin');
await page.fill('#pass', 'secret');
await page.click('button:has-text("Login")');
userToken = await page.evaluate(() => localStorage.getItem('token'));
await context.close();
});
// Runs BEFORE EACH test in this describe block
test.beforeEach(async ({ page }) => {
await page.goto('/dashboard');
await page.evaluate((token) => localStorage.setItem('token', token), userToken);
await page.reload();
});
test('shows welcome', async ({ page }) => { /* ... */ });
test('shows stats', async ({ page }) => { /* ... */ });
// Runs ONCE after everything in this describe block
test.afterAll(async () => { /* cleanup */ });
});
```
### Hook Cheatsheet
| Hook | Runs | Use For |
|------|------|---------|
| `test.beforeAll` | Once, before all tests in the scope (file or `test.describe`) | Heavy setup (create test data, not login β use a fixture for that) |
| `test.beforeEach` | Before **each** test | Reset state the previous test polluted |
| `test.afterEach` | After **each** test | Capture artifacts on failure (Playwright already screenshots on retry β check before you write your own) |
| `test.afterAll` | Once, after all tests in the scope | Delete test users, tear down shared resources |
> β οΈ **Warning**: `test.beforeAll` shares state across every test in its scope. If Test 1 deletes the user, Test 2 & 3 fail mysteriously. That's the same "shared state" trap the next chapter solves with **fixtures** β each test gets fresh setup and teardown.
---
### π VISUAL: Hook Execution Timeline
```mermaid
gantt
title Hook Execution Timeline for describe Block
dateFormat X
axisFormat %S
section beforeAll
Login & Token :done, a1, 0, 3
section Test 1
beforeEach :active, b1, 3, 2
Test: Welcome :crit, t1, 5, 3
afterEach :done, c1, 8, 1
section Test 2
beforeEach :active, b2, 9, 2
Test: Stats :crit, t2, 11, 3
afterEach :done, c2, 14, 1
section Test 3
beforeEach :active, b3, 15, 2
Test: Profile :crit, t3, 17, 3
afterEach :done, c3, 20, 1
section afterAll
Cleanup :done, a2, 21, 2
```
> πΌοΈ **Illustration**: [`03-hooks-timeline.png`](assets/posts/playwright-guide-illustrations/03-hooks-timeline.png) β `beforeAll` β `beforeEach` β test β `afterEach` β `afterAll`.
```text
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£
β β
β test.describe('Auth', () => { β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββ β
β β test.beforeAll() ββββββββββββββββ β β RUNS ONCE β
β β Login once, get token β β
β βββββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββ β
β β test.beforeEach() βββββββββββββββ β β RUNS 3 TIMES β
β β Restore token, goto dashboard β β
β βββββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β test 1 β β test 2 β β test 3 β β
β β 'welcome' β β 'stats' β β 'profile' β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββ β
β β test.afterEach() βββββββββββββββ β β RUNS 3 TIMES β
β β Screenshot on fail, cleanup β β
β βββββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββ β
β β test.afterAll() βββββββββββββββββ β β RUNS ONCE β
β β Logout, delete test users β β
β βββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β οΈ DANGER ZONE: test.beforeAll shares state across tests in its scope!
If test 1 deletes the user, test 2 & 3 will fail mysteriously.
This is why fixtures (next chapter) are safer β each test gets fresh state.
Also note: hooks aren't limited to test.describe. test.beforeAll at file
scope runs once before any test IN THAT FILE. Hooks never escape their file.
```
---
## π§ͺ Chapter 7: Fixtures β The Playwright Superpower
> Why do we use fixtures? So we don't repeat ourselves. Work smarter, not harder β shrink the problem.
### The Problem
5 test files. Each needs "logged in as admin." Copy-paste `beforeAll` everywhere? **No.** That's busywork, not a solution.
### The Solution: `fixtures.ts` β build the gadget once
```typescript
// fixtures.ts β build the gadget once
import { test as base, Page } from '@playwright/test';
type MyFixtures = {
loggedInPage: Page;
};
export const test = base.extend({
loggedInPage: async ({ page }, use) => {
// SETUP: Login once
await page.goto('/login');
await page.fill('#user', 'admin');
await page.fill('#pass', 'secret');
await page.click('button:has-text("Login")');
await page.waitForURL('/dashboard');
// HAND OVER to the test β "Here, use this."
await use(page);
// TEARDOWN: Runs after test β self-destruct sequence
await page.evaluate(() => localStorage.clear());
},
});
```
### Using It
```typescript
// dashboard.test.ts
import { test, expect } from './fixtures';
test('dashboard shows welcome', async ({ loggedInPage }) => {
await expect(loggedInPage.locator('h1')).toContainText('Welcome');
});
test('dashboard shows stats', async ({ loggedInPage }) => {
await expect(loggedInPage.locator('.stats')).toBeVisible();
});
```
### Why Fixtures Win
| Feature | `describe` + hooks | Fixtures |
|---------|-------------------|----------|
| Isolation | β Shared state breaks | β
Each test gets fresh fixture |
| TypeScript support | π Manual types | β
Full autocomplete |
| Reuse across files | β Copy-paste | β
Import once, use everywhere |
| Multiple users | π° Nested describes | β
`adminPage`, `userPage`, `guestPage` |
| Dependencies | Hidden | β
Explicit in test signature |
```typescript
// Different fixtures for different needs β your own roster
test('admin sees all', async ({ adminPage }) => { ... });
test('user sees own', async ({ userPage }) => { ... });
test('guest sees login', async ({ guestPage }) => { ... });
```
---
### π VISUAL: Fixtures Architecture
```mermaid
flowchart TB
subgraph FIXTURE[fixtures.ts]
direction TB
F1[base.extend] --> F2[loggedInPage fixture]
F2 --> F3[SETUP: login]
F3 --> F4[use(page)]
F4 --> F5[TEARDOWN: cleanup]
end
subgraph TESTS[Test Files]
direction TB
T1[dashboard.test.ts]
T2[profile.test.ts]
T3[settings.test.ts]
end
subgraph RUN[Test Execution]
direction TB
R1[Test 1: loggedInPage]
R2[Test 2: loggedInPage]
R3[Test 3: loggedInPage]
end
FIXTURE -.->|import| TESTS
TESTS -.->|use| RUN
style FIXTURE fill:#e8f5e9,stroke:#4caf50
style TESTS fill:#e3f2fd,stroke:#2196f3
style RUN fill:#fff3e0,stroke:#ff9800
```
> πΌοΈ **Illustration**: [`04-fixtures-isolation.png`](assets/posts/playwright-guide-illustrations/04-fixtures-isolation.png) β isolation, not free parallelism.
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β FIXTURES vs HOOKS β ISOLATION, NOT PARALLELISM β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£
β β
β PARALLELISM RULE (from Playwright docs): β
β βββββββββββββββββββββββββββββββββββββββ β
β β’ Test FILES run in parallel by default (across workers). β
β β’ Tests WITHIN a single file run SERIALLY by default. β
β β’ To run tests in one file in parallel: set fullyParallel: true or β
β test.describe.configure({ mode: 'parallel' }). β
β β’ Flat vs describe is GROUPING β not the parallelism engine. β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β HOOKS (beforeAll) β shared state risk, not a parallelism blocker: β
β βββββββββββββββββββββββββββββββββββββββ β
β β
β Worker 1: [beforeAll] β [test 1] β [test 2] β [test 3] β [afterAll] β
β β² β² β² β² β
β βββββββββββββ΄βββββββββββ΄βββββββββββ β
β SHARED STATE = DANGER β
β β
β Worker 2 runs OTHER test FILES in parallel (different file = different β
β worker). Tests in a single file are serial regardless of hooks. β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β FIXTURES β ISOLATION, not free parallelism: β
β βββββββββββββββββββββββββββββββββββββββ β
β β
β Worker 1: [fixture setup] β [test 1] β [fixture teardown] β
β Worker 1: [fixture setup] β [test 2] β [fixture teardown] β
β Worker 1: [fixture setup] β [test 3] β [fixture teardown] β
β β
β Tests in a file still run serial unless fullyParallel or β
β test.describe.configure({ mode: 'parallel' }). Fixtures guarantee β
β each test gets a FRESH instance β isolation, not parallel magic. β
β β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MULTIPLE FIXTURES β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β fixtures.ts β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β export const test = base.extend({ β β
β β adminPage: async ({ page }, use) => { login('admin'); ... },β β
β β userPage: async ({ page }, use) => { login('user'); ... }, β β
β β guestPage: async ({ page }, use) => { /* no login */ ... }, β β
β β mobilePage: async ({ page }, use) => { setMobile(); ... }, β β
β β darkModePage: async ({ page }, use) => { setDarkMode(); ... },β β
β β }); β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β Tests pick what they need: β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β test('admin dashboard', async ({ adminPage }) => { ... }); β β
β β test('user profile', async ({ userPage }) => { ... }); β β
β β test('guest landing', async ({ guestPage }) => { ... }); β β
β β test('mobile nav', async ({ mobilePage }) => { ... }); β β
β β test('dark mode', async ({ darkModePage }) => { ... }); β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β β
TypeScript knows exactly which fixture each test gets β
β β
Autocomplete works: loggedInPage. β type-safe β
β β
Run any combo in parallel β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## π Chapter 8: Reports β What You'll See
### Flat Tests
```
β login works
β dashboard loads
β logout works
```
### With `describe`
```
Auth
β login works
β dashboard loads
β logout works
```
Both work in HTML report. `describe` adds folder-like grouping. Flat and describe produce the same execution β `describe` is only a report grouping tool.
---
### π VISUAL: HTML Report Comparison
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PLAYWRIGHT HTML REPORT β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β FLAT TESTS GROUPED WITH describe β
β ββββββββββββββ βββββββββββββββββββ β
β β
β βΌ All Tests (3 passed) βΌ Auth (3 passed) β
β β login works 1.2s β login works 1.2s β
β β dashboard 0.8s β dashboard 0.8s β
β β logout 0.5s β logout 0.5s β
β β
β βΌ Cart (2 passed) βΌ Checkout (1 passed) β
β β add item 0.9s β pay with card 2.1s β
β β remove item 0.4s β
β β
β SEARCH: "login" SEARCH: "Auth" β
β β Finds flat test β Runs all 3 tests in Auth β
β β
β β
β PARALLELISM: Files run in parallel (4 workers). Tests inside each β
β file run serial by default. Flat and describe are both file-level β
β grouping β the engine is the same. β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## π Chapter 9: Running Just One Test (Because Life's Short)
```bash
# Run one test by name (works both styles)
npx playwright test -g "login works"
# Run all tests in a describe block
npx playwright test -g "Auth"
# Run specific file
npx playwright test tests/dashboard.test.ts
```
> You don't need to run all tests every time. Run just what you need. Stay green.
---
### π VISUAL: Test Filtering Commands
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PLAYWRIGHT TEST FILTERING β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β PROJECT STRUCTURE: β
β tests/ β
β βββ auth.test.ts # test.describe('Auth', ...) β
β β βββ test('login') β
β β βββ test('logout') β
β βββ dashboard.test.ts # flat tests β
β β βββ test('welcome') β
β β βββ test('stats') β
β βββ checkout.test.ts β
β βββ test('pay with card') β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β COMMAND β WHAT RUNS β
βββββββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββ€
β npx playwright test β ALL tests β
β npx playwright test tests/authβ¦ β Auth file only β
β npx playwright test -g "login" β Any test with "login" in name β
β npx playwright test -g "Auth" β All tests in Auth describe β
β npx playwright test -g "welcome|stats" β Tests matching regex β
β npx playwright test --project=chromium β Specific browser only β
β npx playwright test --headed β See browser (debug mode) β
β npx playwright test --debug β Inspector + headed + pause β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β PRO TIPS: β
β β’ Use descriptive test names: "user can login with valid credentials" β
β β’ Grep is case-insensitive: -g "LOGIN" works β
β β’ Combine: npx playwright test -g "Auth" --project=firefox β
β β’ Skip: npx playwright test --grep-invert "flaky" β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## π Chapter 10: Your Learning Path (TL;DR)
### Week 1: Just Write Tests
```typescript
test('thing works', async ({ page }) => {
await page.goto('/');
await expect(page.locator('h1')).toBeVisible();
});
```
- Learn `page.goto`, `page.click`, `page.fill`, `expect`
- Don't touch `describe`, fixtures, hooks yet
- Just get a test green. Figure out the basics first.
### Week 2: Feel the Pain
- Notice you're logging in 50 times
- Tests slow because each logs in fresh
- Realize "there's gotta be a better way."
### Week 3: Discover Fixtures
- Move login to `fixtures.ts`
- Import `loggedInPage` everywhere
- Each test now runs in isolation with fresh state β no shared-state surprises
- Watch `fullyParallel` + fresh fixtures give clean, isolated runs π
### Week 4 (Optional): `describe` for Organization
- Group related tests for reports
- Use hooks only when fixture feels heavy
- Team organized and ready for CI.
---
### π VISUAL: 4-Week Learning Journey
```mermaid
journey
title Your Playwright Learning Journey
section Week 1: Origin
Write first test: 5: You
Learn basics: 4: You
Tests pass: 5: You
section Week 2: Pain
Copy-paste login: 2: You
Tests slow: 1: You
Frustration: 3: You
section Week 3: Breakthrough
Create fixtures: 5: You
Parallel runs: 5: You
Clean code: 5: You
section Week 4: Mastery
Organize reports: 4: You
Team adopts: 5: You
Ship confidently: 5: You
```
```text
ββββββββββββββ¦βββββββββββββββββββββββββββββββ
β WEEK β FOCUS β
β βββββββββββββ¬βββββββββββββββββββββββββββββββ£
β WEEK 1 β Syntax & Basics β
β β β’ test(), page, expect β
β β β’ async/await β
β β β’ const/let β
β βββββββββββββ¬βββββββββββββββββββββββββββββββ£
β WEEK 2 β Feel the Pain β
β β β’ Repeated setup β
β β β’ Slow tests β
β β β’ Copy-paste fatigue β
β βββββββββββββ¬βββββββββββββββββββββββββββββββ£
β WEEK 3 β Fixtures = Superpower β
β β β’ base.extend() β
β β β’ Type-safe fixtures β
β β β’ Per-test isolation β
β βββββββββββββ¬βββββββββββββββββββββββββββββββ£
β WEEK 4 β Polish & Organize β
β β β’ describe for reports β
β β β’ Hooks when needed β
β β β’ CI/CD integration β
ββββββββββββββ©βββββββββββββββββββββββββββββββ
```
---
## π Bonus: Cheat Sheet for Your Wall
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PLAYWRIGHT BEGINNER SURVIVAL GUIDE β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
test('name', async ({ page }) => { ... }) β
β β
await page.goto('url') // Go + wait β
β β
await page.click('button') // Click + wait β
β β
await page.fill('#id', 'text') // Type + wait β
β β
const text = await page.textContent('h1') β
β β
expect(locator).toBeVisible() // Assertions β
β β
expect(locator).toHaveText('x') β
β β
β π const > let (unless reassignment) β
β π async function + await = readable async β
β π Fixtures > hooks for shared setup β
β π describe = optional grouping, not required β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
### π VISUAL: Complete Mental Model Map
```mermaid
mindmap
root((Playwright
Testing))
Basics
test()
async/await
page fixture
expect()
Patterns
Flat tests
describe/it
Hooks
Fixtures β
Fixtures
base.extend()
Type-safe
Reusable
Parallel
Multiple types
Reports
Flat list
Grouped tree
HTML/JSON/JUnit
Commands
-g filter
--project
--headed
--debug
Progression
Week 1: Basics
Week 2: Pain
Week 3: Fixtures
Week 4: Organize
```
---
# Part II β Beyond the Basics
> You can write a test that passes. Now write tests that **survive** β flake-free, debuggable, fast, and easy to refactor when the UI changes next sprint.
---
## π― Chapter 11: Locators β Finding Page Elements With X-Ray Vision
> *"You either die a hero, or you live long enough to see yourself use XPath." β paraphrased*
>
> Locators are how your test finds a button, an input, a heading on the page. Get this right and the rest is downhill.
A **locator** is a *resilient* pointer to an element. You create it once; Playwright re-resolves it every time you use it. That's huge β if the DOM shifts, the locator still finds the element. Old Selenium code grabbed an element *once* and held onto it. Playwright grabs a *description* of the element.
```typescript
import { test, expect } from '@playwright/test';
test('homepage heroes are reachable', async ({ page }) => {
await page.goto('https://playwright.dev/');
// Each of these is a Locator (resilient, re-resolved on use)
const getStartedLink = page.getByRole('link', { name: 'Get started' });
const mainHeading = page.getByRole('heading', { level: 1 }).first();
const searchButton = page.getByRole('button', { name: 'Search' });
await expect(getStartedLink).toBeVisible();
await expect(mainHeading).toContainText('Playwright');
await expect(searchButton).toBeVisible();
});
```
Wait β was the title correct? Playwright gives you two assertion shapes:
### `expect()` vs `expect.soft()`
| Assertion | Stops on fail? | Use when |
|-----------|----------------|----------|
| `await expect(loc).toBeVisible({ timeout: 5000 })` | β
Yes β test ends | You *need* this to be true to continue (login button visible before click) |
| `expect.soft(loc).toBeVisible()` | β No β keeps going | You want a full report of everything that's broken, not just the first failure |
Use `expect.soft` sparingly. Most of the time, **fail fast** β that's the default `expect`.
### The Locator Hierarchy β Best to Worst
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LOCATOR PREFERENCE β "RESILIENT FIRST" RANKING β
β βββββββ¦βββββββββββββββββββββββββββ¦βββββββββββββββββββββββββββββββββ£
β RANK β METHOD β WHY β
β βββββββ¬βββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ£
β 1 β getByRole β How users & a11y see the page β
β 2 β getByLabel β Form inputs by label text β
β 3 β getByText β Visible text (headings, links)β
β 4 β getByPlaceholder β Inputs with no label β
β 5 β getByAltText β Images, area maps β
β 6 β getByTitle β Hover tooltips β
β 7 β getByTestId β Stable anchor (data-testid=β¦) β
β βββββββ¬βββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ£
β -- β page.locator('css') β OK fallback β ties to layout β
β -- β page.locator('xpath=β¦') β Last resort, avoid if possibleβ
ββββββββ©βββββββββββββββββββββββββββ©βββββββββββββββββββββββββββββββββ
```
> πΌοΈ **Illustration**: [`05-locator-ranking.png`](assets/posts/playwright-guide-illustrations/05-locator-ranking.png) β resilient first.
> **Rule of thumb**: If a screen reader can find it, your test can find it. `getByRole` is the gold standard because it tests your accessibility *for free*.
#### Cheat sheet β your everyday selectors
| Want to find⦠| Use |
|---------------|-----|
| A "Sign in" button | `page.getByRole('button', { name: 'Sign in' })` |
| An email input | `page.getByLabel('Email')` |
| The page heading | `page.getByRole('heading', { level: 1 })` |
| A link "Prices" | `page.getByRole('link', { name: 'Prices' })` |
| An input with placeholder | `page.getByPlaceholder('you@example.com')` |
| A card with text "Premium" | `page.getByText('Premium', { exact: true })` |
| Anything tagged for tests | `page.getByTestId('checkout-button')` |
#### Filtering & chaining β narrowing it down
```typescript
// Find a specific row inside the cart, then the "Remove" button inside it
const row = page.getByRole('row', { name: 'Bicycle' });
await row.getByRole('button', { name: 'Remove' }).click();
// Multiple matches? Filter by text
await page.getByRole('listitem').filter({ hasText: 'In stock' }).first().click();
// Narrowing by child element
const cardWithPrice = page.locator('.card').filter({ has: page.getByText('$199') });
```
---
## π Chapter 12: Assertions β `expect()` With Superpowers
> *"With great power comes great responsibility." β Spider-Man's Uncle Ben, again, because he was right.*
>
> Playwright `expect` doesn't just *check* β it **retries**. That's the magic that makes your tests stable.
A normal `expect(value === 5)` checks once and either passes or fails. A Playwright `expect(locator).toBeVisible()` checks⦠*and rechecks*⦠*and rechecks*⦠up to your **expect timeout** (default 5,000ms, set in `playwright.config.ts`). The moment it becomes true, it short-circuits and passes. This is why flaky `setTimeout` waits are unnecessary in Playwright.
### The Assert Menu
| Assertion | Direction | Reads as |
|-----------|-----------|----------|
| `toBeVisible()` | state | "is shown on the page" |
| `toBeHidden()` | state | "is NOT shown (display:none, hidden, off-screen)" |
| `toBeEnabled()` | state | "can be interacted with" |
| `toBeDisabled()` | state | "greyed out / can't be clicked" |
| `toBeChecked()` | state | "checkbox/radio selected" |
| `toHaveText('x')` | content | "exact text equals 'x'" |
| `toContainText('x')` | content | "text includes 'x' somewhere" |
| `toHaveValue('x')` | form | "input value equals 'x'" |
| `toHaveCount(3)` | list | "exactly 3 matching elements" |
| `toHaveURL(/dashboard/)` | nav | "current URL matches regex" |
| `toHaveTitle(/Welcome/)` | nav | "tab title matches regex" |
| `toHaveAttribute('href', '/x')` | attr | "attribute matches" |
| `toHaveScreenshot('btn.png')` | visual | "looks identical to saved snapshot" |
### Negating β pass when something is NOT true
```typescript
await expect(locator).not.toBeVisible(); // It stays hidden
await expect(locator).not.toHaveText('Error'); // Error never appears
```
### The two kinds of `expect` β pick the right one
```typescript
// SNAPSHOT β runs ONCE, no retries. For non-DOM values.
expect(typeof title).toBe('string');
expect([1, 2, 3]).toHaveLength(3);
expect(myArray).toContain('admin');
// AUTO-RETRY β keeps polling until true or timeout. For locator-based checks.
await expect(page.getByRole('button')).toBeVisible(); // β note the await
await expect(page.getByText('Saved')).toBeVisible();
```
> β οΈ **Beginner trap**: forgetting `await` on a locator-based `expect`. Playwright will warn, and the assertion becomes a single check β flaky.
> If you're asserting a **locator**, you almost always want **`await expect(locator).toBe...()`**.
### The "Soft" Mode β See All The Broken Things At Once
```typescript
// Without soft: stops at the first failure. You fix one thing, run again, find two more.
// With soft: runs every expect, then reports all of them.
await expect.soft(page.getByText('Total')).toBeVisible();
await expect.soft(page.getByText('Subtotal')).toBeVisible();
await expect.soft(page.getByText('Tax')).toBeVisible();
```
Great for "smoke" checks where you want a full triage list, not whack-a-mole debugging.
---
## βοΈ Chapter 13: The `playwright.config.ts` β Mission Control
> The config file is where you decide *everything* about how your tests run: browsers, timeouts, retries, parallelism. It's your mission brief before tests run.
Here's a representative `playwright.config.ts` for a TypeScript project, annotated:
```typescript
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests', // β where the .spec.ts files live
fullyParallel: true, // β tests run side-by-side, not in a queue
timeout: 30 * 1000, // β each test gets 30s before it's killed
expect: { timeout: 5000 }, // β each expect() retries for up to 5s
forbidOnly: !!process.env.CI, // β test.only is a crime on CI
retries: process.env.CI ? 2 : 0, // β flakes get a second chance on CI
workers: process.env.CI ? 1 : undefined, // β one worker on CI, all of them locally
reporter: 'html', // β produces playwright-report/index.html
use: {
trace: 'on-first-retry', // β record a trace when a retry happens
browserName: 'chromium', // β default browser (overridden per project)
headless: true, // β no visible browser window
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
],
});
```
### Settings worth memorizing
| Setting | Default | Tune it when⦠|
|---------|---------|---------------|
| `timeout` | 30s | Tests time out before finishing long flows β bump it |
| `expect.timeout` | 5s | Stable asserts keep failing β page is slow, not broken |
| `retries` | 0 (CI: 2) | You want to distinguish *flaky* from *broken* |
| `workers` | auto | CI is overloaded (lower it) or local has cores to spare |
| `fullyParallel` | `true` | You have shared mutable state β go serial |
| `trace` | `off` | You can't reproduce a CI failure β turn on `'on-first-retry'` |
### Projects β the same tests, different heroes
```typescript
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
// { name: 'Mobile Chrome', use: { ...devices['Pixel 5'] } },
// { name: 'iPhone 12', use: { ...devices['iPhone 12'] } },
]
// Run just one browser's suite
// npx playwright test --project=firefox
// Run the desktop trio, skip mobile
// npx playwright test --project=chromium --project=firefox --project=webkit
```
> π‘ **Pro tip**: tests run once *per project*. Three projects = three runs. That's the price of confidence. If CI is slow, trim the project list or shard.
### `use.baseURL` β save yourself the URL ritual
```typescript
use: { baseURL: 'https://playwright.dev' }
// Now in your tests:
await page.goto('/docs/intro'); // β relative URL, prepended automatically
await page.goto('/'); // β homepage
```
---
## π Chapter 14: Debugging β When the Test Goes Rogue
> Tests will fail. That's the point. The goal isn't to *avoid* failure β it's to **find it fast** and **understand it**.
### The Three Musketeers of Debugging
| Tool | One-liner | What you get |
|------|-----------|--------------|
| **UI Mode** | `npx playwright test --ui` | Interactive watch mode. Click to rerun, hover to time-travel, filter by status |
| **Inspector** | `npx playwright test --debug` | Browser opens, pauses *before each action*, shows the locator it's about to hit |
| **Trace Viewer** | `npx playwright show-trace trace.zip` | Post-mortem: every action, screenshot, DOM snapshot, network call, console log |
#### `--debug` β step through live
```bash
npx playwright test tests/login.spec.ts --debug
```
- Browser opens visibly (headless = false).
- Playwright **pauses** before every action.
- Press βΆ to step. Watch what it actually clicks.
- Use the **Pick locator** button to grab a selector and try it live.
#### `--ui` β your testing dashboard
```bash
npx playwright test --ui
```
A side panel lists every test. Click one to run it. Files watch for changes. You get a timeline, a screenshot gallery, and a built-in locator explorer. **This is what you'll use 90% of the time locally.**
#### Trace Viewer β the autopsy
If `trace: 'on-first-retry'` is set, every test that fails-and-retries records a **trace**. Open it after the run:
```bash
npx playwright show-trace test-results/.../trace.zip
```
You'll see a filmstrip of the run: every action with a *before* and *after* DOM snapshot, console output, network requests, and the exact locator used. It's a flight-data recorder for your test.
### The Beginner's Anti-Flake Checklist
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β "MY TEST WORKS LOCALLY BUT FAILS ON CI" β A CHECKLIST β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£
β β Did I wait for a network-idle state that never comes on slow CI? β
β β Drop waitForLoadState('networkidle'), use locator-based waits β
β β Am I using a time-based sleep? (page.waitForTimeout(2000)) β
β β Replace with `await expect(locator).toBeVisible()` β
β β Is my selector layout-dependent? ('.col-md-4 > div:nth-child(2)') β
β β Switch to getByRole / getByLabel / getByTestId β
β β Does my test depend on a specific screen size? β
β β Set `use: { viewport: { width, height } }` explicitly β
β β Am I sharing state across tests in a describe? β
β β Each test should log in with fresh state β use a fixture β
β β Is the date/time timezone-dependent? (toLocaleString()) β
β β Pin the timezone in the test, or stub `Date` β
β β Is there a hidden animation still in progress? β
β β await page.waitForFunction(() => !document.hidden) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
> **Iron Law**: If you reach for `page.waitForTimeout(3000)`, stop. You're guessing. Use a locator-based assertion instead. The clock is a liar; the DOM is the truth.
> πͺ **War story.** A checkout test was flaky on CI for two weeks. Locally it passed every time. Trace viewer showed the failure landing at the "Place order" click. Root cause: a cookie banner appeared ~1.5s after `load` β slowmarketing script on CI took longer than on my laptop. The click hit the banner, not the button. Two-line fix: `await expect(page.getByRole('button', { name: 'Accept all' })).toBeHidden()` before clicking place order, then `await locator.click({ timeout: 5000 })`. Flakes went to zero. The clock was lying; the DOM told the truth. Lesson: every "flaky on CI" bug I've chased was a missing actionability wait, never a missing sleep.
---
## π‘ Chapter 15: API Testing β The Backstage Pass
> Some tests just want to skip the UI. And they should β API tests run **10Γ faster** and cut out the flaky middleman.
You don't have a browser in API tests; you have a `request` object Playwright hands you. It hits endpoints directly.
```typescript
import { test, expect } from '@playwright/test';
test('GET /api/products returns a list', async ({ request }) => {
const response = await request.get('/api/products');
// Status
expect(response.ok()).toBeTruthy(); // 2xx
expect(response.status()).toBe(200);
// Body β automatically parsed as JSON
const body = await response.json();
expect(Array.isArray(body)).toBe(true);
expect(body.length).toBeGreaterThan(0);
expect(body[0]).toHaveProperty('name');
});
test('POST /api/login returns a token', async ({ request }) => {
const response = await request.post('/api/login', {
data: { email: 'admin@demo.com', password: 'secret' },
});
const body = await response.json();
expect(body.token).toBeDefined();
});
```
### Why mix API + UI in one test?
The killer pattern: **set up state via API, assert via UI**. No more "log in via the UI 40 times."
```typescript
import { test, expect } from '@playwright/test';
test('logged-in user sees their purchases', async ({ request, page }) => {
// 1. Log in via API (fast, no clicks, no rendering)
const login = await request.post('/api/login', {
data: { email: 'admin@demo.com', password: 'secret' },
});
const { token } = await login.json();
// 2. Seed some purchased items via API
await request.post('/api/cart', {
data: { sku: 'BIKE-001', qty: 1 },
headers: { Authorization: `Bearer ${token}` },
});
// 3. Inject the token into the browser session
await page.addInitScript((t) => localStorage.setItem('token', t), token);
await page.goto('/dashboard');
// 4. Assert only the meaningful UI behavior
await expect(page.getByText('Bicycle')).toBeVisible();
});
```
> π‘ This is the same idea as fixtures (Chapter 7), just using the network. Use API for **setup**, UI for **assertions**.
### The Methods
| Method | Use | Example |
|--------|-----|---------|
| `request.get(url)` | Read | Fetch a list |
| `request.post(url, { data })` | Create | Submit a form |
| `request.put(url, { data })` | Replace | Update a whole record |
| `request.patch(url, { data })` | Modify | Update one field |
| `request.delete(url)` | Remove | Tear down what you made |
| `request.fetch(url, { method })` | Custom | Anything weird |
All return a `response` with `.ok()`, `.status()`, `.json()`, `.text()`, `.headers()`.
---
## ποΈ Chapter 16: Page Objects β Because Copy-Paste Is Not a Design Pattern
> Page Objects (PO) are how you keep your tests from rotting. When the button "Sign in" becomes "Continue", you change **one** line in the PO, not thirty lines across thirty tests.
### The Pain (without Page Objects)
```typescript
test('user can log in', async ({ page }) => {
await page.goto('https://demo.example.com/login');
await page.getByLabel('Email').fill('admin@demo.com');
await page.getByLabel('Password').fill('secret');
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByText('Welcome')).toBeVisible();
});
test('admin sees dashboard', async ({ page }) => {
await page.goto('https://demo.example.com/login');
await page.getByLabel('Email').fill('admin@demo.com');
await page.getByLabel('Password').fill('secret');
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByText('Welcome')).toBeVisible();
await expect(page.getByText('Admin Console')).toBeVisible();
});
```
Copy-paste the login four times? When the button label changes, you update four tests. Multiply by twenty files. **This is a bug farm.**
### The Fix: One Class Per Page (or Component)
```typescript
// pages/LoginPage.ts
import { Page, Locator, expect } from '@playwright/test';
export class LoginPage {
private readonly emailField: Locator;
private readonly passwordField: Locator;
private readonly signInButton: Locator;
private readonly welcomeMessage: Locator;
constructor(private readonly page: Page) {
this.emailField = page.getByLabel('Email');
this.passwordField = page.getByLabel('Password');
this.signInButton = page.getByRole('button', { name: 'Sign in' });
this.welcomeMessage = page.getByText('Welcome');
}
async goto() {
await this.page.goto('https://demo.example.com/login');
}
async login(email: string, password: string) {
await this.emailField.fill(email);
await this.passwordField.fill(password);
await this.signInButton.click();
await expect(this.welcomeMessage).toBeVisible();
}
}
```
### Using It in a Test β *Clean, Readable, Reusable*
```typescript
// tests/login.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from '../pages/LoginPage';
test('user can log in', async ({ page }) => {
const login = new LoginPage(page);
await login.goto();
await login.login('admin@demo.com', 'secret');
// Welcome assertion ran inside login() β no need to repeat it here
await expect(page).toHaveURL(/dashboard/);
});
test('admin sees the console', async ({ page }) => {
const login = new LoginPage(page);
await login.goto();
await login.login('admin@demo.com', 'secret');
await expect(page.getByText('Admin Console')).toBeVisible();
});
```
When the button label changes from "Sign in" to "Continue", you edit **one line** in `LoginPage.ts`. Every test that calls `login()` keeps working. **That's the whole idea.**
### The Three Laws of Page Objects
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 1. ENCAPSULATE β the test knows NOTHING about HTML. β
β Tests talk to methods. Methods talk to locators. Locators β
β talk to the DOM. Never skip a layer. β
β β
β 2. ASSERT INCREMENTALLY β Page Objects make ASSERTIONS, not β
β return raw element handles. β
β β
login(...) returns void and asserts "Welcome" β
β β getEmailField() returns a Locator for the test to assert β
β (small exceptions for shared POs called from many tests) β
β β
β 3. ONE CLASS PER PAGE β don't glue "LoginPage + DashboardPage" β
β into a single "App". Each page is its own unit. β
β Composition over inheritance unless you genuinely share it. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
### Page Object vs Fixture β Pick a Lane
| Situation | Reach for |
|-----------|-----------|
| A single page reused across many tests | **Page Object** (LoginPage, CartPage) |
| Cross-cutting state *before* the test (log in once, seed data) | **Fixture** (Chapter 7) |
| Both | A fixture that *yields* a PO |
| Flaky low-level UI interaction (drag-drop, file upload) | Helper method on the PO |
```typescript
// The combo move: a fixture gives you a ready-to-use Page Object
export const test = base.extend<{ loginPage: LoginPage }>({
loginPage: async ({ page }, use) => {
const lp = new LoginPage(page);
await lp.goto();
await use(lp);
},
});
test('go straight to dashboard', async ({ loginPage }) => {
await loginPage.login('admin@demo.com', 'secret');
});
```
### Component-vs-Page: When to Split
A **Page Object** owns a *whole route* (`/login`, `/cart`, `/checkout`). A **Component** owns a *widget* reused on many routes (a ``, a ``). Build both when the widget shows up in 3+ pages.
> π§ **Iron Law**: If you can write the same selector twice without flinching, it belongs in a PO. If you can write the same *page flow* twice, it belongs in a PO **method**.
---
## π¬ Part II Closing Credits
> You don't need a bigger boat. You need **fixtures**, **locators**, and **Page Objects**.
Start small. Write ugly tests. Make them pass. Then refactor.
The best test is the one that catches a bug at 2 AM before production reaches the water supply.
**Happy testing! π**
---
*Found this helpful? Star the repo. Found a typo? PR welcome. Confused? Open an issue β I answer like a human, not a bot.*
---
*Previous chapters: The Basics β Locators β Assertions β Config β Debugging β API β Page Objects.*
*Next up: [Part III β The Timeouts Deep Dive](#part-iii--the-timeouts-deep-dive)*
# Part III β The Timeouts Deep Dive
> A timeout is not a number. It's a **promise**: "I'll wait *this long* for reality to match expectation, and if it doesn't, something is genuinely wrong." Get this wrong and you get either flakes (timeout too short) or slow tests (timeout too long).
This appendix goes one layer deeper than the basics. If `test` / `await` / fixtures are still fuzzy, read Part I first.
---
## Appendix A β Map of the Territory
```mermaid
mindmap
root((Timeouts))
Per-test
test.timeout (30s whole-test ceiling)
expect.timeout (5s assertion polling window)
Per-action (config overrides)
actionTimeout
covers click / fill / press / check / hover...
navigationTimeout
covers goto / waitForURL / reload / goBack
(per-call inline { timeout } always wins)
Whole-run
globalTimeout (total run ceiling, not per-action)
Fixture-scoped
test.setTimeout(value) inside a fixture
Avoid
waitForTimeout (sleep)
waitForLoadState networkidle
```
> πΌοΈ **Illustration**: [`07-timeout-layers.png`](assets/posts/playwright-guide-illustrations/07-timeout-layers.png) β narrowest wins.
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β THE FOUR LAYERS OF TIMEOUTS β NARROWEST TO WIDEST β
β βββββββββββββββββββββββββ¦ββββββββββββββββββββ¦ββββββββββββββββββββββββββββ£
β LAYER β SCOPE β EXAMPLE β
β βββββββββββββββββββββββββ¬ββββββββββββββββββββ¬ββββββββββββββββββββββββββββ£
β 1. Inline 3rd arg β ONE call β page.goto(url, { timeout: 10000 }) β
β 2. test.setTimeout β ONE test β test.setTimeout(60000) β
β 3. use.actionTimeout β ALL actions β use: { actionTimeout: 8000 } β
β 4. config-level β EVERYTHING β timeout / expect.timeout β
ββββββββββββββββββββββββββ©ββββββββββββββββββββ©ββββββββββββββββββββββββββββββββββββββ
Rule: the NARROWER layer WINS. Inline argument beats config setting.
```
---
## Appendix B - The Two Big Numbers in `playwright.config.ts`
```typescript
export default defineConfig({
timeout: 30 * 1000, // β (1) whole-test ceiling
expect: { timeout: 5000 }, // β (2) per-assertion polling window
});
```
### (1) `timeout` β the whole-test ceiling
This is the **execution timeout** for one test (including all `beforeEach`/`afterEach` for that test). If the test body + fixtures exceed `30 * 1000` ms, Playwright kills the worker and marks the test **timed out** β not failed, *timed out*.
- Default: **30 seconds**
- Set per test: `test.setTimeout(120000)` (override just one slow test)
- Inside a test: `test.setTimeout(test.info().timeout + 10_000)` (extend the current budget)
### (2) `expect.timeout` β the assertion polling window
This is how long `await expect(locator).toBeVisible()` will **re-check** the page before giving up. The whole point of `expect` is *retry-on-truth*. If the element becomes visible in 80ms, the assert passes in 80ms. If it never appears, the assert polls until `expect.timeout` then fails.
- Default: **5 seconds**
- Override per assertion: `expect(loc, { timeout: 10000 }).toBeVisible()`
> β οΈ **Beginner trap**: Bumping `expect.timeout` to "fix" a flaky assert. If an assertion consistently needs > 5s, the page is *genuinely slow* or your selector is wrong β investigate, don't widen the window.
---
## Appendix C - Action Timeouts β `click`, `fill`, `press`β¦
Every method that interacts with the DOM takes an optional **second/ third argument** `{ timeout }`. This is the **actionability timeout**: Playwright waits for the element to be *visible, stable, enabled, and receptive* before performing the action.
```typescript
// Click a button β wait up to 10s for it to become actionable
await page.getByRole('button', { name: 'Buy' }).click({ timeout: 10000 });
// Fill an input β wait up to 10s for it to accept text
await page.getByLabel('Email').fill('admin@demo.com', { timeout: 10000 });
```
| Method | Default timeout | Tunable? |
|--------|----------------|----------|
| `page.goto` | 30s | β
`{ timeout }` |
| `page.waitForURL` | 30s | β
`{ timeout }` |
| `locator.click` | `actionTimeout` (default β until actionability fails) | β
`{ timeout }` |
| `locator.fill` | `actionTimeout` | β
`{ timeout }` |
| `locator.press` | `actionTimeout` | β
`{ timeout }` |
| `locator.selectOption` | `actionTimeout` | β
`{ timeout }` |
| `locator.check` / `.uncheck` | `actionTimeout` | β
`{ timeout }` |
### Actionability β what "clickable" actually means
Before `click()` fires, Playwright silently waits until the element satisfies **all** of:
1. **Visible** β has non-empty bounding box, no `display:none` / `visibility:hidden`.
2. **Stable** β not animating (the bounding box is the same for two consecutive animation frames).
3. **Enabled** β no `disabled` attribute, not a descendant of an `[aria-disabled=true]` element.
4. **Receives events** β the point it's about to click isn't intercepted by an overlay, modal, or `pointer-events: none`.
If any of these are false when the `{ timeout }` elapses, the action **fails** β but *with a great message*. Read those failures carefully: they tell you *which* of the four failed and why.
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β "ELEMENT IS NOT INTERACTABLE" β READ THE FOUR BLOCKERS β
β βββββββββββββββββββ¦βββββββββββββββββββββββββββββ¦βββββββββββββββββββββββ
β SYMPTOM β REAL CAUSE β FIX β
β βββββββββββββββββββ¬βββββββββββββββββββββββββββββ¬βββββββββββββββββββββββ
β "element is hidden"β display:none still set β Wait for a state β
β β or in a closed menu β transition to finish β
β "element not stable"β CSS animation running β await it; or .first() β
β "element is detached"β DOM node replaced β Query locator fresh β
β "intercepts pointer"β Overlay/modal on top β Close the overlay, β
β β (cookie banner!) β or use force:true β
ββββββββββββββββββββ©βββββββββββββββββββββββββββββ©βββββββββββββββββββββββ
```
> π‘ The `force: true` option **skips** actionability checks. Use sparingly β it's "I know, just click it anyway." You lose resilience and you lose the diagnostic message on failure.
> πΌοΈ **Illustration**: [`06-actionability.png`](assets/posts/playwright-guide-illustrations/06-actionability.png) β the four blockers Playwright waits for before an action.
---
## Appendix D - Navigation Timeouts β `goto`, `waitForURL`, `loadState`
`page.goto(url)` does **two things**:
1. Triggers the navigation.
2. Waits for the page's **load state**.
### Load states β the four you should know
| State | Meaning | Use cases |
|-------|---------|-----------|
| `'commit'` | Network response received, document starts parsing | "Did the request even land?" |
| `'domcontentloaded'` | DOM parsed, but stylesheets/images may not be done | Most page-level asserts |
| `'load'` (default for `goto`) | `window.onload` fired | "Page is fully rendered" |
| `'networkidle'` | No network requests for **500ms** | β οΈ Avoid on streaming/polling apps |
```typescript
// Default: waits for 'load'.
await page.goto('/dashboard');
// Wait specifically for DOM to be parsed (faster, often all you need)
await page.goto('/dashboard', { waitUntil: 'domcontentloaded' });
// Faster still β just want the response status, not the render
await page.goto('/dashboard', { waitUntil: 'commit' });
```
### The `networkidle` trap
> `networkidle` is the option every new Playwright user reaches for β and the one that **refuses** to settle down on any modern SPA.
`networkidle` requires **0 network requests for 500ms**. That works for static pages. On a dashboard with websockets, analytics beacons, polling, or a heartbeat, `networkidle` may **never** settle β your `goto` times out at 30s.
**Reach for `networkidle` only when**:
- You're testing a static marketing page.
- You're integrating with a third-party site you can't control.
**Prefer**:
- `waitUntil: 'domcontentloaded'` for the navigation.
- Then `await expect(locator).toBeVisible()` for the actual condition you care about. The **locator assertion** replaces the brittle load-state guess.
### `waitForURL` β asserting the navigation actually landed
After a click that should redirect, don't assume β assert:
```typescript
await page.getByRole('link', { name: 'Profile' }).click();
await page.waitForURL('**/profile', { timeout: 10000 });
// Or with a regex
await page.waitForURL(/profile\/\d+/, { timeout: 10000 });
```
Bonus: `waitForURL` is **interceptable**. Playwright knows about redirects, SPA route changes, and `history.pushState`. A naive `await page.waitForTimeout(1000)` knows nothing.
---
## Appendix E - The Per-Test Override β `test.setTimeout`
```typescript
test('checkout with 50 items', async ({ page }) => {
test.setTimeout(120000); // β this test gets 2 minutes
test.slow(); // β shortcut: triple the default timeout
// ... long flow ...
});
```
| Call | Effect |
|------|--------|
| `test.setTimeout(60_000)` | Sets the whole-test ceiling to 60s, *replacing* the config value |
| `test.slow()` | Multiplies the config timeout by 3 β handy for known-slow tests |
| `test.setTimeout(0)` | Disables the timeout entirely (use only for interactive debugging) |
| `test.info().timeout` | Reads the current timeout (useful for relative bumps) |
### Times up *mid-test*? Use `test.info().setTimeout`
```typescript
// Discover the file is bigger than expected β extend the budget conditionally
const fileSize = await page.locator('.upload-progress').getAttribute('data-size');
if (Number(fileSize) > 10_000_000) {
test.info().setTimeout(test.info().timeout + 60_000); // +60s for big uploads
}
```
---
## Appendix F - Config-Level Overrides β `actionTimeout`, `navigationTimeout`
Want to set a default timeout for **every** click, fill, and goto without touching every call site? Use these in `playwright.config.ts β use`:
```typescript
export default defineConfig({
use: {
actionTimeout: 10_000, // β every action (click / fill / press / check / hover) gets 10s by default
navigationTimeout: 20_000, // β every goto / waitForURL / reload gets 20s
},
});
```
| Setting | Applies to | Default |
|---------|-----------|---------|
| `actionTimeout` | `click`, `fill`, `press`, `check`, `selectOption`, `hover`, β¦ | none β only the whole-test `timeout` caps it |
| `navigationTimeout` | `goto`, `goBack`, `goForward`, `reload`, `waitForURL` | none β falls through to the whole-test `timeout` |
| per-call `{ timeout }` | One specific call (e.g. `locator.click({ timeout: 5000 })`) | always wins over the two settings above |
> β οΈ There are **no** `clickTimeout` / `fillTimeout` / `pressTimeout` config keys. `actionTimeout` covers all of them as a group. To tune one specific action, pass `{ timeout }` on that call.
> β οΈ `actionTimeout` and `navigationTimeout` are **ignored** when you pass `{ timeout }` on a specific call β the inline argument always wins.
---
## Appendix G - The `waitFor*` Family β When Not to Use Them
| Method | What it does | When to use |
|--------|-------------|-------------|
| `locator.waitFor({ state: 'attached' })` | Wait for element to be in DOM | It may never become visible (hidden tab) |
| `locator.waitFor({ state: 'visible' })` | Wait for it to be rendered | Manual waits before non-assert code |
| `locator.waitFor({ state: 'detached' })` | Wait for it to disappear | Modal closed, spinner removed |
| `page.waitForResponse(urlOrPredicate)` | Wait for a specific network call | You kicked off an XHR and need its result |
| `page.waitForRequest(...)` | Wait for an outbound request | "Did we actually fire the analytics call?" |
| `page.waitForFunction(() => β¦)` | Wait for arbitrary JS condition | Page state not expressible as a locator |
| `page.waitForTimeout(ms)` | **Sleep** | β **Never** (see below) |
| `page.waitForLoadState('load')` | Wait for a load state | Rarely β `goto` already does this |
```typescript
// GOOD β wait for a locator, get auto-retry for free
await expect(page.getByText('Saving complete')).toBeVisible();
// GOOD β explicit waitFor before a non-assert operation
await page.getByText('Saving complete').waitFor();
await page.screenshot({ path: 'saved.png' }); // non-assert, can't be wrapped in expect
// GOOD β wait for a specific network call
await page.click('Download');
const [response] = await Promise.all([
page.waitForResponse(r => r.url().includes('/export') && r.status() === 200),
page.click('Confirm'),
]);
// BAD β fixed sleep. You're literally guessing. Never do this.
await page.waitForTimeout(2000);
```
> β **The Iron Law of `waitForTimeout`**: every `waitForTimeout` in your test is a bug you haven't found yet. Replace it with a locator-based assertion or `waitForResponse`. The clock is a liar; the DOM is the truth.
### When `waitForFunction` is genuinely the right tool
```typescript
// Infinite scroll: wait until row count stopped growing for 200ms
await page.waitForFunction(() => {
const rows = document.querySelectorAll('.row');
const count = rows.length;
if (count === (window as any).__lastRows) return true;
(window as any).__lastRows = count;
return false;
}, undefined, { timeout: 10000 });
```
Use `waitForFunction` when the readiness signal isn't expressible as a DOM element you can `expect`. Otherwise, prefer assertions.
---
## Appendix H - Retries β the Soft Side of Timeouts
A retry is a timeout you're willing to be wrong about *once*. Configure in `playwright.config.ts`:
```typescript
export default defineConfig({
retries: 2, // β retry every failing test twice
// retries: process.env.CI ? 2 : 0, // β only on CI (common pattern)
});
```
### How retries interact with timeouts
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β FLOW: a test hits the 30s whole-test timeout β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β
β Run #1: ... β Test "timed out" after 30000ms β
β β β
β βΌ β
β Is retries > 0? ββnoβββΊ FAIL (no retry) β
β β yes β
β βΌ β
β Run #2: ... β Pass β
β β β
β βΌ β
β β marked FLAKY in the report β
β (failed first, passed on retry = the official definition) β
β β
β Run #2: ... β Same failure? β
β β yes, retries > 1 β
β βΌ β
β Run #3: ... β Still failing β FAIL (hard) β
β β
β Each RETRY replays the whole test on a fresh worker, with the β
β FULL timeout budget again. There is no other retry mode. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
| What you set | Effect |
|--------------|--------|
| `retries: 0` | A failure is a failure. Strictest β every red is a real red. |
| `retries: 2` | A failing test is retried up to 2 more times (3 runs total). A test that **fails first, passes on retry** is reported as **flaky** β surfaced in the report but not blocking CI. That's the official definition of "flaky" in Playwright: failed-then-passed-on-retry. |
| `retries: process.env.CI ? 2 : 0` | Common pattern β be strict locally, give CI a second chance (CI machines are noisier than your laptop). |
> β οΈ There is **no `retries: { mode: ... }` object form**. Retries is just a number. Each retry replays the whole test from scratch on a fresh worker β that's the only behavior, no opt-in required.
> π‘ **What "flaky" means in a Playwright report.** A test that **failed first, passed on retry** is marked flaky. The opposite case β passing first, then failing on a later run β is not the Playwright definition of flaky; that's intermittent breakage and you should debug root cause, not widen retry windows. If a test *consistently* needs 2 runs to pass, bump the timeout or fix the selector β don't bump retries.
### `--retry` from the CLI
```bash
npx playwright test --retries=3 # one-off override
npx playwright test --grep-invert flaky --retries=1 # be strict about known-flaky tests
```
---
## Appendix I - Fixtures and Timeouts β Easy to Get Surprised
A fixture's setup and teardown count toward the **test's** timeout budget. If your `loggedInPage` fixture takes 20s to log in, your test has only 10s left of a 30s ceiling.
### The fix: `test.setTimeout(...)` in the fixture
```typescript
export const test = base.extend<{ loggedInPage: Page }>({
loggedInPage: async ({ page }, use) => {
test.setTimeout(60_000); // β this test (and fixture) gets 60s
await login(page);
await use(page); // β test runs with the remaining budget
await page.context().storageState(); // β teardown also counts!
},
});
```
> β οΈ `test.setTimeout` inside a fixture **applies to the test that uses it**. If multiple fixtures call it, the last one wins. Pick one fixture to be "budget owner" and let it set the timeout.
### Worker-scoped fixtures and the worker timeout
Worker fixtures (`test.extend` with the `{ scope: 'worker' }` option) run **once per worker**, not per test. They have their **own** 30s budget β set with `test.setTimeout` inside the fixture, just the same.
---
## Appendix J - The Decision Flowchart β "Which Timeout Is This?"
```mermaid
flowchart TD
Q([Something is timing out. What is it?]) --> A{Is it a single\nspecific call?}
A -->|YES| B["Add { timeout } inline β narrowest fix"]
A -->|NO| C{Is it one specific\nslow test?}
C -->|YES| D["test.setTimeout inside the test"]
C -->|NO| E{Is it one KIND of action\nall clicks / all gotos?}
E -->|YES| F["use.actionTimeout or\nuse.navigationTimeout in config"]
E -->|NO| G{Is it every test\nin the file/suite?}
G -->|YES| H["timeout in defineConfig,\nor describe.configure"]
G -->|NO| I["It's a flake, not a timeout.\nBump retries, debug the page"]
B --> Z[β
Fixed]
D --> Z
F --> Z
H --> Z
I --> Y[π Investigate root cause first]
style B fill:#d4edda,stroke:#28a745
style D fill:#d4edda,stroke:#28a745
style F fill:#d4edda,stroke:#28a745
style H fill:#d4edda,stroke:#28a745
style I fill:#f8d7da,stroke:#f5c6cb
```
```text
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β THE 60-SECOND TIMEOUT TRIAGE β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β
β "Test timed out 30000ms" β whole-test ceiling. Bump β
β `timeout` or test.setTimeout β
β "expectβ¦toBeVisible (5000ms)" β assertion polling window. β
β Bump `expect.timeout` or the β
β inline arg β
β "click timeout 10000ms" β single action. Inline arg or β
β use.actionTimeout β
β "page.goto: Timeout 30000ms" β navigation. Set navigation β
β Timeout or pick a faster β
β waitUntil β
β "Element is not interactable" β not a timeout. Actionability β
β check failed. Fix the page. β
β "Test passed on retry" (report) β flaky. Page is slow or β
β selector is brittle. β
β β
β β οΈ STEP ZERO BEFORE ANY OF THIS: read the full error. Playwright β
β tells you where, what, and which timeout fired. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## Appendix K - The Timeouts Cheat Sheet
```text
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PLAYWRIGHT TIMEOUTS CHEAT SHEET β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β (1) test ceiling defineConfig(timeout: 30_000) β
β (2) assert window defineConfig(expect: { timeout: 5000 }) β
β (3) all-navigation use: { navigationTimeout: 20_000 } β
β (4) all-actions use: { actionTimeout: 10_000 } β
β (5) one test test.setTimeout(120_000) / test.slow() β
β (6) one call page.goto(url, { timeout: 10000 }) β
β (7) one assertion expect(loc, { timeout: 10000 }).toBe...() β
β β
β β NEVER use page.waitForTimeout(ms) β replace w/ expect β
β β οΈ USE SPARINGLY networkidle β modern SPAs don't settle β
β β
PREFER locator-based expect() β auto-retry + fast β
β β
PREFER waitForResponse for the network you triggeredβ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## π¬ Closing Credits
> A good timeout is invisible. The clock is a liar; the DOM is the truth.
**Happy waiting (intelligently)! β³**
---
*Found this helpful? Star the repo. Found a typo? PR welcome. Confused? Open an issue β I answer like a human, not a bot.*
---
*The Playwright Guide β consolidated from the original beginner guide, BLOG_POST, and the timeouts deep dive. Covers Playwright 1.40+. Cross-checked against the official [timeouts docs](https://playwright.dev/docs/test-timeouts) and the [actionability spec](https://playwright.dev/docs/actionability).*
---
## π Sources
Cross-checked against the official Playwright docs (Node.js). All facts in this guide β defaults, signatures, modes of parallelism, retry behavior, actionability criteria β were verified against these pages before publishing.
| Topic | Official URL |
|-------|--------------|
| Timeouts (test, expect, action, navigation, fixture, global) | https://playwright.dev/docs/test-timeouts |
| Actionability (visible, stable, enabled, receives events) | https://playwright.dev/docs/actionability |
| Fixtures (built-in, custom, worker-scoped, automatic, options) | https://playwright.dev/docs/test-fixtures |
| Parallelism (files parallel by default, serial tests, fullyParallel, configure modes) | https://playwright.dev/docs/test-parallel |
| Retries (number form, "flaky" = failed-then-passed, serial mode) | https://playwright.dev/docs/test-retries |
| Assertions (auto-retrying vs non-retrying, soft, expect.configure, expect.poll, expect.toPass) | https://playwright.dev/docs/test-assertions |
| Writing tests (basic shape, `await expect`, the `page` fixture) | https://playwright.dev/docs/writing-tests |
| Locators (getByRole / getByLabel / getByText and the resilience ranking) | https://playwright.dev/docs/locators |
| Page Object Models (the Playwright-canonical PO pattern) | https://playwright.dev/docs/pom |
If anything here contradicts the official docs, the docs win.