Performance Testing

// test/performance-basic.spec.ts
// => Uses Performance API for timing measurements
// => Browser built-in, no external dependencies

import { test, expect } from "@playwright/test";
// => Playwright test framework
// => expect for assertions

test("measure page load performance", async ({ page }) => {
  // => Navigates to page and collects timing data
  // => Performance entries captured via browser API

  await page.goto("https://example.com");
  // => Loads target page
  // => Waits for load event by default

  const performanceData = await page.evaluate(() => {
    // => Executes in browser context
    // => Accesses window.performance object
    // => Returns timing data to Node.js context

    const navigation = performance.getEntriesByType("navigation")[0] as PerformanceNavigationTiming;
    // => Gets navigation timing entry
    // => Cast to specific type for TypeScript
    // => Only one navigation entry per page load

    const paint = performance.getEntriesByType("paint");
    // => Gets paint timing entries
    // => Returns array of paint events
    // => Includes first-paint, first-contentful-paint

    return {
      // => Returns object with calculated metrics
      // => All values in milliseconds

      domContentLoaded: navigation.domContentLoadedEventEnd - navigation.domContentLoadedEventStart,
      // => Time for DOM ready event
      // => Measures HTML parsing completion

      loadComplete: navigation.loadEventEnd - navigation.loadEventStart,
      // => Time for full page load
      // => Includes all resources (images, scripts)

      firstPaint: paint.find((entry) => entry.name === "first-paint")?.startTime ?? 0,
      // => First pixel painted on screen
      // => Visual feedback starts

      firstContentfulPaint: paint.find((entry) => entry.name === "first-contentful-paint")?.startTime ?? 0,
      // => First content element painted
      // => User sees meaningful content

      domInteractive: navigation.domInteractive,
      // => DOM ready for interaction
      // => Scripts can manipulate DOM

      transferSize: navigation.transferSize,
      // => Bytes transferred over network
      // => Includes headers and body
      // => 0 if from cache
    };
  });
  // => Returns performance metrics to test context

  console.log("Performance Metrics:", performanceData);
  // => Logs metrics for manual inspection
  // => Format: { domContentLoaded: 150, loadComplete: 500, ... }

  expect(performanceData.firstContentfulPaint).toBeLessThan(2500);
  // => Asserts FCP under 2.5s
  // => Core Web Vitals "Good" threshold
  // => Test fails if exceeded

  expect(performanceData.loadComplete).toBeLessThan(5000);
  // => Asserts page load under 5s
  // => Reasonable performance expectation
});

npm install --save-dev @playwright/test playwright-lighthouse

// test/performance-lighthouse.spec.ts
// => Production-grade performance testing
// => Lighthouse CI integration for Core Web Vitals

import { test, expect } from "@playwright/test";
import { playAudit } from "playwright-lighthouse";
import lighthouseDesktopConfig from "lighthouse/lighthouse-core/config/desktop-config.js";
// => Lighthouse desktop configuration preset
// => Optimized desktop thresholds

