1# Test Annotations & Organization
2 
3## Table of Contents
4 
51. [Skip Annotations](#skip-annotations)
62. [Fixme & Fail Annotations](#fixme--fail-annotations)
73. [Slow Tests](#slow-tests)
84. [Test Steps](#test-steps)
95. [Custom Annotations](#custom-annotations)
106. [Conditional Annotations](#conditional-annotations)
11 
12## Skip Annotations
13 
14### Basic Skip
15 
16```typescript
17// Skip unconditionally
18test.skip("feature not implemented", async ({ page }) => {
19  // This test won't run
20});
21 
22// Skip with reason
23test("payment flow", async ({ page }) => {
24  test.skip(true, "Payment gateway in maintenance");
25  // Test body won't execute
26});
27```
28 
29### Conditional Skip
30 
31```typescript
32test("webkit-specific feature", async ({ page, browserName }) => {
33  test.skip(browserName !== "webkit", "This feature only works in WebKit");
34 
35  await page.goto("/webkit-feature");
36});
37 
38test("production only", async ({ page }) => {
39  test.skip(process.env.ENV !== "production", "Only runs against production");
40 
41  await page.goto("/prod-feature");
42});
43```
44 
45### Skip by Platform
46 
47```typescript
48test("windows-specific", async ({ page }) => {
49  test.skip(process.platform !== "win32", "Windows only");
50});
51 
52test("not on CI", async ({ page }) => {
53  test.skip(!!process.env.CI, "Skipped in CI environment");
54});
55```
56 
57### Skip Describe Block
58 
59```typescript
60test.describe("Admin features", () => {
61  test.skip(
62    ({ browserName }) => browserName === "firefox",
63    "Firefox admin bug",
64  );
65 
66  test("admin dashboard", async ({ page }) => {
67    // Skipped in Firefox
68  });
69 
70  test("admin settings", async ({ page }) => {
71    // Skipped in Firefox
72  });
73});
74```
75 
76## Fixme & Fail Annotations
77 
78### Fixme - Known Issues
79 
80```typescript
81// Mark test as needing fix (skips the test)
82test.fixme("broken after refactor", async ({ page }) => {
83  // Test won't run but is tracked
84});
85 
86// Conditional fixme
87test("flaky on CI", async ({ page }) => {
88  test.fixme(!!process.env.CI, "Investigate CI flakiness - ticket #123");
89 
90  await page.goto("/flaky-feature");
91});
92```
93 
94### Fail - Expected Failures
95 
96```typescript
97// Test is expected to fail (runs but expects failure)
98test("known bug", async ({ page }) => {
99  test.fail();
100 
101  await page.goto("/buggy-page");
102  // If this passes, the test fails (bug was fixed!)
103  await expect(page.getByText("Working")).toBeVisible();
104});
105 
106// Conditional fail
107test("fails on webkit", async ({ page, browserName }) => {
108  test.fail(browserName === "webkit", "WebKit rendering bug #456");
109 
110  await page.goto("/render-test");
111  await expect(page.getByTestId("element")).toHaveCSS("width", "100px");
112});
113```
114 
115### Difference Between Skip, Fixme, Fail
116 
117| Annotation     | Runs? | Use Case                         |
118| -------------- | ----- | -------------------------------- |
119| `test.skip()`  | No    | Feature not applicable           |
120| `test.fixme()` | No    | Known bug, needs investigation   |
121| `test.fail()`  | Yes   | Expected to fail, tracking a bug |
122 
123## Slow Tests
124 
125### Mark Slow Tests
126 
127```typescript
128// Triple the default timeout
129test("large data import", async ({ page }) => {
130  test.slow();
131 
132  await page.goto("/import");
133  await page.setInputFiles("#file", "large-file.csv");
134  await page.getByRole("button", { name: "Import" }).click();
135 
136  await expect(page.getByText("Import complete")).toBeVisible();
137});
138 
139// Conditional slow
140test("video processing", async ({ page, browserName }) => {
141  test.slow(browserName === "webkit", "WebKit video processing is slow");
142 
143  await page.goto("/video-editor");
144});
145```
146 
147### Custom Timeout
148 
149```typescript
150test("very long operation", async ({ page }) => {
151  // Set specific timeout (in milliseconds)
152  test.setTimeout(120000); // 2 minutes
153 
154  await page.goto("/long-operation");
155});
156 
157// Timeout for describe block
158test.describe("Integration tests", () => {
159  test.describe.configure({ timeout: 60000 });
160 
161  test("test 1", async ({ page }) => {
162    // Has 60 second timeout
163  });
164});
165```
166 
167## Test Steps
168 
169### Basic Steps
170 
171```typescript
172test("checkout flow", async ({ page }) => {
173  await test.step("Add item to cart", async () => {
174    await page.goto("/products");
175    await page.getByRole("button", { name: "Add to Cart" }).click();
176  });
177 
178  await test.step("Go to checkout", async () => {
179    await page.getByRole("link", { name: "Cart" }).click();
180    await page.getByRole("button", { name: "Checkout" }).click();
181  });
182 
183  await test.step("Fill shipping info", async () => {
184    await page.getByLabel("Address").fill("123 Test St");
185    await page.getByLabel("City").fill("Test City");
186  });
187 
188  await test.step("Complete payment", async () => {
189    await page.getByLabel("Card").fill("4242424242424242");
190    await page.getByRole("button", { name: "Pay" }).click();
191  });
192 
193  await expect(page.getByText("Order confirmed")).toBeVisible();
194});
195```
196 
197### Nested Steps
198 
199```typescript
200test("user registration", async ({ page }) => {
201  await test.step("Fill registration form", async () => {
202    await page.goto("/register");
203 
204    await test.step("Personal info", async () => {
205      await page.getByLabel("Name").fill("John Doe");
206      await page.getByLabel("Email").fill("[email protected]");
207    });
208 
209    await test.step("Security", async () => {
210      await page.getByLabel("Password").fill("SecurePass123");
211      await page.getByLabel("Confirm Password").fill("SecurePass123");
212    });
213  });
214 
215  await test.step("Submit and verify", async () => {
216    await page.getByRole("button", { name: "Register" }).click();
217    await expect(page.getByText("Welcome")).toBeVisible();
218  });
219});
220```
221 
222### Steps with Return Values
223 
224```typescript
225test("verify order", async ({ page }) => {
226  const orderId = await test.step("Create order", async () => {
227    await page.goto("/checkout");
228    await page.getByRole("button", { name: "Place Order" }).click();
229 
230    // Return value from step
231    return await page.getByTestId("order-id").textContent();
232  });
233 
234  await test.step("Verify order details", async () => {
235    await page.goto(`/orders/${orderId}`);
236    await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
237  });
238});
239```
240 
241### Step in Page Object
242 
243```typescript
244// pages/checkout.page.ts
245export class CheckoutPage {
246  async fillShippingInfo(address: string, city: string) {
247    await test.step("Fill shipping information", async () => {
248      await this.page.getByLabel("Address").fill(address);
249      await this.page.getByLabel("City").fill(city);
250    });
251  }
252 
253  async completePayment(cardNumber: string) {
254    await test.step("Complete payment", async () => {
255      await this.page.getByLabel("Card").fill(cardNumber);
256      await this.page.getByRole("button", { name: "Pay" }).click();
257    });
258  }
259}
260```
261 
262## Custom Annotations
263 
264### Add Annotations
265 
266```typescript
267test("important feature", async ({ page }, testInfo) => {
268  // Add custom annotation
269  testInfo.annotations.push({
270    type: "priority",
271    description: "high",
272  });
273 
274  testInfo.annotations.push({
275    type: "ticket",
276    description: "JIRA-123",
277  });
278 
279  await page.goto("/feature");
280});
281```
282 
283### Annotation Fixture
284 
285```typescript
286// fixtures/annotations.fixture.ts
287import { test as base, TestInfo } from "@playwright/test";
288 
289type AnnotationFixtures = {
290  annotate: {
291    ticket: (id: string) => void;
292    priority: (level: "low" | "medium" | "high") => void;
293    owner: (name: string) => void;
294  };
295};
296 
297export const test = base.extend<AnnotationFixtures>({
298  annotate: async ({}, use, testInfo) => {
299    await use({
300      ticket: (id) => {
301        testInfo.annotations.push({ type: "ticket", description: id });
302      },
303      priority: (level) => {
304        testInfo.annotations.push({ type: "priority", description: level });
305      },
306      owner: (name) => {
307        testInfo.annotations.push({ type: "owner", description: name });
308      },
309    });
310  },
311});
312 
313// Usage
314test("critical feature", async ({ page, annotate }) => {
315  annotate.ticket("JIRA-456");
316  annotate.priority("high");
317  annotate.owner("Alice");
318 
319  await page.goto("/critical");
320});
321```
322 
323### Read Annotations in Reporter
324 
325```typescript
326// reporters/annotation-reporter.ts
327import { Reporter, TestCase, TestResult } from "@playwright/test/reporter";
328 
329class AnnotationReporter implements Reporter {
330  onTestEnd(test: TestCase, result: TestResult) {
331    const ticket = test.annotations.find((a) => a.type === "ticket");
332    const priority = test.annotations.find((a) => a.type === "priority");
333 
334    if (ticket) {
335      console.log(`Test linked to: ${ticket.description}`);
336    }
337 
338    if (priority?.description === "high" && result.status === "failed") {
339      console.log(`HIGH PRIORITY FAILURE: ${test.title}`);
340    }
341  }
342}
343 
344export default AnnotationReporter;
345```
346 
347## Conditional Annotations
348 
349### Annotation Helper
350 
351```typescript
352// helpers/test-annotations.ts
353import { test } from "@playwright/test";
354 
355export function skipInCI(reason = "Skipped in CI") {
356  test.skip(!!process.env.CI, reason);
357}
358 
359export function skipInBrowser(browser: string, reason: string) {
360  test.beforeEach(({ browserName }) => {
361    test.skip(browserName === browser, reason);
362  });
363}
364 
365export function onlyInEnv(env: string) {
366  test.skip(process.env.ENV !== env, `Only runs in ${env}`);
367}
368```
369 
370```typescript
371// tests/feature.spec.ts
372import { skipInCI, onlyInEnv } from "../helpers/test-annotations";
373 
374test("local only feature", async ({ page }) => {
375  skipInCI("Uses local resources");
376 
377  await page.goto("/local-feature");
378});
379 
380test("production check", async ({ page }) => {
381  onlyInEnv("production");
382 
383  await page.goto("/prod-only");
384});
385```
386 
387### Describe-Level Conditions
388 
389```typescript
390test.describe("Mobile features", () => {
391  test.beforeEach(({ isMobile }) => {
392    test.skip(!isMobile, "Mobile only tests");
393  });
394 
395  test("touch gestures", async ({ page }) => {
396    // Only runs on mobile
397  });
398});
399 
400test.describe("Desktop features", () => {
401  test.beforeEach(({ isMobile }) => {
402    test.skip(isMobile, "Desktop only tests");
403  });
404 
405  test("hover interactions", async ({ page }) => {
406    // Only runs on desktop
407  });
408});
409```
410 
411## Anti-Patterns to Avoid
412 
413| Anti-Pattern                | Problem                | Solution                         |
414| --------------------------- | ---------------------- | -------------------------------- |
415| Skipping without reason     | Hard to track why      | Always provide description       |
416| Too many skipped tests      | Test debt accumulates  | Review and clean up regularly    |
417| Using skip instead of fixme | Loses intent           | Use fixme for bugs, skip for N/A |
418| Not using steps             | Hard to debug failures | Group logical actions in steps   |
419 
420## Related References
421 
422- **Test Tags**: See [test-tags.md](test-tags.md) for tagging and filtering tests with `--grep`
423- **Test Organization**: See [test-suite-structure.md](test-suite-structure.md) for structuring tests
424- **Debugging**: See [debugging.md](../debugging/debugging.md) for troubleshooting
425