@assertrx/dino 1.0.0

package/skills/playwright-core/performance-testing.md

@@ -0,0 +1,608 @@
+# Performance Testing
+
+> **When to use**: Measuring and enforcing Web Vitals, resource loading timing, bundle sizes, and runtime performance. Use Playwright to catch performance regressions in CI before users notice them.
+> **Prerequisites**: [core/configuration.md](configuration.md), [core/assertions-and-waiting.md](assertions-and-waiting.md)
+
+## Quick Reference
+
+```typescript
+// Measure Largest Contentful Paint (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 });
+  });
+});
+expect(lcp).toBeLessThan(2500); // Good LCP threshold
+
+// Throttle network to 3G
+const client = await page.context().newCDPSession(page);
+await client.send('Network.emulateNetworkConditions', {
+  offline: false, downloadThroughput: 1.6 * 1024 * 1024 / 8,
+  uploadThroughput: 750 * 1024 / 8, latency: 150,
+});
+```
+
+## Patterns
+
+### Web Vitals Measurement (LCP, CLS, FID/INP)
+
+**Use when**: Enforcing Core Web Vitals thresholds as part of your test suite.
+**Avoid when**: You only need aggregate field data -- use Chrome UX Report or RUM tools instead.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('Core Web Vitals meet thresholds on homepage', async ({ page }) => {
+  // Inject Web Vitals observer before navigation
+  await page.addInitScript(() => {
+    (window as any).__webVitals = { lcp: 0, cls: 0, fid: 0 };
+
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      (window as any).__webVitals.lcp = entries[entries.length - 1].startTime;
+    }).observe({ type: 'largest-contentful-paint', buffered: true });
+
+    new PerformanceObserver((list) => {
+      let clsValue = 0;
+      for (const entry of list.getEntries()) {
+        if (!(entry as any).hadRecentInput) {
+          clsValue += (entry as any).value;
+        }
+      }
+      (window as any).__webVitals.cls = clsValue;
+    }).observe({ type: 'layout-shift', buffered: true });
+
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      (window as any).__webVitals.fid = entries[0]?.processingStart - entries[0]?.startTime;
+    }).observe({ type: 'first-input', buffered: true });
+  });
+
+  await page.goto('/');
+
+  // Trigger a user interaction to measure FID
+  await page.getByRole('button', { name: 'Get started' }).click();
+
+  // Wait for LCP to settle
+  await page.waitForTimeout(1000); // Acceptable here: waiting for metric to finalize
+
+  const vitals = await page.evaluate(() => (window as any).__webVitals);
+
+  expect(vitals.lcp).toBeLessThan(2500);   // Good: <2.5s
+  expect(vitals.cls).toBeLessThan(0.1);    // Good: <0.1
+  // FID may be 0 in automated tests due to no real user delay
+  if (vitals.fid > 0) {
+    expect(vitals.fid).toBeLessThan(100);  // Good: <100ms
+  }
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('LCP meets threshold on homepage', async ({ page }) => {
+  await page.addInitScript(() => {
+    window.__lcp = 0;
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      window.__lcp = entries[entries.length - 1].startTime;
+    }).observe({ type: 'largest-contentful-paint', buffered: true });
+  });
+
+  await page.goto('/');
+  await page.waitForTimeout(1000);
+
+  const lcp = await page.evaluate(() => window.__lcp);
+  expect(lcp).toBeLessThan(2500);
+});
+```
+
+### Performance API Access
+
+**Use when**: Measuring navigation timing, resource loading, or custom performance marks.
+**Avoid when**: Web Vitals alone cover your needs.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('page load timing is within budget', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  const timing = await page.evaluate(() => {
+    const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
+    return {
+      dns: nav.domainLookupEnd - nav.domainLookupStart,
+      tcp: nav.connectEnd - nav.connectStart,
+      ttfb: nav.responseStart - nav.requestStart,
+      domContentLoaded: nav.domContentLoadedEventEnd - nav.startTime,
+      loadComplete: nav.loadEventEnd - nav.startTime,
+      domInteractive: nav.domInteractive - nav.startTime,
+    };
+  });
+
+  expect(timing.ttfb).toBeLessThan(600);           // TTFB under 600ms
+  expect(timing.domContentLoaded).toBeLessThan(2000); // DOM ready under 2s
+  expect(timing.loadComplete).toBeLessThan(5000);     // Full load under 5s
+});
+
+test('critical API calls complete within budget', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  const apiTimings = await page.evaluate(() => {
+    return performance
+      .getEntriesByType('resource')
+      .filter((r) => r.name.includes('/api/'))
+      .map((r) => ({
+        name: r.name.split('/api/')[1],
+        duration: r.duration,
+        size: (r as PerformanceResourceTiming).transferSize,
+      }));
+  });
+
+  for (const api of apiTimings) {
+    expect(api.duration, `API ${api.name} too slow`).toBeLessThan(1000);
+  }
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('page load timing is within budget', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  const timing = await page.evaluate(() => {
+    const nav = performance.getEntriesByType('navigation')[0];
+    return {
+      ttfb: nav.responseStart - nav.requestStart,
+      domContentLoaded: nav.domContentLoadedEventEnd - nav.startTime,
+      loadComplete: nav.loadEventEnd - nav.startTime,
+    };
+  });
+
+  expect(timing.ttfb).toBeLessThan(600);
+  expect(timing.domContentLoaded).toBeLessThan(2000);
+  expect(timing.loadComplete).toBeLessThan(5000);
+});
+```
+
+### Resource Loading and Bundle Size Monitoring
+
+**Use when**: Enforcing bundle size budgets and catching unexpected large resources.
+**Avoid when**: Bundle analysis is handled by webpack-bundle-analyzer or similar build tools.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('JavaScript bundle sizes are within budget', async ({ page }) => {
+  const resourceSizes: { name: string; size: number }[] = [];
+
+  page.on('response', async (response) => {
+    const url = response.url();
+    if (url.endsWith('.js') || url.includes('.js?')) {
+      const headers = response.headers();
+      const size = parseInt(headers['content-length'] || '0');
+      resourceSizes.push({
+        name: url.split('/').pop()!.split('?')[0],
+        size,
+      });
+    }
+  });
+
+  await page.goto('/');
+  await page.waitForLoadState('networkidle');
+
+  // No single JS bundle should exceed 250KB compressed
+  for (const resource of resourceSizes) {
+    expect(
+      resource.size,
+      `Bundle ${resource.name} is ${(resource.size / 1024).toFixed(1)}KB`
+    ).toBeLessThan(250 * 1024);
+  }
+
+  // Total JS payload should not exceed 500KB
+  const totalSize = resourceSizes.reduce((sum, r) => sum + r.size, 0);
+  expect(totalSize, `Total JS: ${(totalSize / 1024).toFixed(1)}KB`).toBeLessThan(500 * 1024);
+});
+
+test('no unexpected large images', async ({ page }) => {
+  const largeImages: { url: string; size: number }[] = [];
+
+  page.on('response', async (response) => {
+    const contentType = response.headers()['content-type'] || '';
+    if (contentType.startsWith('image/')) {
+      const size = parseInt(response.headers()['content-length'] || '0');
+      if (size > 200 * 1024) {
+        largeImages.push({ url: response.url(), size });
+      }
+    }
+  });
+
+  await page.goto('/');
+  await page.waitForLoadState('networkidle');
+
+  expect(
+    largeImages,
+    `Found ${largeImages.length} images over 200KB: ${largeImages.map(i => i.url).join(', ')}`
+  ).toHaveLength(0);
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('JavaScript bundle sizes are within budget', async ({ page }) => {
+  const resourceSizes = [];
+
+  page.on('response', async (response) => {
+    const url = response.url();
+    if (url.endsWith('.js') || url.includes('.js?')) {
+      const size = parseInt(response.headers()['content-length'] || '0');
+      resourceSizes.push({ name: url.split('/').pop().split('?')[0], size });
+    }
+  });
+
+  await page.goto('/');
+  await page.waitForLoadState('networkidle');
+
+  const totalSize = resourceSizes.reduce((sum, r) => sum + r.size, 0);
+  expect(totalSize).toBeLessThan(500 * 1024);
+});
+```
+
+### Slow Network Simulation via CDP
+
+**Use when**: Testing your app's behavior and performance under constrained network conditions.
+**Avoid when**: Playwright's built-in `offline` option is sufficient for your test.
+
+**TypeScript**
+```typescript
+import { test, expect, type Page } from '@playwright/test';
+
+// Network presets
+const NETWORK_PRESETS = {
+  slow3G: {
+    offline: false,
+    downloadThroughput: (500 * 1024) / 8,  // 500 Kbps
+    uploadThroughput: (500 * 1024) / 8,
+    latency: 400,
+  },
+  fast3G: {
+    offline: false,
+    downloadThroughput: (1.6 * 1024 * 1024) / 8,  // 1.6 Mbps
+    uploadThroughput: (750 * 1024) / 8,
+    latency: 150,
+  },
+  regularLTE: {
+    offline: false,
+    downloadThroughput: (4 * 1024 * 1024) / 8,  // 4 Mbps
+    uploadThroughput: (3 * 1024 * 1024) / 8,
+    latency: 20,
+  },
+} as const;
+
+async function throttleNetwork(page: Page, preset: keyof typeof NETWORK_PRESETS) {
+  const client = await page.context().newCDPSession(page);
+  await client.send('Network.enable');
+  await client.send('Network.emulateNetworkConditions', NETWORK_PRESETS[preset]);
+  return client;
+}
+
+test('app shows loading states on slow network', async ({ page }) => {
+  await throttleNetwork(page, 'slow3G');
+
+  await page.goto('/dashboard');
+
+  // Loading skeleton should appear while content loads slowly
+  await expect(page.getByTestId('loading-skeleton')).toBeVisible();
+
+  // Content should eventually load
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible({ timeout: 30000 });
+});
+
+test('images lazy-load on slow connection', async ({ page }) => {
+  await throttleNetwork(page, 'fast3G');
+  await page.goto('/gallery');
+
+  // Only above-the-fold images should be loaded initially
+  const loadedImages = await page.evaluate(() =>
+    Array.from(document.querySelectorAll('img'))
+      .filter((img) => img.complete && img.naturalWidth > 0).length
+  );
+
+  // Scroll to trigger lazy loading
+  await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+  await page.waitForTimeout(2000);
+
+  const allLoadedImages = await page.evaluate(() =>
+    Array.from(document.querySelectorAll('img'))
+      .filter((img) => img.complete && img.naturalWidth > 0).length
+  );
+
+  expect(allLoadedImages).toBeGreaterThan(loadedImages);
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+async function throttleNetwork(page, preset) {
+  const presets = {
+    slow3G: { offline: false, downloadThroughput: (500 * 1024) / 8, uploadThroughput: (500 * 1024) / 8, latency: 400 },
+    fast3G: { offline: false, downloadThroughput: (1.6 * 1024 * 1024) / 8, uploadThroughput: (750 * 1024) / 8, latency: 150 },
+  };
+  const client = await page.context().newCDPSession(page);
+  await client.send('Network.enable');
+  await client.send('Network.emulateNetworkConditions', presets[preset]);
+  return client;
+}
+
+test('app shows loading states on slow network', async ({ page }) => {
+  await throttleNetwork(page, 'slow3G');
+  await page.goto('/dashboard');
+
+  await expect(page.getByTestId('loading-skeleton')).toBeVisible();
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible({ timeout: 30000 });
+});
+```
+
+### CPU Throttling via CDP
+
+**Use when**: Simulating low-powered devices to test animation smoothness, interaction responsiveness, or heavy computation.
+**Avoid when**: Network performance is the bottleneck, not CPU.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('animations remain smooth under CPU throttling', async ({ page }) => {
+  const client = await page.context().newCDPSession(page);
+
+  // 4x slowdown simulates a mid-tier mobile device
+  await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });
+
+  await page.goto('/animations-demo');
+  await page.getByRole('button', { name: 'Start animation' }).click();
+
+  // Measure frame rate during animation
+  const fps = await page.evaluate(() => {
+    return new Promise<number>((resolve) => {
+      let frames = 0;
+      const start = performance.now();
+      function count() {
+        frames++;
+        if (performance.now() - start < 1000) {
+          requestAnimationFrame(count);
+        } else {
+          resolve(frames);
+        }
+      }
+      requestAnimationFrame(count);
+    });
+  });
+
+  // Should maintain at least 30fps even on throttled CPU
+  expect(fps).toBeGreaterThan(30);
+
+  // Reset throttling
+  await client.send('Emulation.setCPUThrottlingRate', { rate: 1 });
+});
+
+test('search input responds quickly under CPU constraint', async ({ page }) => {
+  const client = await page.context().newCDPSession(page);
+  await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });
+
+  await page.goto('/search');
+
+  const start = Date.now();
+  await page.getByRole('textbox', { name: 'Search' }).fill('test query');
+  await expect(page.getByRole('listbox')).toBeVisible();
+  const elapsed = Date.now() - start;
+
+  // Autocomplete should appear within 500ms even under 4x CPU throttle
+  expect(elapsed).toBeLessThan(500);
+
+  await client.send('Emulation.setCPUThrottlingRate', { rate: 1 });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('animations remain smooth under CPU throttling', async ({ page }) => {
+  const client = await page.context().newCDPSession(page);
+  await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });
+
+  await page.goto('/animations-demo');
+  await page.getByRole('button', { name: 'Start animation' }).click();
+
+  const fps = await page.evaluate(() => {
+    return new Promise((resolve) => {
+      let frames = 0;
+      const start = performance.now();
+      function count() {
+        frames++;
+        if (performance.now() - start < 1000) {
+          requestAnimationFrame(count);
+        } else {
+          resolve(frames);
+        }
+      }
+      requestAnimationFrame(count);
+    });
+  });
+
+  expect(fps).toBeGreaterThan(30);
+  await client.send('Emulation.setCPUThrottlingRate', { rate: 1 });
+});
+```
+
+### Performance Budgets in CI
+
+**Use when**: Enforcing hard performance limits that block merges when thresholds are exceeded.
+**Avoid when**: Performance varies too much in CI environment -- use trend-based monitoring instead.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+// Define budgets in a shared config
+const PERFORMANCE_BUDGETS = {
+  homepage: {
+    lcp: 2500,
+    cls: 0.1,
+    ttfb: 600,
+    totalJsSize: 500 * 1024,
+    totalImageSize: 1000 * 1024,
+    domContentLoaded: 2000,
+  },
+  dashboard: {
+    lcp: 3000,
+    cls: 0.1,
+    ttfb: 800,
+    totalJsSize: 750 * 1024,
+    totalImageSize: 500 * 1024,
+    domContentLoaded: 3000,
+  },
+} as const;
+
+test.describe('performance budgets', () => {
+  test('homepage meets performance budget', async ({ page }) => {
+    const budget = PERFORMANCE_BUDGETS.homepage;
+    let totalJsSize = 0;
+
+    page.on('response', (response) => {
+      if (response.url().endsWith('.js') || response.url().includes('.js?')) {
+        totalJsSize += parseInt(response.headers()['content-length'] || '0');
+      }
+    });
+
+    // Inject LCP observer
+    await page.addInitScript(() => {
+      (window as any).__lcp = 0;
+      new PerformanceObserver((list) => {
+        const entries = list.getEntries();
+        (window as any).__lcp = entries[entries.length - 1].startTime;
+      }).observe({ type: 'largest-contentful-paint', buffered: true });
+    });
+
+    await page.goto('/');
+    await page.waitForLoadState('networkidle');
+
+    const metrics = await page.evaluate(() => {
+      const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
+      return {
+        lcp: (window as any).__lcp,
+        ttfb: nav.responseStart - nav.requestStart,
+        domContentLoaded: nav.domContentLoadedEventEnd - nav.startTime,
+      };
+    });
+
+    expect(metrics.lcp, 'LCP budget exceeded').toBeLessThan(budget.lcp);
+    expect(metrics.ttfb, 'TTFB budget exceeded').toBeLessThan(budget.ttfb);
+    expect(metrics.domContentLoaded, 'DOMContentLoaded budget exceeded').toBeLessThan(budget.domContentLoaded);
+    expect(totalJsSize, 'JS bundle budget exceeded').toBeLessThan(budget.totalJsSize);
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+const PERFORMANCE_BUDGETS = {
+  homepage: { lcp: 2500, ttfb: 600, totalJsSize: 500 * 1024, domContentLoaded: 2000 },
+};
+
+test('homepage meets performance budget', async ({ page }) => {
+  const budget = PERFORMANCE_BUDGETS.homepage;
+  let totalJsSize = 0;
+
+  page.on('response', (response) => {
+    if (response.url().endsWith('.js')) {
+      totalJsSize += parseInt(response.headers()['content-length'] || '0');
+    }
+  });
+
+  await page.addInitScript(() => {
+    window.__lcp = 0;
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      window.__lcp = entries[entries.length - 1].startTime;
+    }).observe({ type: 'largest-contentful-paint', buffered: true });
+  });
+
+  await page.goto('/');
+  await page.waitForLoadState('networkidle');
+
+  const metrics = await page.evaluate(() => {
+    const nav = performance.getEntriesByType('navigation')[0];
+    return {
+      lcp: window.__lcp,
+      ttfb: nav.responseStart - nav.requestStart,
+      domContentLoaded: nav.domContentLoadedEventEnd - nav.startTime,
+    };
+  });
+
+  expect(metrics.lcp).toBeLessThan(budget.lcp);
+  expect(metrics.ttfb).toBeLessThan(budget.ttfb);
+  expect(totalJsSize).toBeLessThan(budget.totalJsSize);
+});
+```
+
+## Decision Guide
+
+| What to Measure | Technique | When to Use |
+|---|---|---|
+| LCP, CLS, FID/INP | `PerformanceObserver` via `addInitScript` | Core Web Vitals regression testing |
+| TTFB, DOM load times | `performance.getEntriesByType('navigation')` | Server response and page load budgets |
+| API call durations | `performance.getEntriesByType('resource')` | Backend performance regression |
+| JS/CSS bundle sizes | `page.on('response')` + `content-length` header | Bundle size budgets in CI |
+| Slow network behavior | CDP `Network.emulateNetworkConditions` | Testing loading states, lazy loading, offline |
+| Low-end device behavior | CDP `Emulation.setCPUThrottlingRate` | Animation smoothness, interaction latency |
+| Full Lighthouse audit | `@playwright/test` + Lighthouse CLI via CDP port | Comprehensive performance scoring |
+| Runtime performance | `page.evaluate` + `requestAnimationFrame` FPS count | Animation and rendering performance |
+
+## Anti-Patterns
+
+| Don't Do This | Problem | Do This Instead |
+|---|---|---|
+| Setting absolute thresholds based on local dev machine | CI machines are slower; thresholds flap | Calibrate budgets on CI hardware or use relative comparisons |
+| Using `networkidle` as a performance measurement point | `networkidle` includes analytics, ads, non-critical resources | Measure specific metrics (LCP, TTFB) directly via Performance API |
+| Running performance tests with `--headed` in CI | Headed mode adds GPU overhead and inconsistency | Use headless mode for consistent measurement |
+| Measuring FID in automated tests | No real user input delay exists in automation | Measure INP or use Lighthouse for FID estimates |
+| Running perf tests in parallel with other CI jobs | CPU contention skews results | Run performance tests in isolation or on dedicated CI runners |
+| Ignoring `content-length` being `0` | Compressed responses may not report size | Use `response.body().length` for actual transfer size |
+| Only testing happy-path performance | Slow error paths degrade user experience | Test performance of error states, empty states, and large datasets |
+| Hard-failing CI on minor regressions | Causes merge friction for non-performance changes | Use warning thresholds with mandatory review, fail only on large regressions |
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| LCP is 0 or unrealistically low | Observer did not fire; page has no qualifying LCP element | Verify the page has images or large text blocks; add `buffered: true` to observer |
+| CLS is always 0 | Layout shifts occur before observer is registered | Use `addInitScript` to inject observer before page load |
+| CDP session errors with Firefox/WebKit | CDP is Chromium-only | Guard CDP code: `test.skip(browserName !== 'chromium')` |
+| Performance numbers vary wildly between runs | CI machine load fluctuates | Run performance tests multiple times and take the median; use dedicated runners |
+| `content-length` header is missing | Server uses chunked transfer encoding | Use `response.body()` then check `Buffer.byteLength()` |
+| Network throttling has no effect | CDP session created on wrong page | Create the CDP session from the page's context, not a separate browser |
+| Bundle size test passes but app feels slow | Measuring compressed size, not parsed size | Also check `performance.getEntriesByType('resource')` for `decodedBodySize` |
+
+## Related
+
+- [core/configuration.md](configuration.md) -- timeout and retry settings for performance-sensitive tests
+- [core/network-mocking.md](network-mocking.md) -- mocking slow APIs for performance boundary testing
+- [core/browser-apis.md](browser-apis.md) -- using browser APIs for measurement
+- [ci/ci-github-actions.md](../ci/ci-github-actions.md) -- CI configuration for performance budgets
+- [core/clock-and-time-mocking.md](clock-and-time-mocking.md) -- time-related performance testing