vitest-react-profiler

React component render tracking and performance testing utilities for Vitest

📖 Documentation • 🚀 Quick Start • 📚 API Reference • 💬 Discussions

Features

• 🔍 Precise Render Tracking - Count exact number of renders with zero guesswork
• ⚡ Performance Monitoring - Detect unnecessary re-renders and track component behavior
• 🎯 Phase Detection - Distinguish between mount, update, and nested update phases
• 📸 Snapshot API - Create render baselines with snapshot() and measure deltas with Extended Matchers
• 🪝 Hook Profiling - Profile custom hooks with full Context support via wrapper option
• ⏱️ Async Testing - Subscribe to renders with onRender() and wait with waitForNextRender()
• 🔔 Real-Time Notifications - React to renders immediately with event-based subscriptions
• ⚛️ React 18+ Concurrent Ready - Full support for useTransition and useDeferredValue
• 🧹 True Automatic Cleanup - Zero boilerplate! Components auto-clear between tests
• 🚀 Zero Config - Works out of the box with Vitest and React Testing Library
• 🛡️ Built-in Safety Mechanisms - Automatic detection of infinite render loops and memory leaks
• 💪 Full TypeScript Support - Complete type safety with custom Vitest matchers
• 🧬 Battle-Tested Quality - 100% mutation score, property-based testing, stress tests, SonarCloud verified.
• 🔬 Mathematically Verified - 266 property tests with 140,000+ randomized scenarios per run
• 🏋️ Stress-Tested - 34 stress tests validate performance on 10,000-render histories
• 📊 Performance Baselines - 46 benchmarks establish regression detection metrics

👥 Who Is This For?

🎨 UI-Kit and Design System Developers

Building a UI-kit for your project or company? You need to track, measure, and improve component performance. This tool helps you:

• Catch unnecessary re-renders during development
• Set performance budgets for components
• Document performance characteristics in tests

📦 Open Source React Library Maintainers

Publishing React components? It's critical to prove your solution is optimized and won't degrade performance in user projects. With this tool, you can:

• Add performance tests to CI/CD pipelines
• Showcase performance metrics in documentation
• Track performance regressions between releases

📊 Teams with Strict Performance SLAs

Have strict performance requirements (fintech, healthcare, real-time systems)? The tool allows you to:

• Set thresholds for render counts
• Automatically verify SLA compliance in tests
• Track asynchronous state updates

Quick Start

Installation

npm install --save-dev vitest-react-profiler
# or
yarn add -D vitest-react-profiler
# or
pnpm add -D vitest-react-profiler

Setup

// vitest-setup.ts
import "vitest-react-profiler"; // Auto-registers afterEach cleanup

Configure Vitest:

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "jsdom",
    setupFiles: ["./vitest-setup.ts"],
  },
});

Your First Test

import { render } from '@testing-library/react';
import { withProfiler } from 'vitest-react-profiler';
import { MyComponent } from './MyComponent';

it('should render only once on mount', () => {
  const ProfiledComponent = withProfiler(MyComponent);
  render(<ProfiledComponent />);

  expect(ProfiledComponent).toHaveRenderedTimes(1);
  expect(ProfiledComponent).toHaveMountedOnce();
});

⏱️ Async Testing

Test components with asynchronous state updates using event-based utilities.

const AsyncComponent = () => {
  const [data, setData] = useState(null);
  useEffect(() => {
    fetchData().then(setData);
  }, []);
  return <div>{data ?? "Loading..."}</div>;
};

it('should handle async updates', async () => {
  const Profiled = withProfiler(AsyncComponent);
  render(<Profiled />);

  // Wait for mount + async update
  await expect(Profiled).toEventuallyRenderTimes(2);
});

Key Matchers

• toEventuallyRenderTimes(n) - Wait for exact render count
• toEventuallyRenderAtLeast(n) - Wait for minimum renders
• toEventuallyReachPhase(phase) - Wait for specific phase

📚 Read the complete guide →

🎯 Stabilization API (v1.12.0)

Wait for components to "stabilize" - useful for virtualized lists, debounced search, and animations.

Key Methods

• waitForStabilization(options) - Wait for renders to stop (debounce pattern)
• toEventuallyStabilize(options) - Matcher version for cleaner assertions

📚 Read the complete guide →

