// Test output shows per-component tables when multiple components are profiled
`

$3

`ts
// test/performance.setup.ts
import { test as base } from '@playwright/test';
import { createPerformanceTest } from 'react-performance-tracking/playwright';

export const test = createPerformanceTest(base);
export { expect } from '@playwright/test';
`

$3

`ts
// test/my-page.perf.spec.ts
import { test } from './performance.setup';

test.describe('My Page Performance', () => {
// Simple test with basic thresholds
test.performance({
thresholds: {
base: {
profiler: {
'*': { duration: 500, rerenders: 20 },
},
},
},
})('page load performance', async ({ page, performance }) => {
await page.goto('/my-page');
await performance.init();
// Assertions run automatically
});

// Test user interactions
test.performance({
thresholds: { base: { profiler: { '*': { duration: 100, rerenders: 5 } } } },
})('button click interaction', async ({ page, performance }) => {
await page.goto('/my-page');
await performance.init();

await performance.reset(); // Isolate the interaction
await page.click('button[data-testid="submit"]');
await performance.waitUntilStable();
});
});
`

$3

`ts
test.describe('Advanced Usage', () => {
// Track custom timing metrics
test.performance({
thresholds: { base: { profiler: { '*': { duration: 500, rerenders: 20 } } } },
})('data loading with custom metrics', async ({ page, performance }) => {
await page.goto('/my-page');
await performance.init();

performance.mark('fetch-start');
await page.click('button[data-testid="load-data"]');
await page.waitForSelector('.data-loaded');
performance.mark('fetch-end');

performance.mark('render-start');
await performance.waitUntilStable();
performance.mark('render-end');

// Create measures for each operation
const fetchTime = performance.measure('data-fetch', 'fetch-start', 'fetch-end');
const renderTime = performance.measure('data-render', 'render-start', 'render-end');

console.log(Fetch: ${fetchTime}ms, Render: ${renderTime}ms);
// Custom metrics are automatically included in test output and artifacts
});
});
`

Advanced Usage: Custom Fixtures

When using createPerformanceTest(), only page and performance fixtures are passed to your test function. If you need custom fixtures (like page objects, mocks, etc.), see the Custom Fixtures Guide.

API Overview

You can import from the root (react-performance-tracking) or subpaths (/react, /playwright).

$3

`ts
import {
PerformanceProvider,
usePerformance,
usePerformanceRequired,
usePerformanceStore,
} from 'react-performance-tracking/react';
`

$3

Essential - what most users need:

`ts
import {
createPerformanceTest,
PERFORMANCE_CONFIG,
NETWORK_PRESETS,
setLogLevel,
} from 'react-performance-tracking/playwright';
`

Configuration Options

$3

`ts
test.performance({
warmup?: boolean; // default: true on CI, false locally
throttleRate?: number; // default: 1 (no throttling)
iterations?: number; // default: 1 (single run)
networkThrottling?: NetworkThrottlingConfig; // preset or custom (Chromium only)
exportTrace?: boolean | string; // export trace for flamegraph (Chromium only)
thresholds: {
base: {
profiler: {
'*': { // Default for all components
duration: number | { avg?: number; p50?: number; p95?: number; p99?: number };
rerenders: number;
};
// Additional component IDs can be specified
// 'header'?: { duration: 100, rerenders: 5 };
};
fps?: number | { avg?: number; p50?: number; p95?: number; p99?: number }; // Min FPS (auto-enables FPS tracking, Chromium only)
memory?: {
heapGrowth?: number; // max heap growth in bytes (auto-enables memory tracking, Chromium only)
};
webVitals?: { // Web Vitals thresholds (auto-enables tracking, all browsers)
lcp?: number; // max LCP in ms (Google recommends ≤2500)
inp?: number; // max INP in ms (Google recommends ≤200)
cls?: number; // max CLS score (Google recommends ≤0.1)
};
};
ci?: { // Overrides for CI environment
profiler?: {
[componentId: string]: Partial;
};
fps?: number | { avg?: number; p50?: number; p95?: number; p99?: number };
memory?: { heapGrowth?: number };
webVitals?: { lcp?: number; inp?: number; cls?: number };
};
};
buffers?: {
duration?: number; // % buffer (default: 20) - also used for duration percentiles (p50, p95, p99)
rerenders?: number; // % buffer (default: 20)
fps?: number; // % buffer (default: 20) - also used for fps percentiles (p50, p95, p99)
heapGrowth?: number; // % buffer (default: 20)
webVitals?: { lcp?: number; inp?: number; cls?: number }; // % buffers (default: 20 each)
};
name?: string; // artifact name
})('test title', async ({ page, performance }) => { ... });

