frontend-performance-testing

name	frontend-performance-testing
description	Guides browser-based performance testing for HTML, CSS, JavaScript, and UI interactions. Use when measuring frontend performance, adding Playwright perf tests, checking regressions, profiling load/render/interaction cost, or discussing performance budgets.

Frontend Performance Testing

Use real browsers for performance checks. In this repo, prefer Playwright because playwright.config.ts already boots bun server.ts and runs against Chromium.

What To Measure

• Load readiness: time to fixture boot, first usable UI, and custom element definitions.
• Interaction latency: click, keyboard, pointer drag, slider movement, picker open/close.
• Render cost: layout, style recalculation, paint, animation frames, and DOM update loops.
• Bundle/build changes: output size and runtime behavior after bun build.
• Regressions under scale: repeated components, large option lists, nested controls, and overlay stacks.

Test Pattern

1. Mount the smallest deterministic fixture that reproduces the performance risk.
2. Warm up once before measuring.
3. Use browser APIs inside page.evaluate: performance.now(), PerformanceObserver, requestAnimationFrame, getBoundingClientRect, and document.fonts.ready when relevant.
4. Repeat enough times to reduce noise; assert on median or bounded worst case, not one sample.
5. Keep budgets local and named after the scenario, not global magic numbers.

Playwright Guidance

• Put stable performance checks near tests/figui unless they need a separate fixture.
• Fail on page errors and unexpected console errors before trusting timing data.
• Use test.slow() for intentionally heavier regression scenarios.
• Capture traces only for failing or investigative runs; do not turn every perf test into a trace artifact.
• Prefer expect.poll for readiness, then measure a synchronous scenario.

Budget Rules

• Budgets should catch meaningful regressions without flaking on normal machine variance.
• Use relative comparisons when possible: changed implementation vs baseline path in the same page.
• Avoid hard sub-millisecond thresholds.
• Document what user-facing lag the budget protects.

Avoid

• jsdom performance conclusions.
• Network-dependent timing assertions.
• Screenshot diffs as a proxy for performance.
• Microbenchmarks that skip the actual DOM/CSS/component path.