test.describe("Production Performance Audits", () => {
  // => Groups performance tests
  // => All tests share same audit requirements

  test.use({
    // => Configures test context
    // => Applied to all tests in describe block

    launchOptions: {
      args: ["--remote-debugging-port=9222"],
      // => Enables Chrome DevTools Protocol
      // => Required for Lighthouse connection
      // => Port 9222 is standard debugging port
    },
  });

  test("Desktop: Core Web Vitals compliance", async ({ page, context }) => {
    // => Tests desktop performance profile
    // => Verifies Core Web Vitals thresholds

    await page.goto("https://example.com");
    // => Navigates to target page
    // => Must complete before audit starts

    await page.waitForLoadState("networkidle");
    // => Waits for network to settle
    // => Ensures all initial resources loaded
    // => Prevents measuring partial page state

    await playAudit({
      // => Runs Lighthouse audit
      // => Returns performance metrics and scores

      page,
      // => Playwright page instance
      // => Lighthouse instruments this page

      port: 9222,
      // => Chrome debugging port
      // => Matches launchOptions configuration

      config: lighthouseDesktopConfig,
      // => Uses desktop performance profile
      // => Desktop-specific thresholds and emulation

      thresholds: {
        // => Pass/fail criteria for CI/CD
        // => Test fails if any threshold breached

        performance: 90,
        // => Overall performance score
        // => 90+ is "Good" (green)
        // => Composite of all metrics weighted

        "largest-contentful-paint": 2500,
        // => LCP: Main content visible
        // => 2.5s is "Good" threshold
        // => 4.0s is "Needs Improvement"

        "first-contentful-paint": 1800,
        // => FCP: First content visible
        // => 1.8s is "Good" threshold

        "cumulative-layout-shift": 0.1,
        // => CLS: Visual stability
        // => 0.1 is "Good" threshold
        // => Measures unexpected layout shifts

        "total-blocking-time": 300,
        // => TBT: Interactivity metric
        // => 300ms is "Good" threshold
        // => FID proxy for lab testing

        "speed-index": 3400,
        // => Speed Index: Visual completeness
        // => 3.4s is "Good" threshold
        // => Measures how quickly content painted
      },
    });
    // => Throws error if any threshold exceeded
    // => Test fails with detailed report
  });

  test("Mobile: 3G Network Performance", async ({ page }) => {
    // => Tests mobile + slow network
    // => Simulates worst-case scenario

    await page.goto("https://example.com");
    await page.waitForLoadState("networkidle");

    await playAudit({
      page,
      port: 9222,

      config: {
        // => Custom mobile configuration
        // => Overrides default desktop settings

        extends: "lighthouse:default",
        // => Starts from default Lighthouse config
        // => Adds mobile-specific settings

        settings: {
          // => Lighthouse execution settings
          // => Controls emulation and throttling

          formFactor: "mobile",
          // => Emulates mobile device
          // => Uses mobile viewport and user agent

          throttling: {
            // => Network and CPU throttling
            // => Simulates slow 3G connection

            rttMs: 150,
            // => Round-trip time: 150ms
            // => Typical slow 3G latency

            throughputKbps: 1.6 * 1024,
            // => Download: 1.6 Mbps
            // => Slow 3G bandwidth

            requestLatencyMs: 150,
            // => Additional request latency
            // => Simulates mobile network delays

            downloadThroughputKbps: 1.6 * 1024,
            uploadThroughputKbps: 750,
            // => Upload: 750 Kbps
            // => Asymmetric (typical mobile)

            cpuSlowdownMultiplier: 4,
            // => CPU throttling: 4x slowdown
            // => Simulates mid-tier mobile device
          },

          screenEmulation: {
            // => Mobile screen dimensions
            // => Affects layout and rendering

            mobile: true,
            width: 375,
            height: 667,
            // => iPhone SE dimensions
            // => Common small mobile screen

            deviceScaleFactor: 2,
            // => Retina display: 2x pixel density
            disabled: false,
          },
        },
      },

      thresholds: {
        // => Mobile thresholds more lenient
        // => Accounts for device constraints

        performance: 70,
        // => 70+ acceptable for mobile
        // => Lower than desktop (90+)

        "largest-contentful-paint": 4000,
        // => 4s LCP acceptable on 3G
        // => Still below "Poor" threshold (4.5s)

        "first-contentful-paint": 3000,
        // => 3s FCP acceptable on 3G

        "total-blocking-time": 600,
        // => 600ms TBT acceptable on mobile
        // => Higher than desktop (300ms)
      },
    });
  });
});

// lighthouse-config.js
// => Performance budget configuration
// => Enforces resource limits in CI/CD

