1# Test Suite Structure
2 
3## Table of Contents
4 
51. [Configuration](#configuration)
62. [E2E Tests](#e2e-tests)
73. [Component Tests](#component-tests)
84. [API Tests](#api-tests)
95. [Visual Regression Tests](#visual-regression-tests)
106. [Directory Structure](#directory-structure)
117. [Tagging & Filtering](#tagging--filtering)
12 
13### Project Setup
14 
15```bash
16npm init playwright@latest
17```
18 
19## Configuration
20 
21### Essential Configuration
22 
23```typescript
24// playwright.config.ts
25import { defineConfig, devices } from "@playwright/test";
26 
27export default defineConfig({
28  testDir: "./tests",
29  fullyParallel: true,
30  forbidOnly: !!process.env.CI,
31  retries: process.env.CI ? 2 : 0,
32  workers: process.env.CI ? 1 : undefined,
33  reporter: [["html"], ["list"]],
34  use: {
35    baseURL: "http://localhost:3000",
36    trace: "on-first-retry",
37    screenshot: "only-on-failure",
38  },
39  projects: [
40    { name: "setup", testMatch: /.*\.setup\.ts/ },
41    {
42      name: "chromium",
43      use: { ...devices["Desktop Chrome"] },
44      dependencies: ["setup"],
45    },
46  ],
47  webServer: {
48    command: "npm run dev",
49    url: "http://localhost:3000",
50    reuseExistingServer: !process.env.CI,
51  },
52});
53```
54 
55## E2E Tests
56 
57Full user journey tests through the browser.
58 
59### Structure
60 
61```typescript
62// tests/e2e/checkout.spec.ts
63import { test, expect } from "@playwright/test";
64 
65test.describe("Checkout Flow", () => {
66  test.beforeEach(async ({ page }) => {
67    await page.goto("/products");
68  });
69 
70  test("complete purchase as guest", async ({ page }) => {
71    // Add to cart
72    await page.getByRole("button", { name: "Add to Cart" }).first().click();
73    await expect(page.getByTestId("cart-count")).toHaveText("1");
74 
75    // Go to checkout
76    await page.getByRole("link", { name: "Cart" }).click();
77    await page.getByRole("button", { name: "Checkout" }).click();
78 
79    // Fill shipping
80    await page.getByLabel("Email").fill("[email protected]");
81    await page.getByLabel("Address").fill("123 Test St");
82    await page.getByRole("button", { name: "Continue" }).click();
83 
84    // Payment
85    await page.getByLabel("Card Number").fill("4242424242424242");
86    await page.getByRole("button", { name: "Pay Now" }).click();
87 
88    // Confirmation
89    await expect(page.getByRole("heading")).toHaveText("Order Confirmed");
90  });
91 
92  test("apply discount code", async ({ page }) => {
93    await page.getByRole("button", { name: "Add to Cart" }).first().click();
94    await page.getByRole("link", { name: "Cart" }).click();
95 
96    await page.getByLabel("Discount Code").fill("SAVE10");
97    await page.getByRole("button", { name: "Apply" }).click();
98 
99    await expect(page.getByText("10% discount applied")).toBeVisible();
100  });
101});
102```
103 
104### Best Practices
105 
106- Test critical user journeys
107- Keep tests independent
108- Use realistic data
109- Clean up test data in teardown
110 
111## Component Tests
112 
113Test individual components in isolation using Playwright Component Testing.
114 
115```bash
116npm init playwright@latest -- --ct
117```
118 
119For comprehensive component testing patterns including mounting, props, events, slots, mocking, and framework-specific examples (React, Vue, Svelte), see **[component-testing.md](../testing-patterns/component-testing.md)**.
120 
121## API Tests
122 
123Test backend APIs without browser.
124 
125### API Mocking Patterns
126 
127For E2E tests that need to mock API responses:
128 
129```typescript
130// Mock single endpoint
131test("displays mocked users", async ({ page }) => {
132  await page.route("**/api/users", (route) =>
133    route.fulfill({
134      status: 200,
135      json: [{ id: 1, name: "Test User" }],
136    })
137  );
138 
139  await page.goto("/users");
140  await expect(page.getByText("Test User")).toBeVisible();
141});
142 
143// Mock with different responses
144test("handles API errors", async ({ page }) => {
145  await page.route("**/api/users", (route) =>
146    route.fulfill({
147      status: 500,
148      json: { error: "Server error" },
149    })
150  );
151 
152  await page.goto("/users");
153  await expect(page.getByText("Server error")).toBeVisible();
154});
155 
156// Conditional mocking
157test("mocks based on request", async ({ page }) => {
158  await page.route("**/api/users", (route, request) => {
159    if (request.method() === "GET") {
160      route.fulfill({ json: [{ id: 1, name: "User" }] });
161    } else {
162      route.continue();
163    }
164  });
165});
166 
167// Mock with delay (simulate slow network)
168test("handles slow API", async ({ page }) => {
169  await page.route("**/api/data", (route) =>
170    route.fulfill({
171      json: { data: "test" },
172      delay: 2000, // 2 second delay
173    })
174  );
175 
176  await page.goto("/dashboard");
177  await expect(page.getByText("Loading...")).toBeVisible();
178  await expect(page.getByText("test")).toBeVisible();
179});
180```
181 
182For advanced patterns (GraphQL mocking, HAR recording, request modification, network throttling), see **[network-advanced.md](../advanced/network-advanced.md)**.
183 
184## Visual Regression Tests
185 
186Compare screenshots to detect visual changes.
187 
188### Basic Visual Test
189 
190```typescript
191// tests/visual/homepage.spec.ts
192import { test, expect } from "@playwright/test";
193 
194test("homepage visual", async ({ page }) => {
195  await page.goto("/");
196  await expect(page).toHaveScreenshot("homepage.png");
197});
198 
199test("component visual", async ({ page }) => {
200  await page.goto("/components");
201 
202  const button = page.getByRole("button", { name: "Primary" });
203  await expect(button).toHaveScreenshot("primary-button.png");
204});
205```
206 
207### Visual Test Options
208 
209```typescript
210test("dashboard visual", async ({ page }) => {
211  await page.goto("/dashboard");
212 
213  await expect(page).toHaveScreenshot("dashboard.png", {
214    fullPage: true, // Capture entire scrollable page
215    maxDiffPixels: 100, // Allow up to 100 different pixels
216    maxDiffPixelRatio: 0.01, // Or 1% difference
217    threshold: 0.2, // Pixel comparison threshold
218    animations: "disabled", // Disable animations
219    mask: [page.getByTestId("date")], // Mask dynamic content
220  });
221});
222```
223 
224### Handling Dynamic Content
225 
226```typescript
227test("page with dynamic content", async ({ page }) => {
228  await page.goto("/profile");
229 
230  // Mask elements that change
231  await expect(page).toHaveScreenshot("profile.png", {
232    mask: [
233      page.getByTestId("timestamp"),
234      page.getByTestId("avatar"),
235      page.getByRole("img"),
236    ],
237  });
238});
239 
240// Or hide elements via CSS
241test("page hiding dynamic elements", async ({ page }) => {
242  await page.goto("/profile");
243 
244  await page.addStyleTag({
245    content: `
246      .dynamic-content { visibility: hidden !important; }
247      [data-testid="ad-banner"] { display: none !important; }
248    `,
249  });
250 
251  await expect(page).toHaveScreenshot("profile-stable.png");
252});
253```
254 
255### Visual Test Configuration
256 
257```typescript
258// playwright.config.ts
259export default defineConfig({
260  expect: {
261    toHaveScreenshot: {
262      maxDiffPixels: 50,
263      animations: "disabled",
264    },
265  },
266  projects: [
267    {
268      name: "visual-chrome",
269      use: {
270        ...devices["Desktop Chrome"],
271        viewport: { width: 1280, height: 720 },
272      },
273      testMatch: /.*visual.*\.spec\.ts/,
274    },
275  ],
276});
277```
278 
279### Update Snapshots
280 
281```bash
282# Update all snapshots
283npx playwright test --update-snapshots
284 
285# Update specific test
286npx playwright test homepage.spec.ts --update-snapshots
287```
288 
289## Directory Structure
290 
291```
292tests/
293├── e2e/                    # End-to-end tests
294│   ├── auth.spec.ts
295│   ├── checkout.spec.ts
296│   └── dashboard.spec.ts
297├── component/              # Component tests
298│   ├── Button.spec.tsx
299│   └── Modal.spec.tsx
300├── api/                    # API tests
301│   ├── users.spec.ts
302│   └── products.spec.ts
303├── visual/                 # Visual regression tests
304│   └── homepage.spec.ts
305├── fixtures/               # Custom fixtures
306│   ├── auth.fixture.ts
307│   └── api.fixture.ts
308└── pages/                  # Page objects
309    ├── login.page.ts
310    └── dashboard.page.ts
311```
312 
313## Anti-Patterns to Avoid
314 
315| Anti-Pattern                          | Problem                            | Solution                  |
316| ------------------------------------- | ---------------------------------- | ------------------------- |
317| Long test files                       | Hard to maintain, slow to navigate | Split by feature, use POM |
318| Tests depend on execution order       | Flaky, hard to debug               | Keep tests independent    |
319| Testing multiple features in one test | Hard to debug failures             | One feature per test      |
320 
321## Related References
322 
323- **Component Testing**: See [component-testing.md](../testing-patterns/component-testing.md) for comprehensive CT patterns
324- **Projects**: See [projects-dependencies.md](projects-dependencies.md) for project-based filtering
325- **Page Objects**: See [page-object-model.md](page-object-model.md) for organizing page interactions
326- **Test Data**: See [fixtures-hooks.md](fixtures-hooks.md) for managing test data
327 
328## Tagging & Filtering
329 
330### Using Tags
331 
332```typescript
333test("user login @smoke @auth", async ({ page }) => {
334  // ...
335});
336 
337test("checkout flow @e2e @critical", async ({ page }) => {
338  // ...
339});
340 
341test.describe("API tests @api", () => {
342  test("create user", async ({ request }) => {
343    // ...
344  });
345});
346```
347 
348### Running Tagged Tests
349 
350```bash
351# Run smoke tests
352npx playwright test --grep @smoke
353 
354# Run all except slow tests
355npx playwright test --grep-invert @slow
356 
357# Combine tags
358npx playwright test --grep "@smoke|@critical"
359```
360 
361For project-based filtering and advanced project configuration, see **[projects-dependencies.md](projects-dependencies.md)**.
362