vitest-profiler

A Vite plugin to profile Vitest test runs.

Motivation

Vitest has fantastic documentation on Profiling Test Performance. When it comes to profiling said performance in practice, it involves a series of configuration and Node.js process modifications that felt too tedious for me to repeat every time. Besides, you likely want those profiling options to be conditional anyway, to apply only when you actually want to profile your test run.

I've created this plugin to implement Vitest recommendations of test profiling while simultaneously giving you a nice experience while doing so. I also intend to keep this plugin in-sync with the Vitest team recommendations in the future so for you it's a single point of entry for accessible test profiling. Enjoy!

Getting started

1. Install

First, add this package as a dependency to your project:

npm i vitest-profiler --save-dev

2. Add plugin

Next, add the vitestProfiler plugin from the vitest-profiler/plugin package to the plugins array of your Vite/Vitest configuration:

// vite.config.js
import { vitestProfiler } from 'vitest-profiler/plugin'

export default defineConfig({
  plugins: [vitestProfiler()],
})

The plugin automatically configures your threads/forks with the correct execArgv to provision Node.js process profiling.

3. Run tests

Finally, run your test command adding vitest-profiler before it:

vitest-profiler npm test

The vitest-profiler CLI will automatically force your tests to be in the run mode (not watch).

Alternatively, you can create a custom NPM script to use as a shorthand:

{
  "scripts": {
    "test": "vitest",
    "test:profile": "vitest-profiler npm test"
  }
}

4. Observe output

After running your tests with the profiler, you will see a message listing all the generated profiles:

Test profiling complete! Generated the following profiles:

  main-thread:
    - CPU:      test-profiles/2025-04-08-10-30-12-main-thread.cpuprofile

  tests:
    - CPU:      test-profiles/2025-04-08--10-30-12-tests.cpuprofile
    - Heap:     test-profiles/2025-04-08--10-30-12-tests.heapprofile

Navigate to the respective files to observe and debug your test performance. Here's a quick guide on each file:

• CPU profiles (*.cpuprofile) record your CPU usage during the test run. Look here to see what takes the most time in your tests;
• Heap profiles (*.heapprofile) record memory usage during the test run. Look here for potential memory leaks/heaps and other memory management issues.