Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

infrastructure-ci-cd/performance.md

View on GitHub
# Performance & Parallelization

## Table of Contents

1. [Parallel Execution](#parallel-execution)
2. [Sharding](#sharding)
3. [Test Optimization](#test-optimization)
4. [Network Optimization](#network-optimization)
5. [Isolation and Parallel Execution](#isolation-and-parallel-execution)
6. [Resource Management](#resource-management)
7. [Benchmarking](#benchmarking)

## Parallel Execution

### Configuration

```typescript
// playwright.config.ts
export default defineConfig({
	// Run test files in parallel
	fullyParallel: true,

	// Number of worker processes
	workers: process.env.CI ? 1 : undefined // undefined = half CPU cores

	// Or explicit count
	// workers: 4,
	// workers: '50%', // Percentage of CPU cores
});
```

### Serial Execution When Needed

```typescript
// Entire file serial
test.describe.configure({ mode: 'serial' });

test.describe('Sequential Tests', () => {
	test('first', async ({ page }) => {
		// Runs first
	});

	test('second', async ({ page }) => {
		// Runs after first
	});
});
```

```typescript
// Single describe block serial
test.describe('Parallel Tests', () => {
	test('a', async () => {}); // Parallel
	test('b', async () => {}); // Parallel
});

test.describe.serial('Serial Tests', () => {
	test('c', async () => {}); // Serial
	test('d', async () => {}); // Serial
});
```

### Parallel Projects

```typescript
// playwright.config.ts
export default defineConfig({
	projects: [
		{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
		{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
		{ name: 'webkit', use: { ...devices['Desktop Safari'] } }
	]
});
```

```bash
# Run all projects in parallel
npx playwright test

# Run specific project
npx playwright test --project=chromium
```

## Sharding

### Basic Sharding

```bash
# Split tests across 4 machines
# Machine 1:
npx playwright test --shard=1/4

# Machine 2:
npx playwright test --shard=2/4

# Machine 3:
npx playwright test --shard=3/4

# Machine 4:
npx playwright test --shard=4/4
```

### Sharding Strategy

Tests are distributed evenly by file. For optimal sharding:

- Keep test files similar in size
- Use `fullyParallel: true` for even distribution
- Balance slow tests across files

### CI Sharding Pattern

```yaml
# GitHub Actions
jobs:
    test:
        strategy:
            matrix:
                shard: [1, 2, 3, 4]
        steps:
            - run: npx playwright test --shard=${{ matrix.shard }}/4
```

> **For comprehensive CI sharding** (blob reports, merging sharded results, full workflows), see [ci-cd.md](ci-cd.md#sharding).

## Test Optimization

### Reuse Authentication

Avoid logging in for every test. Use setup projects with storage state to authenticate once and reuse the session.

> **For authentication patterns** (storage state, multiple auth states, setup projects), see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns).

### Reuse Page State (serial only — trade-off with isolation)

Sharing 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.

```typescript
// ⚠️ Serial only, no isolation: state from one test leaks into the next.
// Prefer test.describe.configure({ mode: 'serial' }) + fresh page per test, or beforeEach + page.goto().
test.describe.configure({ mode: 'serial' });
test.describe('Dashboard', () => {
	let page: Page;

	test.beforeAll(async ({ browser }) => {
		const context = await browser.newContext({
			storageState: '.auth/user.json'
		});
		page = await context.newPage();
		await page.goto('/dashboard');
	});

	test.afterAll(async () => {
		await page?.close();
	});

	test('shows stats', async () => {
		await expect(page.getByTestId('stats')).toBeVisible();
	});

	test('shows chart', async () => {
		await expect(page.getByTestId('chart')).toBeVisible();
	});
});
```

### Lazy Navigation

```typescript
// Bad: Navigate in every test
test('check header', async ({ page }) => {
	await page.goto('/products');
	await expect(page.getByRole('heading')).toBeVisible();
});

test('check footer', async ({ page }) => {
	await page.goto('/products');
	await expect(page.getByRole('contentinfo')).toBeVisible();
});

// Good: Share navigation
test.describe('Products Page', () => {
	test.beforeEach(async ({ page }) => {
		await page.goto('/products');
	});

	test('check header', async ({ page }) => {
		await expect(page.getByRole('heading')).toBeVisible();
	});

	test('check footer', async ({ page }) => {
		await expect(page.getByRole('contentinfo')).toBeVisible();
	});
});
```

### Skip Unnecessary Setup

```typescript
// Use test.skip for conditional execution
test('admin feature', async ({ page }) => {
	test.skip(!process.env.ADMIN_ENABLED, 'Admin features disabled');
	// ...
});

// Use test.fixme for known broken tests
test.fixme('broken feature', async ({ page }) => {
	// Skipped but tracked
});
```

## Network Optimization

### Mock APIs

```typescript
test.beforeEach(async ({ page }) => {
	// Mock slow/heavy endpoints
	await page.route('**/api/analytics', (route) => route.fulfill({ json: { views: 1000 } }));

	await page.route('**/api/recommendations', (route) => route.fulfill({ json: [] }));
});
```

### Block Unnecessary Resources

```typescript
test.beforeEach(async ({ page }) => {
	// Block analytics, ads, tracking
	await page.route('**/*', (route) => {
		const url = route.request().url();
		if (url.includes('google-analytics') || url.includes('facebook') || url.includes('hotjar')) {
			return route.abort();
		}
		return route.continue();
	});
});
```

### Block Resource Types

```typescript
// Block images and fonts for faster tests
await page.route('**/*', (route) => {
	const resourceType = route.request().resourceType();
	if (['image', 'font', 'stylesheet'].includes(resourceType)) {
		return route.abort();
	}
	return route.continue();
});
```

### Cache API Responses

```typescript
const apiCache = new Map<string, object>();

test.beforeEach(async ({ page }) => {
	await page.route('**/api/**', async (route) => {
		const url = route.request().url();

		if (apiCache.has(url)) {
			return route.fulfill({ json: apiCache.get(url) });
		}

		const response = await route.fetch();
		const json = await response.json();
		apiCache.set(url, json);
		return route.fulfill({ json });
	});
});
```

## Isolation and Parallel Execution

### Default: one context per test

Playwright 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.

### Avoiding state leak in parallel runs

- **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.
- Use **fixtures** for setup/teardown and **`beforeEach`** for per-test navigation so each test gets a fresh page or a clean slate.
- 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.

### Debugging flaky parallel runs

If a test is flaky only with multiple workers:

1. **Reproduce**: Run with default workers and `--repeat-each=10` (or `--repeat-each=100 --max-failures=1`).
2. **Confirm parallel-specific**: Run with `--workers=1`. If the failure disappears, the cause is likely shared state or non-isolated backend/DB data.
3. **Fix**: Remove shared page/context; use per-test fixtures and `beforeEach`; isolate test data per worker with `workerIndex` in a worker-scoped fixture.

Workers are restarted after a test failure so subsequent tests in that worker get a clean environment; fixing isolation still prevents the initial flakiness.

## Resource Management

### Browser Contexts

```typescript
// Recommended: One context per test (default) — full isolation
test('isolated test', async ({ page }) => {
	// Fresh context automatically
});

// Manual context for specific needs
test('multiple tabs', async ({ browser }) => {
	const context = await browser.newContext();
	const page1 = await context.newPage();
	const page2 = await context.newPage();

	// Clean up
	await context.close();
});
```

### Memory Management

```typescript
// playwright.config.ts
export default defineConfig({
	// Limit concurrent workers
	workers: 2,

	// Limit parallel tests per worker
	use: {
		// Lower memory usage
		launchOptions: {
			args: ['--disable-dev-shm-usage']
		}
	}
});
```

### Timeouts

```typescript
// playwright.config.ts
export default defineConfig({
	// Global test timeout
	timeout: 30000,

	// Assertion timeout
	expect: {
		timeout: 5000
	},

	// Navigation timeout
	use: {
		navigationTimeout: 15000,
		actionTimeout: 10000
	}
});
```

## Benchmarking

### Measure Test Duration

```typescript
test('performance test', async ({ page }, testInfo) => {
	const startTime = Date.now();

	await page.goto('/');

	const loadTime = Date.now() - startTime;
	console.log(`Page load: ${loadTime}ms`);

	// Add to test report
	testInfo.annotations.push({
		type: 'performance',
		description: `Load time: ${loadTime}ms`
	});
});
```

### Performance Metrics

```typescript
test('collect metrics', async ({ page }) => {
	await page.goto('/');

	const metrics = await page.evaluate(() => ({
		// Navigation timing
		loadTime: performance.timing.loadEventEnd - performance.timing.navigationStart,
		domContentLoaded: performance.timing.domContentLoadedEventEnd - performance.timing.navigationStart,

		// Performance entries
		resources: performance.getEntriesByType('resource').length,

		// Memory (Chrome only)
		// @ts-ignore
		memory: performance.memory?.usedJSHeapSize
	}));

	console.log('Metrics:', metrics);
	expect(metrics.loadTime).toBeLessThan(3000);
});
```

### Lighthouse Integration

```typescript
import { playAudit } from 'playwright-lighthouse';

test('lighthouse audit', async ({ page }) => {
	await page.goto('/');

	const audit = await playAudit({
		page,
		thresholds: {
			performance: 80,
			accessibility: 90,
			'best-practices': 80,
			seo: 80
		},
		port: 9222
	});

	expect(audit.lhr.categories.performance.score * 100).toBeGreaterThanOrEqual(80);
});
```

## Performance Checklist

| Optimization                   | Impact     |
| ------------------------------ | ---------- |
| Enable `fullyParallel`         | High       |
| Reuse authentication           | High       |
| Mock heavy APIs                | High       |
| Block tracking scripts         | Medium     |
| Use sharding in CI             | High       |
| Reduce workers if memory-bound | Medium     |
| Cache API responses            | Medium     |
| Skip unnecessary tests         | Low-Medium |

## Related References

- **CI/CD sharding**: See [ci-cd.md](ci-cd.md) for CI configuration
- **Test organization**: See [test-suite-structure.md](../core/test-suite-structure.md) for structuring tests
- **Fixtures for reuse**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for authentication patterns
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall