Skip to main content

Documentation Index

Fetch the complete documentation index at: https://codspeed.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

The @codspeed/playwright-plugin integration currently supports only the walltime instrument. CPU Simulation is not available.
@codspeed/playwright-plugin is the CodSpeed integration for Playwright. It runs a user-defined flow against a target application, measures the time spent inside that flow, and reports it to CodSpeed. The flow itself is plain Playwright code, so anything Playwright can drive can be benchmarked.
Today the plugin supports Electron apps as a target. Browser-based targets (existing dev servers, static builds, hosted URLs) are on the roadmap and will be added under the same bench API.

​
Installation

Install the plugin alongside playwright:

​
Example usage with Electron

Build your Electron app first so the main entrypoint exists (e.g., out/main/index.js), then declare a benchmark with target.kind set to "electron":
bench/inbox.bench.ts
import { bench } from "@codspeed/playwright-plugin";
import path from "node:path";

bench(
  "inbox-search",
  async ({ page }) => {
    await page.fill("#search", "quarterly report");
    await page.waitForSelector("#results");
  },
  {
    target: {
      kind: "electron",
      appPath: path.resolve("out/main/index.js"),
    },
    beforeRound: async ({ page }) => {
      await page.waitForSelector("#main:not(.loading)");
    },
    rounds: 5,
  }
);
For each round, the plugin launches Electron with the provided main entrypoint, waits for the first window, runs beforeRound, measures fn, runs afterRound, then closes the app. For a more complete example, have a look at the example benchmark included in the codspeed-node repository.

​
API

The plugin exposes a single bench function. Its shape is target-agnostic: 
import { bench } from "@codspeed/playwright-plugin";

bench(name, fn, options);
​
name
string
required
Identifier of the benchmark, used by CodSpeed to track it across runs.
​
fn
({ page }) => void | Promise<void>
required
The function whose execution time is measured. Receives a Playwright Page bound to the target. Everything that runs inside fn counts toward the reported timing.
​
options
BenchOptions
required
Target configuration and benchmark settings, detailed below.

​
Options

​
target
Target
required
Discriminated union describing what to drive. The kind field selects the target; the remaining fields are specific to that kind. Current variants: { kind: "electron", ... }. More will be added without breaking existing call sites.
​
rounds
number
default:"1"
Number of measurement rounds. Can be overridden at runtime via the CODSPEED_ROUNDS environment variable.
​
beforeRound
({ page }) => void | Promise<void>
Runs before each round, after the target is ready. Use it to bring the app to a ready state. Not measured.
​
afterRound
({ page }) => void | Promise<void>
Runs after each round, before the target is torn down. Not measured.

​
Electron target options

​
target.kind
"electron"
required
Selects the Electron target.
​
target.appPath
string
required
Absolute path to the Electron main entrypoint, e.g., out/main/index.js.
​
target.electronArgs
string[]
default:"[]"
Extra CLI flags forwarded to the Electron process.
​
target.cwd
string
default:"process.cwd()"
Working directory for the Electron process. Also the directory electron is resolved from when target.electronExecutablePath is not set.
​
target.electronExecutablePath
string
Absolute path to the Electron binary. Only set this to override the default resolution.

​
Running the benchmarks locally

With node 24+, you can run typescript files directly:
terminal
$ node bench/inbox.bench.ts
[CodSpeed] [round 1/5] 42.13 ms
[CodSpeed] [round 2/5] 41.78 ms
[CodSpeed] [round 3/5] 42.05 ms
[CodSpeed] [round 4/5] 41.92 ms
[CodSpeed] [round 5/5] 42.21 ms
Locally, bench runs the app and prints per-round timings to the terminal. Results are uploaded to CodSpeed only when running in the CI environment or when using the CodSpeed CLI.

​
Running the benchmarks in your CI

To generate performance reports, you need to run the benchmarks in your CI. This allows CodSpeed to automatically run benchmarks and warn you about regressions during development.
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:
Two pieces of this workflow are not optional:
  • The job must run on a CodSpeed Macro runner (runs-on: codspeed-macro). Walltime measurements are not stable on shared GitHub-hosted runners.
  • CODSPEED_WALLTIME_PROFILER must be set to samply on the benchmark step. The plugin currently only supports the samply profiler; without it, the run will fail to produce profiling information.
Electron needs a display to render its window. On headless CI runners, wrap the benchmark command with xvfb-run or install a virtual framebuffer, otherwise the app will fail to start.