Browser Required

Perform browser-based performance audits

Static analysis alone cannot simulate the complex rendering, script execution, and layout processes of modern web browsers, which is essential for capturing real-world performance.

Quick Reference

• Use real browser engines to capture runtime metrics (LCP, CLS, INP)
• Synthetic tests in full browsers reveal execution bottlenecks
• Verify performance across different device and connection simulations

Check

Ensure that performance audits are conducted in an environment that executes JavaScript and renders the page (e.g., Lighthouse, Puppeteer).

Fix

Integrate browser-based testing tools like Lighthouse or WebPageTest into the development workflow and CI/CD pipeline.

Explain

Explain the limitations of static analysis for performance and why a full browser environment is necessary.

Code Review

Review the routes, assets, and loading behavior that affect Perform browser-based performance audits. Flag exact files, requests, or rendering steps that add unnecessary network, CPU, or layout cost, and describe the measurement method used to confirm the issue.

---

For full implementation details, code examples, and framework-specific guidance, see references/rule.md.

Rule page: https://frontendchecklist.io/en/rules/performance/browser-required

Perform browser-based performance audits

Conduct performance audits in a full browser environment to capture accurate runtime metrics and layout shifts.

Priority: medium · Difficulty: intermediate · Time: 10 min

--- While static analysis can catch some performance issues, many critical metrics can only be measured during page execution in a real web browser.

Code Examples

#

Using Lighthouse CLI for Browser Audits

Lighthouse runs a full Chrome instance to audit your page.

# Install Lighthouse
npm install -g lighthouse

# Run an audit on a URL
lighthouse https://example.com --view --chrome-flags="--headless"

Scripting Browser Audits with Puppeteer

You can automate browser-based checks using Puppeteer or Playwright.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  // Throttling network and CPU
  const client = await page.target().createCDPSession();
  await client.send('Network.emulateNetworkConditions', {
    offline: false,
    latency: 100,
    downloadThroughput: 750 * 1024 / 8, // Fast 3G
    uploadThroughput: 250 * 1024 / 8,
  });

  await page.goto('https://example.com');
  const metrics = await page.metrics();
  console.log('Browser Metrics:', metrics);

  await browser.close();
})();

Why It Matters

• Accurate Metrics: Core Web Vitals like Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS) require a rendering engine to be calculated.
• JavaScript Execution: Only a browser can measure the impact of JavaScript on main-thread blocking and interaction latency.
• Real-World Simulation: Browsers allow for throttling CPU and network speeds to simulate real-world user conditions.
• Visual Feedback: Browser-based tools provide screenshots and videos of the loading process, helping to identify "jank" and layout shifts.

Best Practices

Use a real browser pass alongside Lighthouse so layout shifts, main-thread work, and interaction delays are measured in an environment that actually executes the page.

✅ Automate in CI: Run browser-based audits on every pull request to catch regressions early. ✅ Throttling: Always test with network and CPU throttling to see how your site performs for users on slower devices. ✅ Use Multiple Regions: Audit from different geographic locations to understand the impact of latency. ✅ Mobile-First: Prioritize audits using mobile device emulation.

❌ Don't Rely Solely on Dev Machines: Your high-end developer laptop doesn't reflect the experience of a user on a budget smartphone. ❌ Avoid Unthrottled Tests: Testing on a gigabit connection will hide most performance bottlenecks.

Tools & Validation

• Lighthouse: The industry standard for browser-based auditing.
• WebPageTest: Provides deep waterfall analysis and multi-location testing.
• PageSpeed Insights: Combines lab data from Lighthouse with real-world field data.
• Playwright: Modern browser automation for custom performance scripts.

Standards

• Use web.dev: Learn Performance as the standard for measuring the final production behavior, not just local synthetic output.
• Use Chrome Developers: Lighthouse overview as the standard for measuring the final production behavior, not just local synthetic output.

Verification

Automated Checks

• Measure the affected page or flow in Lighthouse, PageSpeed Insights, or DevTools and confirm the targeted metric improves.
• Inspect the network waterfall or performance timeline to confirm the intended resource or execution change actually took effect.

Manual Checks

• Verify the change on a throttled mobile profile, not just local desktop.
• If this rule maps to a budget or Web Vital, confirm the page now stays within that threshold.