export default {
  // => Lighthouse configuration object
  // => Extends default lighthouse settings

  extends: "lighthouse:default",

  settings: {
    // => Budget configuration
    // => Defines resource limits per page

    budgets: [
      {
        // => Resource budget for all pages
        // => Applied to every audit

        resourceSizes: [
          // => Limits on resource types by size
          // => Prevents bloat from accumulating

          {
            resourceType: "total",
            budget: 300,
            // => Total page size: 300KB
            // => All resources combined
            // => Good baseline for fast load
          },

          {
            resourceType: "script",
            budget: 150,
            // => JavaScript: 150KB
            // => Prevents JS bloat
            // => Parse/compile time increases with size
          },

          {
            resourceType: "image",
            budget: 100,
            // => Images: 100KB
            // => Use compression and lazy loading
          },

          {
            resourceType: "stylesheet",
            budget: 30,
            // => CSS: 30KB
            // => Critical CSS inlined
            // => Non-critical deferred
          },

          {
            resourceType: "font",
            budget: 20,
            // => Fonts: 20KB
            // => Use font-display: swap
            // => Limit font variants
          },
        ],

        resourceCounts: [
          // => Limits on number of resources
          // => Too many resources = HTTP overhead

          {
            resourceType: "third-party",
            budget: 10,
            // => Third-party scripts: max 10
            // => Analytics, ads, tracking
            // => Each adds latency and risk
          },

          {
            resourceType: "total",
            budget: 50,
            // => Total resources: max 50
            // => Prevents waterfall explosion
          },
        ],

        timings: [
          // => Time-based performance budgets
          // => Core Web Vitals thresholds

          {
            metric: "first-contentful-paint",
            budget: 2000,
            // => FCP: 2s budget
            // => User sees content quickly
          },

          {
            metric: "largest-contentful-paint",
            budget: 2500,
            // => LCP: 2.5s budget
            // => Main content visible
          },

          {
            metric: "cumulative-layout-shift",
            budget: 0.1,
            // => CLS: 0.1 budget
            // => Visual stability
          },

          {
            metric: "total-blocking-time",
            budget: 300,
            // => TBT: 300ms budget
            // => Interactivity metric
          },

          {
            metric: "interactive",
            budget: 3500,
            // => TTI: 3.5s budget
            // => Page fully interactive
          },
        ],
      },
    ],
  },
};

// test/performance-budget.spec.ts
// => Performance budget enforcement
// => CI/CD gate for resource limits

import { test } from "@playwright/test";
import { playAudit } from "playwright-lighthouse";
import budgetConfig from "../lighthouse-config.js";
// => Imports custom budget configuration
// => Shared across all budget tests

test("Enforce performance budgets", async ({ page }) => {
  // => Tests against budget limits
  // => Fails if any budget exceeded

  test.use({
    launchOptions: {
      args: ["--remote-debugging-port=9222"],
    },
  });

  await page.goto("https://example.com");
  await page.waitForLoadState("networkidle");

  await playAudit({
    page,
    port: 9222,
    config: budgetConfig,
    // => Uses budget configuration
    // => Lighthouse validates budgets automatically
    // => Build fails on budget violations

    thresholds: {
      performance: 85,
      // => Overall score threshold
      // => Independent of budget checks
    },
  });
  // => Lighthouse reports budget violations
  // => Test fails with details on exceeded budgets
});

// test/resource-timing.spec.ts
// => Resource-level performance analysis
// => Identifies slow resources and bottlenecks

import { test, expect } from "@playwright/test";

interface ResourceTiming {
  name: string;
  duration: number;
  transferSize: number;
  type: string;
  cached: boolean;
}

