1# Performance & Parallelization
2 
3## Table of Contents
4 
51. [Parallel Execution](#parallel-execution)
62. [Sharding](#sharding)
73. [Test Optimization](#test-optimization)
84. [Network Optimization](#network-optimization)
95. [Isolation and Parallel Execution](#isolation-and-parallel-execution)
106. [Resource Management](#resource-management)
117. [Benchmarking](#benchmarking)
12 
13## Parallel Execution
14 
15### Configuration
16 
17```typescript
18// playwright.config.ts
19export default defineConfig({
20  // Run test files in parallel
21  fullyParallel: true,
22 
23  // Number of worker processes
24  workers: process.env.CI ? 1 : undefined, // undefined = half CPU cores
25 
26  // Or explicit count
27  // workers: 4,
28  // workers: '50%', // Percentage of CPU cores
29});
30```
31 
32### Serial Execution When Needed
33 
34```typescript
35// Entire file serial
36test.describe.configure({ mode: "serial" });
37 
38test.describe("Sequential Tests", () => {
39  test("first", async ({ page }) => {
40    // Runs first
41  });
42 
43  test("second", async ({ page }) => {
44    // Runs after first
45  });
46});
47```
48 
49```typescript
50// Single describe block serial
51test.describe("Parallel Tests", () => {
52  test("a", async () => {}); // Parallel
53  test("b", async () => {}); // Parallel
54});
55 
56test.describe.serial("Serial Tests", () => {
57  test("c", async () => {}); // Serial
58  test("d", async () => {}); // Serial
59});
60```
61 
62### Parallel Projects
63 
64```typescript
65// playwright.config.ts
66export default defineConfig({
67  projects: [
68    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
69    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
70    { name: "webkit", use: { ...devices["Desktop Safari"] } },
71  ],
72});
73```
74 
75```bash
76# Run all projects in parallel
77npx playwright test
78 
79# Run specific project
80npx playwright test --project=chromium
81```
82 
83## Sharding
84 
85### Basic Sharding
86 
87```bash
88# Split tests across 4 machines
89# Machine 1:
90npx playwright test --shard=1/4
91 
92# Machine 2:
93npx playwright test --shard=2/4
94 
95# Machine 3:
96npx playwright test --shard=3/4
97 
98# Machine 4:
99npx playwright test --shard=4/4
100```
101 
102### Sharding Strategy
103 
104Tests are distributed evenly by file. For optimal sharding:
105 
106- Keep test files similar in size
107- Use `fullyParallel: true` for even distribution
108- Balance slow tests across files
109 
110### CI Sharding Pattern
111 
112```yaml
113# GitHub Actions
114jobs:
115  test:
116    strategy:
117      matrix:
118        shard: [1, 2, 3, 4]
119    steps:
120      - run: npx playwright test --shard=${{ matrix.shard }}/4
121```
122 
123> **For comprehensive CI sharding** (blob reports, merging sharded results, full workflows), see [ci-cd.md](ci-cd.md#sharding).
124 
125## Test Optimization
126 
127### Reuse Authentication
128 
129Avoid logging in for every test. Use setup projects with storage state to authenticate once and reuse the session.
130 
131> **For authentication patterns** (storage state, multiple auth states, setup projects), see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns).
132 
133### Reuse Page State (serial only — trade-off with isolation)
134 
135Sharing a single page/context across tests with `beforeAll`/`afterAll` is **not recommended** for most suites: it breaks test isolation, causes state leak between tests, and makes failures harder to debug. Prefer a fresh `page` per test (Playwright default). Use shared page only when you explicitly need serial execution and accept no isolation.
136 
137```typescript
138// ⚠️ Serial only, no isolation: state from one test leaks into the next.
139// Prefer test.describe.configure({ mode: 'serial' }) + fresh page per test, or beforeEach + page.goto().
140test.describe.configure({ mode: "serial" });
141test.describe("Dashboard", () => {
142  let page: Page;
143 
144  test.beforeAll(async ({ browser }) => {
145    const context = await browser.newContext({
146      storageState: ".auth/user.json",
147    });
148    page = await context.newPage();
149    await page.goto("/dashboard");
150  });
151 
152  test.afterAll(async () => {
153    await page?.close();
154  });
155 
156  test("shows stats", async () => {
157    await expect(page.getByTestId("stats")).toBeVisible();
158  });
159 
160  test("shows chart", async () => {
161    await expect(page.getByTestId("chart")).toBeVisible();
162  });
163});
164```
165 
166### Lazy Navigation
167 
168```typescript
169// Bad: Navigate in every test
170test("check header", async ({ page }) => {
171  await page.goto("/products");
172  await expect(page.getByRole("heading")).toBeVisible();
173});
174 
175test("check footer", async ({ page }) => {
176  await page.goto("/products");
177  await expect(page.getByRole("contentinfo")).toBeVisible();
178});
179 
180// Good: Share navigation
181test.describe("Products Page", () => {
182  test.beforeEach(async ({ page }) => {
183    await page.goto("/products");
184  });
185 
186  test("check header", async ({ page }) => {
187    await expect(page.getByRole("heading")).toBeVisible();
188  });
189 
190  test("check footer", async ({ page }) => {
191    await expect(page.getByRole("contentinfo")).toBeVisible();
192  });
193});
194```
195 
196### Skip Unnecessary Setup
197 
198```typescript
199// Use test.skip for conditional execution
200test("admin feature", async ({ page }) => {
201  test.skip(!process.env.ADMIN_ENABLED, "Admin features disabled");
202  // ...
203});
204 
205// Use test.fixme for known broken tests
206test.fixme("broken feature", async ({ page }) => {
207  // Skipped but tracked
208});
209```
210 
211## Network Optimization
212 
213### Mock APIs
214 
215```typescript
216test.beforeEach(async ({ page }) => {
217  // Mock slow/heavy endpoints
218  await page.route("**/api/analytics", (route) =>
219    route.fulfill({ json: { views: 1000 } }),
220  );
221 
222  await page.route("**/api/recommendations", (route) =>
223    route.fulfill({ json: [] }),
224  );
225});
226```
227 
228### Block Unnecessary Resources
229 
230```typescript
231test.beforeEach(async ({ page }) => {
232  // Block analytics, ads, tracking
233  await page.route("**/*", (route) => {
234    const url = route.request().url();
235    if (
236      url.includes("google-analytics") ||
237      url.includes("facebook") ||
238      url.includes("hotjar")
239    ) {
240      return route.abort();
241    }
242    return route.continue();
243  });
244});
245```
246 
247### Block Resource Types
248 
249```typescript
250// Block images and fonts for faster tests
251await page.route("**/*", (route) => {
252  const resourceType = route.request().resourceType();
253  if (["image", "font", "stylesheet"].includes(resourceType)) {
254    return route.abort();
255  }
256  return route.continue();
257});
258```
259 
260### Cache API Responses
261 
262```typescript
263const apiCache = new Map<string, object>();
264 
265test.beforeEach(async ({ page }) => {
266  await page.route("**/api/**", async (route) => {
267    const url = route.request().url();
268 
269    if (apiCache.has(url)) {
270      return route.fulfill({ json: apiCache.get(url) });
271    }
272 
273    const response = await route.fetch();
274    const json = await response.json();
275    apiCache.set(url, json);
276    return route.fulfill({ json });
277  });
278});
279```
280 
281## Isolation and Parallel Execution
282 
283### Default: one context per test
284 
285Playwright gives each test its own browser context (and page). That gives isolation: no shared cookies, storage, or DOM between tests, so failures don’t carry over and you can run tests in any order or in parallel. Keep this default unless you have a clear reason to share state.
286 
287### Avoiding state leak in parallel runs
288 
289- **Do not** rely on shared mutable state (e.g. a single `page` or `context` in `beforeAll`) when tests can run in parallel. State from one test can leak into another and cause flaky, order-dependent failures.
290- Use **fixtures** for setup/teardown and **`beforeEach`** for per-test navigation so each test gets a fresh page or a clean slate.
291- For **backend or DB state** shared across tests, isolate per worker so parallel workers don’t collide. Use a worker-scoped fixture and `testInfo.workerIndex` (or `process.env.TEST_WORKER_INDEX`) to create unique data per worker (e.g. unique user or DB prefix). See [fixtures-hooks.md](../core/fixtures-hooks.md) for worker-scoped fixtures and [debugging.md](../debugging/debugging.md) for debugging flaky parallel runs.
292 
293### Debugging flaky parallel runs
294 
295If a test is flaky only with multiple workers:
296 
2971. **Reproduce**: Run with default workers and `--repeat-each=10` (or `--repeat-each=100 --max-failures=1`).
2982. **Confirm parallel-specific**: Run with `--workers=1`. If the failure disappears, the cause is likely shared state or non-isolated backend/DB data.
2993. **Fix**: Remove shared page/context; use per-test fixtures and `beforeEach`; isolate test data per worker with `workerIndex` in a worker-scoped fixture.
300 
301Workers are restarted after a test failure so subsequent tests in that worker get a clean environment; fixing isolation still prevents the initial flakiness.
302 
303## Resource Management
304 
305### Browser Contexts
306 
307```typescript
308// Recommended: One context per test (default) — full isolation
309test("isolated test", async ({ page }) => {
310  // Fresh context automatically
311});
312 
313// Manual context for specific needs
314test("multiple tabs", async ({ browser }) => {
315  const context = await browser.newContext();
316  const page1 = await context.newPage();
317  const page2 = await context.newPage();
318 
319  // Clean up
320  await context.close();
321});
322```
323 
324### Memory Management
325 
326```typescript
327// playwright.config.ts
328export default defineConfig({
329  // Limit concurrent workers
330  workers: 2,
331 
332  // Limit parallel tests per worker
333  use: {
334    // Lower memory usage
335    launchOptions: {
336      args: ["--disable-dev-shm-usage"],
337    },
338  },
339});
340```
341 
342### Timeouts
343 
344```typescript
345// playwright.config.ts
346export default defineConfig({
347  // Global test timeout
348  timeout: 30000,
349 
350  // Assertion timeout
351  expect: {
352    timeout: 5000,
353  },
354 
355  // Navigation timeout
356  use: {
357    navigationTimeout: 15000,
358    actionTimeout: 10000,
359  },
360});
361```
362 
363## Benchmarking
364 
365### Measure Test Duration
366 
367```typescript
368test("performance test", async ({ page }, testInfo) => {
369  const startTime = Date.now();
370 
371  await page.goto("/");
372 
373  const loadTime = Date.now() - startTime;
374  console.log(`Page load: ${loadTime}ms`);
375 
376  // Add to test report
377  testInfo.annotations.push({
378    type: "performance",
379    description: `Load time: ${loadTime}ms`,
380  });
381});
382```
383 
384### Performance Metrics
385 
386```typescript
387test("collect metrics", async ({ page }) => {
388  await page.goto("/");
389 
390  const metrics = await page.evaluate(() => ({
391    // Navigation timing
392    loadTime:
393      performance.timing.loadEventEnd - performance.timing.navigationStart,
394    domContentLoaded:
395      performance.timing.domContentLoadedEventEnd -
396      performance.timing.navigationStart,
397 
398    // Performance entries
399    resources: performance.getEntriesByType("resource").length,
400 
401    // Memory (Chrome only)
402    // @ts-ignore
403    memory: performance.memory?.usedJSHeapSize,
404  }));
405 
406  console.log("Metrics:", metrics);
407  expect(metrics.loadTime).toBeLessThan(3000);
408});
409```
410 
411### Lighthouse Integration
412 
413```typescript
414import { playAudit } from "playwright-lighthouse";
415 
416test("lighthouse audit", async ({ page }) => {
417  await page.goto("/");
418 
419  const audit = await playAudit({
420    page,
421    thresholds: {
422      performance: 80,
423      accessibility: 90,
424      "best-practices": 80,
425      seo: 80,
426    },
427    port: 9222,
428  });
429 
430  expect(audit.lhr.categories.performance.score * 100).toBeGreaterThanOrEqual(
431    80,
432  );
433});
434```
435 
436## Performance Checklist
437 
438| Optimization                   | Impact     |
439| ------------------------------ | ---------- |
440| Enable `fullyParallel`         | High       |
441| Reuse authentication           | High       |
442| Mock heavy APIs                | High       |
443| Block tracking scripts         | Medium     |
444| Use sharding in CI             | High       |
445| Reduce workers if memory-bound | Medium     |
446| Cache API responses            | Medium     |
447| Skip unnecessary tests         | Low-Medium |
448 
449## Related References
450 
451- **CI/CD sharding**: See [ci-cd.md](ci-cd.md) for CI configuration
452- **Test organization**: See [test-suite-structure.md](../core/test-suite-structure.md) for structuring tests
453- **Fixtures for reuse**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for authentication patterns
454