Quick Start

Pick your test runner. Both paths use the default SQLite store and capture failures locally in under two minutes.

Bun

1. Install the plugin and a store

   bun add -D @flaky-tests/plugin-bun @flaky-tests/store-sqlite

   Store adapters ship as optionalDependencies of the plugin, so you install only the one you use. The default preload resolves FLAKY_TESTS_STORE (defaults to sqlite) at startup.

2. Add the preload to bunfig.toml

   [test]
   preload = ["@flaky-tests/plugin-bun/preload"]

   That’s it. The next time you run bun test, failures are captured automatically.

3. Run your tests

   bun test

   Failures are written to node_modules/.cache/flaky-tests/failures.db. Nothing else changes — tests still pass and fail as normal.

4. Check for flaky patterns

   After a few runs (or in CI after a few days):

   bunx @flaky-tests/core

   If new patterns are detected you’ll see something like:

   ✗ 1 new flaky test pattern detected
   
     1. auth > login > should redirect on success
        tests/auth.test.ts · timeout · 8 fails in 7d
        Expected redirect within 2000ms
   
     Run with --prompt to print investigation prompts

5. Generate an investigation prompt

   bunx @flaky-tests/core --prompt

   Copy the output into Claude, Cursor, or Copilot to investigate.

Vitest

1. Install the reporter and a store

   npm

   npm i -D @flaky-tests/plugin-vitest @flaky-tests/store-sqlite

   pnpm

   pnpm add -D @flaky-tests/plugin-vitest @flaky-tests/store-sqlite

   yarn

   yarn add -D @flaky-tests/plugin-vitest @flaky-tests/store-sqlite

2. Add the reporter to vitest.config.ts

   vitest.config.ts

   import { defineConfig } from 'vitest/config'
   import { FlakyTestsReporter } from '@flaky-tests/plugin-vitest'
   import { SqliteStore } from '@flaky-tests/store-sqlite'
   
   export default defineConfig({
     test: {
       reporters: ['default', new FlakyTestsReporter(new SqliteStore())],
     },
   })

   Works with Vitest v1, v2, and v3 — the reporter only uses the stable onInit / onFinished hooks.

3. Run your tests

   npm

   npx vitest run

   pnpm

   pnpm vitest run

   yarn

   yarn vitest run

   Failures are written to node_modules/.cache/flaky-tests/failures.db. Nothing else changes — tests still pass and fail as normal.

4. Check for flaky patterns

   After a few runs (or in CI after a few days):

   npm

   npx @flaky-tests/core

   pnpm

   pnpm @flaky-tests/core

   yarn

   yarn @flaky-tests/core

   If new patterns are detected you’ll see something like:

   ✗ 1 new flaky test pattern detected
   
     1. auth > login > should redirect on success
        tests/auth.test.ts · timeout · 8 fails in 7d
        Expected redirect within 2000ms
   
     Run with --prompt to print investigation prompts

5. Generate an investigation prompt

   npm

   npx @flaky-tests/core --prompt

   pnpm

   pnpm @flaky-tests/core --prompt

   yarn

   yarn @flaky-tests/core --prompt

   Copy the output into Claude, Cursor, or Copilot to investigate.

Wire it into package.json

Typing bunx / npx each time gets old. Install the CLI as a dev dependency and add scripts so the whole team runs the same invocation:

npm

npm i -D @flaky-tests/core

pnpm

pnpm add -D @flaky-tests/core

yarn

yarn add -D @flaky-tests/core

package.json

{
  "scripts": {
    "flaky": "flaky-tests",
    "flaky:prompt": "flaky-tests --prompt",
    "flaky:report": "flaky-tests --html"
  }
}

Now anyone on the project can run bun run flaky (or npm run flaky / pnpm flaky / yarn flaky) without reaching for the full package name, and CI workflows get a single stable command to call.

What’s next?

• Working in a team? → Choosing a store — SQLite is local only
• Want automatic detection in CI? → Scheduled detection
• Need deeper Vitest config? → Setting up with Vitest
• Bun-specific options? → Setting up with Bun