test("Analyze resource loading performance", async ({ page }) => {
  // => Collects resource timing data
  // => Identifies performance bottlenecks

  await page.goto("https://example.com");
  await page.waitForLoadState("networkidle");
  // => Ensures all resources loaded
  // => Resource timing complete

  const resourceTimings = await page.evaluate(() => {
    // => Executes in browser context
    // => Accesses Performance API

    const resources = performance.getEntriesByType("resource") as PerformanceResourceTiming[];
    // => Gets all resource timing entries
    // => Includes scripts, styles, images, fonts, XHR

    return resources.map((resource) => ({
      // => Transforms to structured data
      // => Extracts key metrics for analysis

      name: resource.name,
      // => Resource URL
      // => Identifies specific resource

      duration: resource.duration,
      // => Total load time (ms)
      // => From start to response complete

      transferSize: resource.transferSize,
      // => Bytes transferred over network
      // => 0 if from cache or cross-origin

      type: resource.initiatorType,
      // => Resource type: script, css, img, fetch, etc.
      // => Categorizes resources

      cached: resource.transferSize === 0,
      // => True if from cache
      // => Cache hits have 0 transfer size
    }));
  });

  // => Group resources by type for analysis
  // => Calculate aggregate metrics per type

  const byType = resourceTimings.reduce(
    (acc, resource) => {
      // => Groups resources by type
      // => Enables type-level analysis

      if (!acc[resource.type]) {
        acc[resource.type] = [];
        // => Initialize type array if first resource of type
      }
      acc[resource.type].push(resource);
      return acc;
    },
    {} as Record<string, ResourceTiming[]>,
  );

  // => Analyze each resource type
  // => Identify performance issues

  for (const [type, resources] of Object.entries(byType)) {
    // => Iterates over resource types
    // => Performs type-specific analysis

    const totalSize = resources.reduce((sum, r) => sum + r.transferSize, 0);
    // => Sum of transfer sizes for type
    // => Identifies bandwidth-heavy types

    const totalDuration = resources.reduce((sum, r) => sum + r.duration, 0);
    // => Sum of load durations for type
    // => Identifies time-consuming types

    const cacheHitRate = resources.filter((r) => r.cached).length / resources.length;
    // => Percentage cached
    // => Measures cache effectiveness

    console.log(`${type}:`, {
      count: resources.length,
      totalSize: `${(totalSize / 1024).toFixed(2)} KB`,
      totalDuration: `${totalDuration.toFixed(2)} ms`,
      cacheHitRate: `${(cacheHitRate * 100).toFixed(1)}%`,
    });
    // => Logs type-level metrics
    // => Format: script: { count: 12, totalSize: "150.50 KB", ... }
  }

  // => Find slowest resources
  // => Candidates for optimization

  const slowResources = resourceTimings
    .filter((r) => r.duration > 1000)
    // => Resources taking over 1s
    // => Significant performance impact
    .sort((a, b) => b.duration - a.duration);
  // => Sorted slowest first
  // => Prioritizes optimization targets

  if (slowResources.length > 0) {
    console.warn(
      "Slow resources detected:",
      slowResources.map((r) => ({
        url: r.name,
        duration: `${r.duration.toFixed(2)} ms`,
      })),
    );
    // => Warns about slow resources
    // => Requires investigation
  }

  // => Validate resource count limits
  // => Prevents resource explosion

  expect(resourceTimings.length).toBeLessThan(50);
  // => Max 50 total resources
  // => Too many resources = connection overhead

  const scripts = resourceTimings.filter((r) => r.type === "script");
  expect(scripts.length).toBeLessThan(15);
  // => Max 15 scripts
  // => Prevents JavaScript bloat

  const thirdParty = resourceTimings.filter((r) => !r.name.includes("example.com"));
  expect(thirdParty.length).toBeLessThan(10);
  // => Max 10 third-party resources
  // => Limits external dependencies
  // => Reduces privacy and performance risks
});

// test/network-throttling.spec.ts
// => Network condition testing
// => Validates performance across connection types

import { test, expect, chromium } from "@playwright/test";

// => Network throttling profiles
// => Simulates real-world connection speeds