// NetworkThrottlingConfig can be:
// - Preset: 'slow-3g' | 'fast-3g' | 'slow-4g' | 'fast-4g' | 'offline'
// - Custom: { latency: number, downloadThroughput: number, uploadThroughput: number, offline?: boolean }
`

$3

- init() – Wait for profiler initialization and stability
- reset() – Clear collected samples and custom metrics (isolate measurements)
- waitForInitialization(timeout?) – Wait for profiler to be ready
- waitUntilStable(options?) – Wait for React to settle
- mark(name) – Record a custom performance mark (timestamp)
- measure(name, startMark, endMark) – Create a measure between two marks (returns duration in ms)
- getCustomMetrics() – Get all recorded marks and measures

$3

`ts
const PERFORMANCE_CONFIG = {
profiler: {
stabilityPeriodMs: 1000,
checkIntervalMs: 100,
maxWaitMs: 5000,
initializationTimeoutMs: 10000,
},
buffers: {
duration: 20,
rerenders: 20,
avg: 20,
heapGrowth: 20,
webVitals: { lcp: 20, inp: 20, cls: 20 },
},
throttling: {
defaultRate: 1,
},
fps: {
defaultThreshold: 60,
},
memory: {
defaultThreshold: 0, // 0 = no threshold, just track
},
webVitals: {
enabled: false, // off by default to avoid overhead
},
iterations: {
defaultCount: 1,
},
get isCI() {
return Boolean(process.env.CI);
},
};
`

$3

`ts
import { setLogLevel } from 'react-performance-tracking/playwright';

// Available levels: 'silent' | 'error' | 'warn' | 'info' | 'debug'
setLogLevel('silent'); // Disable all console output
setLogLevel('error'); // Only show errors
setLogLevel('info'); // Default - show info, warnings, errors
`

$3

| Environment | Thresholds Used | Warmup Default |
| ----------- | ----------------------- | -------------- |
| CI | base merged with ci | true |
| Local | base only | false |

Console Output

`
════════════════════════════════════════════════════════════════════════════════
[Performance] PERFORMANCE TEST: page-load-performance
════════════════════════════════════════════════════════════════════════════════
Environment: local | CPU: 4x | Iterations: 3
────────────────────────────────────────────────────────────────────────────────

ITERATIONS
┌─────┬─────────────┬─────────┬───────┐
│ # │ Duration │ Renders │ FPS │
├─────┼─────────────┼─────────┼───────┤
│ 1 ○ │ 35.20ms │ 26 │ 29.6 │
│ 2 │ 22.50ms │ 26 │ 47.4 │
│ 3 │ 21.60ms │ 26 │ 50.5 │
├─────┼─────────────┼─────────┼───────┤
│ AVG │ 22.05ms ±0.5│ 26 ±0.0│ 49.0 │
└─────┴─────────────┴─────────┴───────┘
○ = warmup (excluded from average)

RESULTS
┌──────────┬──────────┬───────────┬────────┐
│ Metric │ Actual │ Threshold │ Status │
├──────────┼──────────┼───────────┼────────┤
│ Duration │ 22.05ms │ < 600ms │ ✓ PASS │
│ Renders │ 26 │ ≤ 24 │ ✓ PASS │
│ FPS │ 49.0 │ ≥ 44.0 │ ✓ PASS │
│ LCP │ 1523ms │ ≤ 3000ms │ ✓ PASS │
│ INP │ 85ms │ ≤ 240ms │ ✓ PASS │
│ CLS │ 0.050 │ ≤ 0.12 │ ✓ PASS │
└──────────┴──────────┴───────────┴────────┘

════════════════════════════════════════════════════════════════════════════════
✓ ALL CHECKS PASSED
════════════════════════════════════════════════════════════════════════════════
`

Troubleshooting

$3

- Increase initialization timeout: Adjust initializationTimeoutMs in your config
- Check PerformanceProvider: Ensure it wraps your app root component
- Verify profiler IDs: Make sure IDs match your test expectations

`ts
// Extend timeout if needed
await performance.waitForInitialization(15000); // 15 seconds instead of default 10s
`

$3

- Browser requirement: FPS tracking requires Chromium (Chrome/Edge)
- Enable in config: Add fps thresholds to automatically enable FPS tracking
- Check CDP availability: Non-Chromium browsers will silently skip FPS tracking

$3

- Environment differences: Check if you're running in CI vs local (different thresholds apply)
- Review buffers: Default buffer is 20% - adjust in config if needed
- Component-specific thresholds: Use per-component thresholds for fine-grained control

`ts
thresholds: {
base: {
profiler: {
'*': { duration: 500, rerenders: 20 },
},
},
ci: {
profiler: {
'*': { duration: 600 }, // More lenient in CI
},
},
},
buffers: {
duration: 10, // Reduce buffer to 10%
},
`

$3

- Chromium only: These features require Chromium browser
- Check config: Verify memory.heapGrowth threshold or networkThrottling config is set
- Session conflicts: Ensure no other tools are using CDP on the same page

$3

- 📖 Read the Documentation
- 💬 Open a GitHub Discussion
- 🐛 Report a bug via GitHub Issues

Limitations

- CPU throttling, FPS tracking, memory tracking, and network throttling require Chromium/CDP; other browsers skip them quietly.
- React Profiler must be enabled in production builds if you test prod bundles.
- When using createPerformanceTest(), only page and performance` fixtures are exposed. Use the building blocks directly if you need custom fixtures (see Advanced Usage above).

Requirements

- React 18+ or 19+
- Playwright 1.40+
- Node.js 18+

License

MIT