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

testing-patterns/performance-testing.md

View on GitHub
# Performance Testing & Web Vitals

## Table of Contents

1. [Core Web Vitals](#core-web-vitals)
2. [Performance Metrics](#performance-metrics)
3. [Performance Budgets](#performance-budgets)
4. [Lighthouse Integration](#lighthouse-integration)
5. [Performance Fixtures](#performance-fixtures)
6. [CI Performance Monitoring](#ci-performance-monitoring)

## Core Web Vitals

### Measure LCP, FID, CLS

```typescript
test('core web vitals within thresholds', async ({ page }) => {
	// Inject web-vitals library
	await page.addInitScript(() => {
		(window as any).__webVitals = {};

		// Simplified web vitals collection
		new PerformanceObserver((list) => {
			for (const entry of list.getEntries()) {
				if (entry.entryType === 'largest-contentful-paint') {
					(window as any).__webVitals.lcp = entry.startTime;
				}
			}
		}).observe({ type: 'largest-contentful-paint', buffered: true });

		new PerformanceObserver((list) => {
			let cls = 0;
			for (const entry of list.getEntries() as any[]) {
				if (!entry.hadRecentInput) {
					cls += entry.value;
				}
			}
			(window as any).__webVitals.cls = cls;
		}).observe({ type: 'layout-shift', buffered: true });
	});

	await page.goto('/');

	// Wait for page to stabilize
	await page.waitForLoadState('networkidle');

	// Get metrics
	const vitals = await page.evaluate(() => (window as any).__webVitals);

	// Assert thresholds (Google's "good" thresholds)
	expect(vitals.lcp).toBeLessThan(2500); // LCP < 2.5s
	expect(vitals.cls).toBeLessThan(0.1); // CLS < 0.1
});
```

### Using web-vitals Library

```typescript
test('web vitals with library', async ({ page }) => {
	await page.addInitScript(() => {
		(window as any).__vitals = {};
	});

	// Inject web-vitals after navigation
	await page.goto('/');

	await page.addScriptTag({
		url: 'https://unpkg.com/web-vitals@3/dist/web-vitals.iife.js'
	});

	await page.evaluate(() => {
		const { onLCP, onFID, onCLS, onFCP, onTTFB } = (window as any).webVitals;

		onLCP((metric: any) => ((window as any).__vitals.lcp = metric.value));
		onFID((metric: any) => ((window as any).__vitals.fid = metric.value));
		onCLS((metric: any) => ((window as any).__vitals.cls = metric.value));
		onFCP((metric: any) => ((window as any).__vitals.fcp = metric.value));
		onTTFB((metric: any) => ((window as any).__vitals.ttfb = metric.value));
	});

	// Trigger FID by clicking
	await page.getByRole('button').first().click();

	// Wait and collect
	await page.waitForTimeout(1000);

	const vitals = await page.evaluate(() => (window as any).__vitals);

	console.log('Web Vitals:', vitals);

	// Assertions
	if (vitals.lcp) expect(vitals.lcp).toBeLessThan(2500);
	if (vitals.fid) expect(vitals.fid).toBeLessThan(100);
	if (vitals.cls) expect(vitals.cls).toBeLessThan(0.1);
});
```

## Performance Metrics

### Navigation Timing

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

	const timing = await page.evaluate(() => {
		const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;

		return {
			// Time to First Byte
			ttfb: nav.responseStart - nav.requestStart,
			// DOM Content Loaded
			domContentLoaded: nav.domContentLoadedEventEnd - nav.startTime,
			// Full page load
			loadComplete: nav.loadEventEnd - nav.startTime,
			// DNS lookup
			dns: nav.domainLookupEnd - nav.domainLookupStart,
			// Connection time
			connection: nav.connectEnd - nav.connectStart,
			// Download time
			download: nav.responseEnd - nav.responseStart,
			// DOM processing
			domProcessing: nav.domComplete - nav.domInteractive
		};
	});

	console.log('Performance timing:', timing);

	// Assertions
	expect(timing.ttfb).toBeLessThan(600); // TTFB < 600ms
	expect(timing.domContentLoaded).toBeLessThan(2000); // DCL < 2s
	expect(timing.loadComplete).toBeLessThan(4000); // Load < 4s
});
```

### Resource Timing

```typescript
test('resource loading performance', async ({ page }) => {
	await page.goto('/');

	const resources = await page.evaluate(() => {
		return performance.getEntriesByType('resource').map((entry) => ({
			name: entry.name.split('/').pop(),
			type: (entry as PerformanceResourceTiming).initiatorType,
			duration: entry.duration,
			size: (entry as PerformanceResourceTiming).transferSize
		}));
	});

	// Find slow resources
	const slowResources = resources.filter((r) => r.duration > 1000);

	if (slowResources.length > 0) {
		console.warn('Slow resources:', slowResources);
	}

	// Find large resources
	const largeResources = resources.filter((r) => r.size > 500000); // > 500KB

	expect(largeResources.length).toBe(0);
});
```

### Memory Usage

```typescript
test('memory usage is reasonable', async ({ page }) => {
	await page.goto('/dashboard');

	// Check memory (Chrome only)
	const memory = await page.evaluate(() => {
		if ((performance as any).memory) {
			return {
				usedJSHeapSize: (performance as any).memory.usedJSHeapSize,
				totalJSHeapSize: (performance as any).memory.totalJSHeapSize
			};
		}
		return null;
	});

	if (memory) {
		const usedMB = memory.usedJSHeapSize / 1024 / 1024;
		console.log(`Memory usage: ${usedMB.toFixed(2)} MB`);

		// Assert reasonable memory usage
		expect(usedMB).toBeLessThan(100); // < 100MB
	}
});
```

## Performance Budgets

### Define Budgets

```typescript
// performance-budgets.ts
export const budgets = {
	homepage: {
		lcp: 2500,
		cls: 0.1,
		fcp: 1800,
		ttfb: 600,
		totalSize: 1500000, // 1.5MB
		jsSize: 500000, // 500KB
		imageCount: 20
	},
	dashboard: {
		lcp: 3000,
		cls: 0.1,
		fcp: 2000,
		ttfb: 800,
		totalSize: 2000000,
		jsSize: 800000
	}
};
```

### Test Against Budgets

```typescript
import { budgets } from './performance-budgets';

test('homepage meets performance budget', async ({ page }) => {
	const budget = budgets.homepage;

	await page.goto('/');
	await page.waitForLoadState('networkidle');

	// Measure LCP
	const lcp = await page.evaluate(() => {
		return new Promise<number>((resolve) => {
			new PerformanceObserver((list) => {
				const entries = list.getEntries();
				resolve(entries[entries.length - 1].startTime);
			}).observe({ type: 'largest-contentful-paint', buffered: true });
		});
	});

	// Measure resources
	const resources = await page.evaluate(() => {
		const entries = performance.getEntriesByType('resource') as PerformanceResourceTiming[];
		return {
			totalSize: entries.reduce((sum, e) => sum + (e.transferSize || 0), 0),
			jsSize: entries
				.filter((e) => e.initiatorType === 'script')
				.reduce((sum, e) => sum + (e.transferSize || 0), 0),
			imageCount: entries.filter((e) => e.initiatorType === 'img').length
		};
	});

	// Assert budgets
	expect(lcp, 'LCP exceeds budget').toBeLessThan(budget.lcp);
	expect(resources.totalSize, 'Total size exceeds budget').toBeLessThan(budget.totalSize);
	expect(resources.jsSize, 'JS size exceeds budget').toBeLessThan(budget.jsSize);
	expect(resources.imageCount, 'Too many images').toBeLessThanOrEqual(budget.imageCount);
});
```

### Budget Fixture

```typescript
// fixtures/performance.fixture.ts
type PerformanceBudget = {
	lcp?: number;
	cls?: number;
	ttfb?: number;
	totalSize?: number;
};

type PerformanceFixtures = {
	assertBudget: (budget: PerformanceBudget) => Promise<void>;
};

export const test = base.extend<PerformanceFixtures>({
	assertBudget: async ({ page }, use) => {
		await use(async (budget) => {
			const metrics = await page.evaluate(() => {
				const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
				const resources = performance.getEntriesByType('resource') as PerformanceResourceTiming[];

				return {
					ttfb: nav.responseStart - nav.requestStart,
					totalSize: resources.reduce((sum, r) => sum + (r.transferSize || 0), 0)
				};
			});

			if (budget.ttfb) {
				expect(metrics.ttfb, `TTFB ${metrics.ttfb}ms exceeds budget ${budget.ttfb}ms`).toBeLessThan(
					budget.ttfb
				);
			}

			if (budget.totalSize) {
				expect(metrics.totalSize, `Total size exceeds budget`).toBeLessThan(budget.totalSize);
			}
		});
	}
});
```

## Lighthouse Integration

### Using playwright-lighthouse

```bash
npm install -D playwright-lighthouse lighthouse
```

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

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

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

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

### Lighthouse with Config

```typescript
test('lighthouse with custom config', async ({ page }, testInfo) => {
	await page.goto('/');

	const audit = await playAudit({
		page,
		port: 9222,
		thresholds: {
			performance: 70
		},
		config: {
			extends: 'lighthouse:default',
			settings: {
				onlyCategories: ['performance'],
				throttling: {
					rttMs: 40,
					throughputKbps: 10240,
					cpuSlowdownMultiplier: 1
				}
			}
		}
	});

	// Save report
	const reportPath = testInfo.outputPath('lighthouse-report.html');
	// Save audit.report to file

	// Attach to test report
	await testInfo.attach('lighthouse', {
		body: JSON.stringify(audit.lhr),
		contentType: 'application/json'
	});
});
```

## CI Performance Monitoring

### Track Performance Over Time

```typescript
// reporters/perf-reporter.ts
import { Reporter, TestResult } from '@playwright/test/reporter';

class PerfReporter implements Reporter {
	private metrics: any[] = [];

	onTestEnd(test: any, result: TestResult) {
		const perfAnnotation = test.annotations.find((a: any) => a.type === 'performance');

		if (perfAnnotation) {
			this.metrics.push({
				test: test.title,
				...JSON.parse(perfAnnotation.description),
				timestamp: new Date().toISOString()
			});
		}
	}

	async onEnd() {
		// Send to metrics service
		if (process.env.METRICS_ENDPOINT) {
			await fetch(process.env.METRICS_ENDPOINT, {
				method: 'POST',
				body: JSON.stringify({
					commit: process.env.GITHUB_SHA,
					branch: process.env.GITHUB_REF,
					metrics: this.metrics
				})
			});
		}
	}
}

export default PerfReporter;
```

### Performance Regression Detection

```typescript
test('no performance regression', async ({ page }) => {
	await page.goto('/');

	const metrics = await page.evaluate(() => {
		const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
		return {
			loadTime: nav.loadEventEnd - nav.startTime
		};
	});

	// Compare against baseline (could be from file or API)
	const baseline = 2000; // ms
	const threshold = 1.1; // 10% regression allowed

	expect(
		metrics.loadTime,
		`Load time ${metrics.loadTime}ms is ${((metrics.loadTime / baseline - 1) * 100).toFixed(1)}% slower than baseline`
	).toBeLessThan(baseline * threshold);
});
```

## Anti-Patterns to Avoid

| Anti-Pattern                | Problem                   | Solution                         |
| --------------------------- | ------------------------- | -------------------------------- |
| Testing only once           | Results vary              | Run multiple times, use averages |
| Ignoring network conditions | Unrealistic results       | Test with throttling             |
| No baseline comparison      | Can't detect regressions  | Track metrics over time          |
| Testing in dev mode         | Slow, not production-like | Test production builds           |

## Related References

- **Performance Optimization**: See [performance.md](../infrastructure-ci-cd/performance.md) for test execution performance
- **CI/CD**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for CI integration
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