const networkProfiles = {
  // => Collection of network conditions
  // => Based on Chrome DevTools presets

  "Fast 3G": {
    // => Fast 3G mobile connection
    // => Common in developing countries

    downloadThroughput: (1.6 * 1024 * 1024) / 8,
    // => 1.6 Mbps download
    // => Converted to bytes per second (÷8)

    uploadThroughput: (750 * 1024) / 8,
    // => 750 Kbps upload
    // => Asymmetric (typical mobile)

    latency: 150,
    // => 150ms round-trip latency
    // => Includes radio latency
  },

  "Slow 3G": {
    // => Slow 3G mobile connection
    // => Worst-case mobile scenario

    downloadThroughput: (400 * 1024) / 8,
    // => 400 Kbps download
    // => Very slow by modern standards

    uploadThroughput: (400 * 1024) / 8,
    // => 400 Kbps upload
    // => Symmetric for slow 3G

    latency: 400,
    // => 400ms latency
    // => Noticeable delay on interactions
  },

  "4G": {
    // => 4G LTE connection
    // => Modern mobile baseline

    downloadThroughput: (4 * 1024 * 1024) / 8,
    // => 4 Mbps download
    // => Typical 4G speed

    uploadThroughput: (3 * 1024 * 1024) / 8,
    // => 3 Mbps upload

    latency: 50,
    // => 50ms latency
    // => Low latency for mobile
  },

  Cable: {
    // => Home broadband connection
    // => Desktop baseline

    downloadThroughput: (5 * 1024 * 1024) / 8,
    // => 5 Mbps download
    // => Conservative broadband estimate

    uploadThroughput: (1 * 1024 * 1024) / 8,
    // => 1 Mbps upload
    // => Asymmetric (typical cable)

    latency: 28,
    // => 28ms latency
    // => Typical broadband latency
  },
};

for (const [profileName, profile] of Object.entries(networkProfiles)) {
  // => Test each network profile
  // => Ensures acceptable performance across conditions

  test(`Performance on ${profileName}`, async () => {
    // => Parameterized test for network profile
    // => Test name includes profile for clarity

    const browser = await chromium.launch({
      args: ["--remote-debugging-port=9222"],
    });
    // => Launches Chrome with debugging
    // => Required for CDP network emulation

    const context = await browser.newContext();
    // => Creates browser context
    // => Isolated session for test

    const client = await context.newCDPSession(await context.newPage());
    // => Creates Chrome DevTools Protocol session
    // => Enables low-level browser control

    await client.send("Network.enable");
    // => Enables network domain
    // => Required for emulation

    await client.send("Network.emulateNetworkConditions", {
      // => Applies network throttling
      // => Simulates specified connection

      offline: false,
      // => Online mode
      // => offline: true simulates no connection

      downloadThroughput: profile.downloadThroughput,
      uploadThroughput: profile.uploadThroughput,
      latency: profile.latency,
      // => Applies profile settings
      // => Affects all network requests
    });

    const page = await context.newPage();
    // => Creates page in throttled context
    // => All requests use emulated network

    const startTime = Date.now();
    // => Records navigation start time
    // => For total load measurement

    await page.goto("https://example.com");
    await page.waitForLoadState("networkidle");
    // => Waits for network idle
    // => Ensures complete page load under throttling

    const loadTime = Date.now() - startTime;
    // => Calculates total load time
    // => Includes throttling effects

    console.log(`${profileName} load time: ${loadTime}ms`);
    // => Logs load time for profile
    // => Compare across profiles

    // => Profile-specific assertions
    // => Thresholds based on connection quality

    if (profileName === "Slow 3G") {
      expect(loadTime).toBeLessThan(15000);
      // => 15s max on Slow 3G
      // => Worst-case tolerance
    } else if (profileName === "Fast 3G") {
      expect(loadTime).toBeLessThan(8000);
      // => 8s max on Fast 3G
      // => Acceptable mobile experience
    } else if (profileName === "4G") {
      expect(loadTime).toBeLessThan(5000);
      // => 5s max on 4G
      // => Modern mobile baseline
    } else {
      expect(loadTime).toBeLessThan(3000);
      // => 3s max on broadband
      // => Desktop expectation
    }

    await browser.close();
    // => Cleans up browser instance
    // => Releases resources
  });
}