1# Assertions & Waiting
2 
3## Table of Contents
4 
51. [Web-First Assertions](#web-first-assertions)
62. [Generic Assertions](#generic-assertions)
73. [Soft Assertions](#soft-assertions)
84. [Waiting Strategies](#waiting-strategies)
95. [Polling & Retrying](#polling--retrying)
106. [Custom Matchers](#custom-matchers)
11 
12## Web-First Assertions
13 
14Auto-retry until condition is met or timeout. Always prefer these over generic assertions.
15 
16### Locator Assertions
17 
18```typescript
19import { expect } from "@playwright/test";
20 
21// Visibility
22await expect(page.getByRole("button")).toBeVisible();
23await expect(page.getByRole("button")).toBeHidden();
24await expect(page.getByRole("button")).not.toBeVisible();
25 
26// Enabled/Disabled
27await expect(page.getByRole("button")).toBeEnabled();
28await expect(page.getByRole("button")).toBeDisabled();
29 
30// Text content
31await expect(page.getByRole("heading")).toHaveText("Welcome");
32await expect(page.getByRole("heading")).toHaveText(/welcome/i);
33await expect(page.getByRole("heading")).toContainText("Welcome");
34 
35// Count
36await expect(page.getByRole("listitem")).toHaveCount(5);
37 
38// Attributes
39await expect(page.getByRole("link")).toHaveAttribute("href", "/home");
40await expect(page.getByRole("img")).toHaveAttribute("alt", /logo/i);
41 
42// CSS
43await expect(page.getByRole("button")).toHaveClass(/primary/);
44await expect(page.getByRole("button")).toHaveCSS("color", "rgb(0, 0, 255)");
45 
46// Input values
47await expect(page.getByLabel("Email")).toHaveValue("[email protected]");
48await expect(page.getByLabel("Email")).toBeEmpty();
49 
50// Focus
51await expect(page.getByLabel("Email")).toBeFocused();
52 
53// Checked state
54await expect(page.getByRole("checkbox")).toBeChecked();
55await expect(page.getByRole("checkbox")).not.toBeChecked();
56 
57// Editable state
58await expect(page.getByLabel("Name")).toBeEditable();
59```
60 
61### Page Assertions
62 
63```typescript
64// URL
65await expect(page).toHaveURL("/dashboard");
66await expect(page).toHaveURL(/\/dashboard/);
67 
68// Title
69await expect(page).toHaveTitle("Dashboard - MyApp");
70await expect(page).toHaveTitle(/dashboard/i);
71```
72 
73### Response Assertions
74 
75```typescript
76const response = await page.request.get("/api/users");
77await expect(response).toBeOK();
78await expect(response).not.toBeOK();
79```
80 
81## Generic Assertions
82 
83Use for non-UI values. Do NOT retry - execute immediately.
84 
85```typescript
86// Equality
87expect(value).toBe(5);
88expect(object).toEqual({ name: "Test" });
89expect(array).toContain("item");
90 
91// Truthiness
92expect(value).toBeTruthy();
93expect(value).toBeFalsy();
94expect(value).toBeNull();
95expect(value).toBeUndefined();
96expect(value).toBeDefined();
97 
98// Numbers
99expect(value).toBeGreaterThan(5);
100expect(value).toBeLessThanOrEqual(10);
101expect(value).toBeCloseTo(5.5, 1);
102 
103// Strings
104expect(string).toMatch(/pattern/);
105expect(string).toContain("substring");
106 
107// Arrays/Objects
108expect(array).toHaveLength(3);
109expect(object).toHaveProperty("key", "value");
110 
111// Exceptions
112expect(() => fn()).toThrow();
113expect(() => fn()).toThrow("error message");
114await expect(asyncFn()).rejects.toThrow();
115```
116 
117## Soft Assertions
118 
119Continue test execution after failure, report all failures at end.
120 
121```typescript
122test("check multiple elements", async ({ page }) => {
123  await page.goto("/dashboard");
124 
125  // Won't stop on first failure
126  await expect.soft(page.getByRole("heading")).toHaveText("Dashboard");
127  await expect.soft(page.getByRole("button", { name: "Save" })).toBeEnabled();
128  await expect.soft(page.getByText("Welcome")).toBeVisible();
129 
130  // Test continues; all failures reported at end
131});
132```
133 
134### Soft Assertions with Early Exit
135 
136```typescript
137test("check form", async ({ page }) => {
138  await expect.soft(page.getByRole("form")).toBeVisible();
139 
140  // Exit early if form not visible (pointless to check fields)
141  if (expect.soft.hasFailures()) {
142    return;
143  }
144 
145  await expect.soft(page.getByLabel("Name")).toBeVisible();
146  await expect.soft(page.getByLabel("Email")).toBeVisible();
147});
148```
149 
150## Waiting Strategies
151 
152### Auto-Waiting (Default)
153 
154Actions automatically wait for:
155 
156- Element to be attached to DOM
157- Element to be visible
158- Element to be stable (no animations)
159- Element to be enabled
160- Element to receive events
161 
162```typescript
163// These auto-wait
164await page.click("button");
165await page.fill("input", "text");
166await page.getByRole("button").click();
167```
168 
169### Wait for Navigation
170 
171```typescript
172// Wait for URL change
173await page.waitForURL("/dashboard");
174await page.waitForURL(/\/dashboard/);
175 
176// Wait for navigation after action
177await Promise.all([
178  page.waitForURL("**/dashboard"),
179  page.click('a[href="/dashboard"]'),
180]);
181 
182// Or without Promise.all
183const urlPromise = page.waitForURL("**/dashboard");
184await page.click("a");
185await urlPromise;
186```
187 
188### Wait for Network
189 
190```typescript
191// Wait for specific response
192const responsePromise = page.waitForResponse("**/api/users");
193await page.click("button");
194const response = await responsePromise;
195expect(response.status()).toBe(200);
196 
197// Wait for request
198const requestPromise = page.waitForRequest("**/api/submit");
199await page.click("button");
200const request = await requestPromise;
201 
202// Wait for no network activity
203await page.waitForLoadState("networkidle");
204```
205 
206### Wait for Element State
207 
208```typescript
209// Wait for element to appear
210await page.getByRole("dialog").waitFor({ state: "visible" });
211 
212// Wait for element to disappear
213await page.getByText("Loading...").waitFor({ state: "hidden" });
214 
215// Wait for element to be attached
216await page.getByTestId("result").waitFor({ state: "attached" });
217 
218// Wait for element to be detached
219await page.getByTestId("modal").waitFor({ state: "detached" });
220```
221 
222### Wait for Function
223 
224```typescript
225// Wait for arbitrary condition
226await page.waitForFunction(() => {
227  return document.querySelector(".loaded") !== null;
228});
229 
230// With arguments
231await page.waitForFunction(
232  (selector) => document.querySelector(selector)?.textContent === "Ready",
233  ".status",
234);
235```
236 
237## Polling & Retrying
238 
239### toPass() for Polling
240 
241Retry until block passes or times out:
242 
243```typescript
244await expect(async () => {
245  const response = await page.request.get("/api/status");
246  expect(response.status()).toBe(200);
247 
248  const data = await response.json();
249  expect(data.ready).toBe(true);
250}).toPass({
251  intervals: [1000, 2000, 5000], // Retry intervals
252  timeout: 30000,
253});
254```
255 
256### expect.poll()
257 
258Poll a function until assertion passes:
259 
260```typescript
261// Poll API until condition met
262await expect
263  .poll(
264    async () => {
265      const response = await page.request.get("/api/job/123");
266      return (await response.json()).status;
267    },
268    {
269      intervals: [1000, 2000, 5000],
270      timeout: 30000,
271    },
272  )
273  .toBe("completed");
274 
275// Poll DOM value
276await expect.poll(() => page.getByTestId("counter").textContent()).toBe("10");
277```
278 
279## Custom Matchers
280 
281```typescript
282// playwright.config.ts or fixtures
283import { expect } from "@playwright/test";
284 
285expect.extend({
286  async toHaveDataLoaded(page: Page) {
287    const locator = page.getByTestId("data-container");
288    let pass = false;
289    let message = "";
290 
291    try {
292      await expect(locator).toBeVisible();
293      await expect(locator).not.toContainText("Loading");
294      pass = true;
295    } catch (e) {
296      message = `Expected data to be loaded but found loading state`;
297    }
298 
299    return { pass, message: () => message };
300  },
301});
302 
303// Extend TypeScript types
304declare global {
305  namespace PlaywrightTest {
306    interface Matchers<R> {
307      toHaveDataLoaded(): Promise<R>;
308    }
309  }
310}
311 
312// Usage
313await expect(page).toHaveDataLoaded();
314```
315 
316## Timeouts
317 
318### Configure Timeouts
319 
320```typescript
321// playwright.config.ts
322export default defineConfig({
323  timeout: 30000, // Test timeout
324  expect: {
325    timeout: 5000, // Assertion timeout
326  },
327});
328 
329// Per-test timeout
330test("long test", async ({ page }) => {
331  test.setTimeout(60000);
332  // ...
333});
334 
335// Per-assertion timeout
336await expect(page.getByRole("button")).toBeVisible({ timeout: 10000 });
337```
338 
339## Best Practices
340 
341| Do                             | Don't                          |
342| ------------------------------ | ------------------------------ |
343| Use web-first assertions       | Use generic assertions for DOM |
344| Let auto-waiting work          | Add unnecessary explicit waits |
345| Use `toPass()` for polling     | Write manual retry loops       |
346| Configure appropriate timeouts | Use `waitForTimeout()`         |
347| Check specific conditions      | Wait for arbitrary time        |
348 
349## Anti-Patterns to Avoid
350 
351| Anti-Pattern                                              | Problem                       | Solution                                     |
352| --------------------------------------------------------- | ----------------------------- | -------------------------------------------- |
353| `await page.waitForTimeout(5000)`                         | Slow, flaky, arbitrary timing | Use auto-waiting or `waitForResponse`        |
354| `await new Promise(resolve => setTimeout(resolve, 1000))` | Same as above                 | Use `waitForResponse` or element state waits |
355| Generic assertions on DOM elements                        | No auto-retry, flaky          | Use web-first assertions with `expect()`     |
356 
357## Related References
358 
359- **Debugging timeout issues**: See [debugging.md](../debugging/debugging.md) for troubleshooting
360- **Fixing flaky tests**: See [debugging.md](../debugging/debugging.md) for race condition solutions
361- **Network interception**: See [test-suite-structure.md](test-suite-structure.md) for API mocking
362