Back to docs

Performance Regression

Added in v6.4.0

Automatically detect performance regressions by comparing current metrics against saved baselines.

Quick Start

# 1. Save a baseline (run multiple times for stability)
cbrowser perf-baseline save "https://example.com" --name "homepage" --runs 5

# 2. Later, check for regressions
cbrowser perf-regression "https://example.com" homepage

Baseline Management

Save a Baseline

cbrowser perf-baseline save <url> [options]

Options:
  --name <name>    Human-readable name (required)
  --runs <n>       Number of runs to average (default: 3)

Example:

cbrowser perf-baseline save "https://myapp.com" --name "homepage-v2.1" --runs 5
cbrowser perf-baseline save "https://myapp.com/checkout" --name "checkout-flow"

List Baselines

cbrowser perf-baseline list

Output:

Performance Baselines:
┌──────────────────┬─────────────────────────────────┬────────┬────────┬────────┐
│ Name             │ URL                             │ LCP    │ CLS    │ FCP    │
├──────────────────┼─────────────────────────────────┼────────┼────────┼────────┤
│ homepage-v2.1    │ https://myapp.com               │ 1850ms │ 0.05   │ 980ms  │
│ checkout-flow    │ https://myapp.com/checkout      │ 2100ms │ 0.08   │ 1200ms │
└──────────────────┴─────────────────────────────────┴────────┴────────┴────────┘

Show Baseline Details

cbrowser perf-baseline show <name>

Delete a Baseline

cbrowser perf-baseline delete <name>

Regression Detection

Basic Check

cbrowser perf-regression <url> <baseline-name>

Custom Thresholds

cbrowser perf-regression <url> <baseline> [options]

Options:
  --threshold-lcp <n>    Max LCP increase % (default: 20)
  --threshold-cls <n>    Max CLS increase (default: 0.1)
  --threshold-fcp <n>    Max FCP increase % (default: 20)
  --output <file>        Save JSON report to file

Example:

# Strict thresholds for critical pages
cbrowser perf-regression "https://myapp.com" homepage --threshold-lcp 10 --threshold-cls 0.05

# Save report for CI
cbrowser perf-regression "https://myapp.com" homepage --output regression-report.json

Metrics Tracked

Metric Description Default Threshold
LCP Largest Contentful Paint 20% increase
FID First Input Delay 50% increase
CLS Cumulative Layout Shift 0.1 absolute increase
FCP First Contentful Paint 20% increase
TTFB Time to First Byte 30% increase
TTI Time to Interactive 25% increase
TBT Total Blocking Time 50% increase
Transfer Size Total bytes transferred 25% increase

Example Output

╔══════════════════════════════════════════════════════════════════════════════╗
║                     PERFORMANCE REGRESSION REPORT                            ║
╚══════════════════════════════════════════════════════════════════════════════╝

📊 Comparing: https://myapp.com
📈 Baseline: homepage-v2.1 (captured 2026-01-15)

┌──────────┬──────────┬──────────┬──────────┬────────────┐
│ Metric   │ Baseline │ Current  │ Change   │ Status     │
├──────────┼──────────┼──────────┼──────────┼────────────┤
│ LCP      │ 1850ms   │ 2450ms   │ +32.4%   │ ❌ REGRESS │
│ FCP      │ 980ms    │ 1020ms   │ +4.1%    │ ✅ OK      │
│ CLS      │ 0.05     │ 0.06     │ +0.01    │ ✅ OK      │
│ TTFB     │ 180ms    │ 165ms    │ -8.3%    │ ✅ IMPROVED│
└──────────┴──────────┴──────────┴──────────┴────────────┘

⚠️ REGRESSION DETECTED: 1 metric exceeded threshold

Recommendations:
  - LCP regression: Check for new large images or slow-loading content
  - Consider lazy-loading below-fold images
  - Audit third-party scripts for blocking behavior

CI/CD Integration

GitHub Actions

- name: Performance Regression Check
  run: |
    npx cbrowser perf-regression "${{ env.PREVIEW_URL }}" production-baseline \
      --threshold-lcp 15 \
      --output perf-report.json

- name: Upload Report
  uses: actions/upload-artifact@v3
  with:
    name: performance-report
    path: perf-report.json

Fail on Regression

# Exit code 1 if regression detected
cbrowser perf-regression "https://staging.myapp.com" baseline || exit 1

Best Practices

  1. Multiple Runs: Use --runs 5 or higher for stable baselines
  2. Consistent Environment: Capture baselines in similar conditions (network, time of day)
  3. Version Baselines: Include version in name (e.g., homepage-v2.1)
  4. Regular Updates: Recapture baselines after intentional performance changes
  5. Realistic Thresholds: Start with defaults, adjust based on your SLOs

Programmatic API

import {
  capturePerformanceBaseline,
  detectPerformanceRegression,
  listPerformanceBaselines
} from 'cbrowser';

// Capture baseline
const baseline = await capturePerformanceBaseline(
  'https://example.com',
  { name: 'homepage', runs: 5 }
);

// Check for regression
const result = await detectPerformanceRegression(
  'https://example.com',
  'homepage',
  { thresholds: { lcp: 15, cls: 0.05 } }
);

if (!result.passed) {
  console.log('Regressions:', result.regressions);
}

Related

Copyright: (c) 2026 Alexa Eden.

License: MIT License

Contact: [email protected]

From the Blog