vitest-affected weekly downloads statistics

vitest-affected

Run only the tests affected by your changes. Zero config, runtime dependency tracking, ~5ms selection overhead.

Why

Test more often, not just faster.

If you're running AI coding agents — or multiple agents in parallel — each one needs to verify its changes with tests. On a large codebase, running the full suite after every change is either painfully slow or impossible (machine melts). So you skip tests, and bugs slip through.

vitest-affected makes it practical to test after every single change. Each agent runs ~20 tests in seconds instead of 2,771 tests in minutes. You get continuous verification without overloading your machine.

It works by using Vitest's own runtime import data to build an exact reverse dependency map, diffing it against git, and walking the graph to find exactly which tests are impacted. If you change a utility buried three imports deep, only the tests that transitively depend on it will run.

If anything fails — git error, corrupt cache, incomplete graph — it falls back to the full suite with a warning. It never silently skips tests.

Features

• Runtime dependency tracking — uses Vitest's importDurations for exact, real-world dependency data • Transitive dependency tracking — BFS reverse-walk catches changes buried deep in the import chain • ~5ms selection overhead — delta-parse only changed files, load cached reverse map, BFS select • Persistent cache — reverse dependency map saved to .vitest-affected/graph.json, survives CI runs • Self-healing — cache updates after every run via runtime reporter; stale edges automatically pruned • Config-change detection — package.json, tsconfig.json, vitest.config.*, lockfile changes trigger full suite • Safe by default — any failure falls back to full suite, deleted files handled as BFS seeds • Silent-starvation heartbeats — a completed run that collects zero dependency edges, or a selective run that ran a test it didn't select, is flagged loudly (the failure mode that silently no-op'd the plugin for weeks is now observable) • Shadow mode — run the full pipeline without mutating include, so a single CI run yields ground truth and the would-be selection — the basis for CI divergence monitoring • Explain trail — ask why any test is (or isn't) selected, via the explain option or the vitest-affected-explain CLI • Observability — optional JSON-line stats log for every run

Install

Setup

That's it. On your next vitest run, only affected tests execute.

How It Works

1. First run — no cache exists, so the full suite runs. A runtime reporter captures every module each test imports via importDurations, building an exact reverse dependency map. This is saved to disk. 2. Subsequent runs — the cached reverse map is loaded (~1ms). Git diff identifies changed files. A fast delta-parse with oxc-parser checks changed files for new imports not yet in the cache (~5ms for 1-5 files). BFS walks the reverse map to find affected tests. 3. After every run — the runtime reporter updates the cache with fresh dependency data. Stale edges (removed imports) are automatically pruned via per-test overwrite.

Options

Environment variables

Three env vars override config without editing it — useful in CI:

| Variable | Effect |

| VITEST_AFFECTED_DISABLED=1 | Fully inert — no selection, no shadow, no stats line. The rollback kill switch; wins over everything. | | VITEST_AFFECTED_SHADOW=1 | Force shadow mode (run everything, log the would-be selection). DISABLED still wins. | | VITEST_AFFECTED_STATS_FILE= | Force stats output to , overriding the config statsFile — so a CI step can point stats at a run-scoped file. |

Default ignored paths

The plugin filters obviously-irrelevant changed files before graph analysis to remove noise (parse warnings, "not in graph" warnings) for files that can never participate in the dependency graph. Built-in defaults:

• Path prefixes: .claude/, .git/, .next/, .vitest-affected/, playwright-report/, test-results/ • Basenames: .gitleaksignore, .prettierignore, next-env.d.ts • Extensions: anything outside the code-extension allowlist (markdown, images, CSS, etc.)

Config-file basenames (package.json, tsconfig.json, vitest.config.*, lockfiles) always pass through and trigger a full-suite run, regardless of any ignore rule.

Fixtures & assets: the dependency graph only follows import edges. A test that reads a fixture via fs.readFile, or an asset pulled in through Vite assetsInclude (e.g. .md), has no edge pointing back from that file to its dependents — so changing it would select too few tests (an under-run). Declare such paths in fullSuiteTriggers to force a full-suite run when they change.

Coupling channels

How does a change to file A end up selecting test T? Through a coupling channel — some link that makes T depend on A. This table is the honest accounting of every channel and how vitest-affected treats it. Verdicts:

• TRACKED — selection follows this channel exactly; no action needed. • FALLBACK-COVERED — not followed by the import graph, but covered once its runtime edge is recorded, or via an opt-in escape hatch. • BY-DESIGN — deliberately not an edge; selecting through it would be wrong. • DOCUMENTED-LIMITATION — a real gap with no automatic coverage; use the noted recipe.

| Channel | Verdict | How |…