@cldmv/vitest-runner

@cldmv/vitest-runner is a sequential Vitest runner that spawns each test file in its own child process, so a large test suite never has to fit in one Vitest process's memory. It runs files one at a time or in a parallel worker pool, gives heavy files their own heap ceiling or a solo slot, and prints one combined summary of results, memory use and duration at the end.

Coverage stays out-of-memory-safe too: each file writes a coverage blob, and a single vitest --mergeReports step combines them into one report, with a worst-coverage table after it. The runner auto-detects your Vitest config, forwards every standard Vitest flag unchanged, and works as a vitest-runner CLI or as a programmatic run() API from ESM and CommonJS.

Big suites, small processes: every test file gets its own Vitest, and the results come back as one run.

✨ What's New

Latest: v1.6.1 (November 2026)

• engines.node set to the runtime floor — v1.6.0 declared >=22.22.0, the build and test toolchain floor. engines.node is now >=22.0.0, the floor of the chalk 6 dependency, and the 22.22.0 development floor moves to devEngines, so earlier Node.js 22 releases install the runner without an EBADENGINE warning. require() needs Node.js >=22.13.0; behavior and options are unchanged (#115).
• View full v1.6.1 Changelog

Recent Releases

• v1.6.0 (November 2026) — --conditions=vitest-runner-dev sends require() to src/index.cjs too, and engines.node raised to >=22.22.0; runner behavior unchanged (Changelog)
• v1.5.6 (October 2026) — Dev-tooling dependency update: tsup 9, Vitest 5.0.5 and a katex override clear both Dependabot alerts; the built files are byte-identical to v1.5.5 (Changelog)
• v1.5.5 (October 2026) — No more ENOTEMPTY startup errors from Vitest 5's module cache: a cache directory per package, one lockfile check per run, and a new fsModuleCachePath option (Changelog)
• v1.5.4 (October 2026) — Dev-tooling dependency update (@cldmv/fix-headers 2.2.0, @cldmv/configs 1.2.4); the published package is identical to v1.5.3 (Changelog)

📚 For complete release notes, see the docs/changelog/ folder.

🚀 Key Features

• Runs every test file in its own child process, one at a time or in a configurable parallel worker pool
• Solo slots for heavy files (--solo-pattern) and per-file heap ceilings (perFileHeapOverrides)
• Full coverage mode via blob-per-file + --mergeReports (no OOM), with a worst-coverage table
• Auto-detects your vitest config; accepts an explicit path if needed
• All standard Vitest CLI flags are forwarded unchanged
• Usable as a CLI binary or as a programmatic Node.js API, with an optional JSON run report
• A per-run scratch directory for every test file (VITEST_RUNNER_TMP / makeRunTmpDir), cleaned up on exit
• ES module build with a thin CommonJS entry for require()

📦 Installation

Requirements

• Node.js 22.0.0 or later (engines.node is >=22.0.0, set by the chalk 6 dependency). The package is an ES module and loads with import. The Vitest version you install has its own Node.js floor. Node.js 20 is not supported from v1.5.3; stay on v1.5.1 there.
• require("@cldmv/vitest-runner") loads the ES module build synchronously, which needs Node.js >=22.13.0; on older Node.js, use import() instead.
• Developing this package needs Node.js 22.22.0 or later (devEngines).
• vitest ≥ 1.0 (peer dependency, installed in your project)
• chalk (bundled dependency — no action needed)

Install

npm install --save-dev @cldmv/vitest-runner

Or to use the CLI globally:

npm install -g @cldmv/vitest-runner

🚀 Quick Start

Run every discovered *.test.vitest.{js,mjs,cjs} file, each in its own process:

npx vitest-runner

Run with OOM-safe coverage and a live progress bar:

npx vitest-runner --coverage-quiet

From code:

import { run } from "@cldmv/vitest-runner";

const code = await run({ testDir: "src/tests" });
process.exit(code);

The full flag list is under CLI usage and every option under Programmatic API.

💻 CLI usage

vitest-runner [OPTIONS] [PATTERNS...]

Runner flags

Test patterns

Patterns are resolved against cwd. Any of the following forms work:

# Absolute or relative file path
vitest-runner src/tests/config/background.test.vitest.mjs

# Partial path or filename — matched against all discovered test files
vitest-runner background.test.vitest.mjs
vitest-runner config/background.test.vitest.mjs

# Directory — all test files inside it are run
vitest-runner src/tests/metadata

Multiple patterns can be combined:

vitest-runner src/tests/config src/tests/metadata

Vitest passthrough flags

All unrecognised flags are forwarded verbatim to every vitest child process:

vitest-runner --reporter=verbose
vitest-runner -t "lazy materialization"
vitest-runner --coverage
vitest-runner --bail

Environment variables

Examples

# Run all test files discovered under the default testDir
vitest-runner

# Run all tests, filter by name
vitest-runner -t "should handle null input"

# Run a specific folder
vitest-runner src/tests/auth

# Run with coverage (blob + merge — OOM-safe)
vitest-runner --coverage

# Coverage with quiet output and live progress bar (ideal for CI)
vitest-runner --coverage --coverage-quiet

# Run only files listed in a JSON file
vitest-runner --test-list my-tests.json

# Use a custom file discovery pattern
vitest-runner --file-pattern '\.spec\.ts$'

# Run 2 workers, with certain files running solo first
vitest-runner --workers 2 --solo-pattern heavy/ --solo-pattern listener-cleanup/

# Skip scratch worktrees / build output when discovery walks the repo root
vitest-runner --exclude 'tmp/**' --exclude 'dist/**'

# Custom heap and worker count
VITEST_HEAP_MB=8192 vitest-runner --workers 2 src/tests/heavy

# Suppress error details in the summary
vitest-runner --no-error-details

# JSON output for automation
vitest-runner --json

# JSON output without top summary arrays
vitest-runner --json --no-top-summary

🔧 Programmatic API

import { run } from "@cldmv/vitest-runner";

// CommonJS
const { run } = require("@cldmv/vitest-runner");

require() loads the ES module build synchronously through Node's require(esm), which needs Node.js >=22.13.0; on older Node.js it throws a clear ERR_REQUIRE_ESM error, and import() is the way to load the package there.

When developing against a local checkout or workspace copy instead of the published package, run Node with --conditions=vitest-runner-dev so that import of the package resolves to its src/ entry (src/index.mjs) and require to src/index.cjs, instead of the built dist/.

run(options) → Promise<number | object>

Runs the test suite and resolves with an exit code (0 = all passed, 1 = any failure) by default. When json: true is passed, it returns a structured JSON report object (including exitCode) instead of printing runner text output.

import { run } from "@cldmv/vitest-runner";

const code = await run({
    testDir: "src/tests"
});

process.exit(code);

Options

PerFileHeapOverride

{
    pattern: string;
    heapMb: number;
}

pattern is a substring matched against the normalised (forward-slash) file path. The first match wins and is compared against the global maxOldSpaceMb; the larger value is used.

Examples

// Run all tests under src/tests/ (cwd defaults to process.cwd())
await run({ testDir: "src/tests" });

// Run only the config and metadata suites
await run({
    testDir: "src/tests",
    testPatterns: ["src/tests/config", "src/tests/metadata"]
});

// Coverage run (OOM-safe blob + merge mode)
await run({
    testDir: "src/tests",
    vitestArgs: ["--coverage"]
});

// Quiet coverage with live progress bar
await run({
    testDir: "src/tests",
    coverageQuiet: true
});

// Machine-readable output (no text logs)
const report = await run({
    testDir: "src/tests",
    json: true
});

console.log(report.exitCode);

// Give heap-heavy files a larger ceiling while keeping the global limit lower
await run({
    testDir: "src/tests",
    maxOldSpaceMb: 2048,
    earlyRunPatterns: ["listener-cleanup/"],
    perFileHeapOverrides: [{ pattern: "listener-cleanup/", heapMb: 6144 }]
});

Scratch directories (VITEST_RUNNER_TMP / makeRunTmpDir)

Every run gets its own scratch root (<scratchDir>/<pid>-<timestamp>/), created before any file runs and removed once the run completes — on success, on failure, and on SIGINT/SIGTERM — unless keepTmp is set. Each file invocation gets its own subdirectory under that root, exposed to the child as process.env.VITEST_RUNNER_TMP. Stale roots left by a crashed prior run (dead PID) are swept at the start of the next run.

From a test file, use makeRunTmpDir(label) to get a fresh, uniquely-named subdirectory instead of managing your own mkdtemp base:

import { makeRunTmpDir } from "@cldmv/vitest-runner";

const dir = makeRunTmpDir("my-fixture"); // a fresh directory under VITEST_RUNNER_TMP

CLI flags: --scratch-dir <path> and --keep-tmp (see Runner flags above).

Vitest's module cache

Vitest 5 caches transformed modules on disk (fsModuleCache, on by default from 5.0.5). Its default location is node_modules/.vitest-cache at the workspace root, shared by every package in the workspace, and each vitest process deletes the whole directory on startup when the lockfile differs from the one the cache was written for. Several processes starting at once after a lockfile change all try to delete it, and some fail with ENOTEMPTY. Packages in one workspace that have their own lockfile also keep clearing each other's cache.

Before any file runs, the runner starts one short helper process that loads the project's Vitest config (the root and every project) the way the workers will, and:

• picks a cache per package: when the cache is on and nothing sets a path, every child gets --fsModuleCachePath=<cwd>/node_modules/.vitest-cache, so one package's run never clears another's cache;
• checks the lockfile once: it starts Vitest once with the workers' args, which clears a stale cache, and exits. The workers then start on a cache that matches the lockfile. This step is skipped when solo files run first (the first solo file does the same job), when files never run in parallel, or when the cache is off.

The cache path is chosen in this order:

1. a --fsModuleCachePath passthrough arg;
2. the fsModuleCachePath option (false adds nothing and leaves Vitest's own setting in place);
3. fsModuleCachePath set anywhere in the resolved config, including a project's own config;
4. <cwd>/node_modules/.vitest-cache.

None of this applies to Vitest before 5, and if the helper fails or takes longer than a minute, the run goes ahead without it. To turn the cache off, pass --fsModuleCache=false or set fsModuleCache: false in the vitest config.

📊 Coverage mode

When --coverage (or coverageQuiet: true) is passed, the runner uses a blob-per-file strategy:

1. Each file receives --coverage --reporter=blob with its own temp output directory.
2. After all files complete, vitest --mergeReports combines the blobs into a single report.
3. Temporary blob and coverage-tmp directories are cleaned up automatically.

This avoids the OOM crash that occurs when a single vitest process holds coverage data for thousands of files simultaneously.

Coverage quiet mode

--coverage-quiet / coverageQuiet: true suppresses all per-file output and renders a live progress bar instead. On completion it prints the coverage table and any failures verbosely. When running in this mode, output is also mirrored to coverage/coverage-run.log (CLI only) with ANSI colour codes stripped so the file is human-readable in any editor.

The log file path can be overridden with --log-file <path>. Passing --log-file by itself only enables log mirroring (it does not enable coverage mode).

When no files are measured

If the coverage include matches no files (for example, a scaffold repo with a test but no source yet), istanbul reports every percentage as Unknown rather than a number. The runner prints those metrics as Unknown — Coverage Unknown% lines | Unknown% statements | … — adds a note that no files were measured, and exits 0 if the tests passed. The same applies to any individual non-numeric percentage in the worst-coverage table.

Coverage thresholds are skipped in this case, because there is nothing to measure: vitest's own threshold check does not fail on an Unknown percentage, and the runner does not add a check of its own. Thresholds apply again as soon as at least one file is measured. The JSON report's coverageSummary.noFilesMeasured is true for such a run.

Producing blobs for an external merge

Set mergeReports: false (CLI: --no-merge-reports) to stop the run after the per-file blobs are written. The internal vitest --mergeReports call and the coverage summary are skipped, and blobsDir is left intact instead of being deleted. The blobs directory is still cleared at the start of each run, so it only ever contains the current run's output.

This is useful when a second coverage blob set (for example, a browser-mode run with a different coverage transform) needs to be merged together with the node-mode blobs. Point both runs at known directories with blobsDir, then merge them in one external vitest --mergeReports step:

// Node-mode blobs, no internal merge
await run({
    testDir: "src/tests",
    vitestArgs: ["--coverage"],
    blobsDir: ".coverage-blobs/node",
    mergeReports: false
});

// (separately produce browser-mode blobs into .coverage-blobs/browser)
// then merge both blob sets in a single external step:
//   vitest --mergeReports .coverage-blobs --coverage

The exit code still reflects test pass/fail; there is just no coverage-merge result to fold in.

📋 Test list files

A test list file is a plain JSON array of test file paths (relative to cwd):

["src/tests/auth/login.test.vitest.mjs", "src/tests/auth/register.test.vitest.mjs", "src/tests/config/defaults.test.vitest.mjs"]

Pass --test-list <file> (CLI) or testListFile: 'path/to/list.json' (API) to run exactly those files instead of scanning testDir.

🔍 Test file naming

By default, the runner discovers files matching:

*.test.vitest.js
*.test.vitest.mjs
*.test.vitest.cjs

Files in node_modules or hidden directories (names starting with .) are always skipped.

The pattern can be overridden with --file-pattern <regex> (CLI) or the testFilePattern option (API):

# Match .spec.ts files instead
vitest-runner --file-pattern '\.spec\.ts$'

await run({ cwd, testDir: "src", testFilePattern: /\.spec\.ts$/i });

📁 Source layout

dist/                  ← built library entry (npm run build / tsup) — generated, not committed
  index.mjs            ← bundled ESM entry
  index.cjs            ← thin CJS entry, copied verbatim from src/index.cjs; require()s index.mjs
bin/                   ← built CLI binary (npm run build / tsup) — generated, not committed
  vitest-runner.mjs    ← bundled CLI, from src/bin/vitest-runner.mjs (shebang preserved)
src/
  index.mjs            ← main run() API + re-exports
  index.cjs            ← CommonJS entry source (copied to dist/index.cjs by the build)
  bin/
    vitest-runner.mjs  ← CLI entry SOURCE — run this directly for source-level dev/testing
  utils/
    ansi.mjs           ← stripAnsi, colourPct
    duration.mjs       ← formatDuration
    env.mjs            ← buildNodeOptions, buildEnv
    resolve.mjs        ← resolveBin, resolveVitestConfig
  core/
    discover.mjs       ← discoverVitestFiles, sortWithPriority, computeFilterConflicts
    parse.mjs          ← parseVitestOutput, deduplicateErrors
    spawn.mjs          ← runSingleFile, runVitestDirect, runMergeReports
    report.mjs         ← printCoverageSummary, printMergeOutput
    progress.mjs       ← createCoverageProgressTracker
    scratch.mjs        ← makeRunTmpDir + the scratch-directory lifecycle
    fs-cache.mjs       ← prepareFsModuleCache: Vitest module cache path + one-time lockfile check
    fs-cache-helper.mjs ← helper process started by fs-cache.mjs (built to dist/ and bin/)
  cli/
    args.mjs           ← parseArguments
    help.mjs           ← showHelp

src/ is not published — only dist/, bin/, and types/ ship (see Programmatic API for the vitest-runner-dev export condition, used when developing against a workspace/local checkout instead of the published package). All sub-module utilities are re-exported from the root entry point, so deep imports are optional.

📚 Documentation

• Changelog — release notes for every version
• Release notes on GitHub — the same notes attached to each release tag

🤝 Contributing

Bug reports and pull requests are welcome on GitHub. Pull requests target the next branch; releases ship from next to master.

🔗 Links

• npm: @cldmv/vitest-runner
• GitHub: CLDMV/vitest-runner
• Issues: GitHub Issues
• Changelog: docs/changelog/
• Releases: GitHub Releases

📄 License

Apache-2.0 © Shinrai / CLDMV. See LICENSE for the full text.