Vitest (recommended)

Installation

First install the plugin @codspeed/vitest-plugin and vitest (if not already installed):

info

The CodSpeed plugin is only compatible with vitest v1.2.2 and above.

npm

npm install --save-dev @codspeed/vitest-plugin vitest

yarn

yarn add --dev @codspeed/vitest-plugin vitest

pnpm

pnpm add --save-dev @codspeed/vitest-plugin vitest

Usage

Let's create a fibonacci function and benchmark it with vitest and the CodSpeed plugin:

TypeScript

src/fibo.bench.ts

import { bench, describe } from "vitest";

function fibonacci(n: number): number {
  if (n < 2) {
    return n;
  }
  return fibonacci(n - 1) + fibonacci(n - 2);
}

describe("fibo", () => {
  bench("fibo 10", () => {
    fibonacci(10);
  });
  bench("fibo 15", () => {
    fibonacci(15);
  });
});

JavaScript

src/fibo.bench.js

import { bench, describe } from "vitest";

function fibonacci(n) {
  if (n < 2) {
    return n;
  }
  return fibonacci(n - 1) + fibonacci(n - 2);
}

describe("fibo", () => {
  bench("fibo 10", () => {
    fibonacci(10);
  });
  bench("fibo 15", () => {
    fibonacci(15);
  });
});

Here, a few things are happening:

• We create a simple recursive fibonacci function.
• We create a new vitest suite "fibo" with two benchmarks, benching our fibonacci function for 10 and 15.

Create or update the vitest.config.ts file to use the CodSpeed runner:

vitest.config.ts

import codspeedPlugin from "@codspeed/vitest-plugin";
import { defineConfig } from "vitest/config";

export default defineConfig({
  plugins: [codspeedPlugin()],
  // ...
});

Now, we can run our benchmarks locally to make sure everything is working as expected:

npm

npx vitest bench --run

yarn

yarn vitest bench --run

pnpm

pnpm vitest bench --run

This will run the benchmarks and output the results in the terminal (for example, with pnpm):

Troubleshooting errors

If you encounter an error like Failed to resolve "@codspeed/vitest-plugin" from "vitest.config.ts", you might need to rename the vitest.config.ts file to vitest.config.mts.

You can find more information in the Vite documentation on importing ESM package.

And... Congrats🎉, CodSpeed is installed in your benchmarking suite! Locally, CodSpeed will fall back to vitest since the instrumentation is only available in the CI environment for now.

You can now run those benchmarks in your CI to get consistent performance measurements.

Running the benchmarks in your CI

To generate performance reports, you need to run the benchmarks in your CI. This allows CodSpeed to detect the CI environment and properly configure the instrumented environment.

tip

If you want more details on how to configure the CodSpeed action, you can check out the Continuous Reporting section.

Here is an example of a GitHub Actions workflow that runs the benchmarks and reports the results to CodSpeed on every push to the main branch and every pull request:

.github/workflows/codspeed.yml

name: CodSpeed

on:
  push:
    branches:
      - "main" # or "master"
  pull_request:
  # `workflow_dispatch` allows CodSpeed to trigger backtest
  # performance analysis in order to generate initial data.
  workflow_dispatch:

jobs:
  benchmarks:
    name: Run benchmarks
    runs-on: ubuntu-latest
    steps:
      - uses: "actions/checkout@v4"
      - uses: "actions/setup-node@v3"
      - name: Install dependencies
        run: npm install
      - name: Run benchmarks
        uses: CodSpeedHQ/action@v3
        with:
          run: npm exec vitest bench
          token: ${{ secrets.CODSPEED_TOKEN }}