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>

Option	Description
`--name <name>`	Human-readable name
`--runs <n>`	Number of runs to average (default: 3)
`--device <name>`	Device to measure as
`--viewport <WxH>`	Page size

The baseline records the device and page size it was measured at, and perf-regression renders with the same ones. perf-baseline save --browser exits 1: the cold-cache runs need Chromium.

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> <name>

Option	Description
`--sensitivity <level>`	`strict`, `normal`, `ci` or `lenient` (default: normal)
`--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)
`--threshold-ttfb <n>`	Max TTFB increase % (default: 30)
`--threshold-tti <n>`	Max TTI increase %
`--threshold-tbt <n>`	Max TBT increase %
`--output <file>`	Save JSON report to file

perf-regression renders the page as its baseline was captured, so since 20.0 it refuses --device, --viewport and --browser (exit 1) instead of ignoring them.

Example:

# Strict thresholds, 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

Multiple Runs: Use --runs 5 or higher for stable baselines
Consistent Environment: Capture baselines in similar conditions (network, time of day)
Version Baselines: Include version in name (e.g., homepage-v2.1)
Regular Updates: Recapture baselines after intentional performance changes
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);
}

CLI Reference - Full command documentation
MCP Server - Use with Claude for automated monitoring
Examples - More usage examples

Copyright: (c) 2026 Alexa Eden.

License: MIT License

Contact: [email protected]

Performance Regression