🪝 Hook Profiling

Profile custom hooks with full Context support.

import { profileHook } from 'vitest-react-profiler';

const useCounter = (initial: number) => {
  const [count, setCount] = useState(initial);
  return { count, increment: () => setCount(c => c + 1) };
};

it('should track hook renders', () => {
  const { result, profiler } = profileHook(() => useCounter(0));

  expect(profiler).toHaveRenderedTimes(1);

  act(() => result.current.increment());

  expect(profiler).toHaveRenderedTimes(2);
  expect(result.current.count).toBe(1);
});

With Context Support

const { result, profiler } = profileHook(() => useTheme(), {
  wrapper: ({ children }) => (
    <ThemeProvider theme="dark">{children}</ThemeProvider>
  ),
});

📚 Read the complete guide →

⚛️ React 18+ Concurrent Features

Full support for React 18+ Concurrent rendering features - no special configuration needed!

The library automatically tracks renders from:

useTransition / startTransition

Test components using transitions for non-urgent updates

useDeferredValue

Test components using deferred values for performance optimization

How It Works

The library uses React's built-in <Profiler> API, which automatically handles Concurrent mode:

• ✅ Transitions are tracked as regular renders
• ✅ Deferred values trigger additional renders (as expected)
• ✅ Interrupted renders are handled correctly by React
• ✅ No special configuration or setup required

Note: The library tracks renders, not React's internal scheduling. Concurrent Features work transparently - your tests verify component behavior, not React internals.

📚 Read the complete guide →

📸 Snapshot API

Create render baselines and measure deltas for optimization testing.

Testing Single Render Per Action

const ProfiledCounter = withProfiler(Counter);
render(<ProfiledCounter />);

ProfiledCounter.snapshot();                    // Create baseline
fireEvent.click(screen.getByText('Increment'));
expect(ProfiledCounter).toHaveRerenderedOnce(); // Verify single rerender

Testing React.memo Effectiveness

const ProfiledList = withProfiler(MemoizedList);
const { rerender } = render(<ProfiledList items={items} theme="light" />);

ProfiledList.snapshot();
rerender(<ProfiledList items={items} theme="dark" />);
expect(ProfiledList).toNotHaveRerendered();    // Memo prevented rerender

Extended Matchers

// Sync matchers
expect(ProfiledComponent).toHaveRerendered();     // At least one rerender
expect(ProfiledComponent).toHaveRerendered(3);    // Exactly 3 rerenders

// Async matchers - wait for rerenders
await expect(ProfiledComponent).toEventuallyRerender();
await expect(ProfiledComponent).toEventuallyRerenderTimes(2, { timeout: 2000 });

Key Methods & Matchers

| Method/Matcher | Description | |----------------|-------------| | snapshot() | Mark baseline for render counting | | getRendersSinceSnapshot() | Get number of renders since baseline | | toHaveRerenderedOnce() | Assert exactly one rerender | | toNotHaveRerendered() | Assert no rerenders | | toHaveRerendered() | Assert at least one rerender | | toHaveRerendered(n) | Assert exactly n rerenders | | toEventuallyRerender() | Wait for rerender | | toEventuallyRerenderTimes(n) | Wait for exact count |

📚 Read the complete guide →

Documentation

📖 Full documentation is available in the Wiki

Quick Links

• Architecture Documentation - 📐 Complete technical architecture (15 sections, ~14,000 lines)
• Getting Started Guide - Installation and configuration
• API Reference - Complete API documentation
• Snapshot API - Extended matchers for optimization testing
• Hook Profiling - Testing React hooks
• React 18+ Concurrent Features - useTransition & useDeferredValue
• Examples - Real-world usage patterns
• Best Practices - Tips and recommendations
• Troubleshooting - Common issues and solutions

Contributing

We welcome contributions! Please read our Contributing Guide and Code of Conduct.

# Run tests
npm test                    # Unit/integration tests (811 tests)
npm run test:properties     # Property-based tests (266 tests, 140k+ checks)
npm run test:stress         # Stress tests (34 tests, large histories)
npm run test:bench          # Performance benchmarks (46 benchmarks)
npm run test:mutation       # Mutation testing (100% score)

# Build
npm run build

License

MIT © Oleg Ivanov

Made with ❤️ by the community

Report Bug • Request Feature • Discussions