ever-co/ever-works / .agents/skills/playwright-best-practices
playwright-best-practices
VerifiedUse 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.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |