@cldmv/vitest-runner 1.1.0 → 1.2.0

package/README.md

@@ -45,20 +45,22 @@ vitest-runner [OPTIONS] [PATTERNS...]
 
 ### Runner flags
 
-| Flag | Description |
-|------|-------------|
-| `--test-list <file>` | Run only the files listed in a JSON array file instead of scanning |
-| `--file-pattern <regex>` | Override the file discovery regex (default: `\.test\.vitest\.(?:js\|mjs\|cjs)$`) |
-| `--workers <n>` | Number of parallel workers (default: `4` or `VITEST_WORKERS`) |
-| `--solo-pattern <pat>` | Run files matching this path substring solo (one at a time) before the worker pool; repeatable |
-| `--no-error-details` | Hide inline error blocks — show only counts in the summary |
-| `--coverage-quiet` | Implies `--coverage`; suppress per-file output and show only a live progress bar and final summaries |
-| `--log-file <path>` | Write a clean (ANSI-stripped) copy of all output to this file. Defaults to `coverage/coverage-run.log` when `--coverage-quiet` is active |
-| `--suppress-file-output` | Suppress per-file runner output blocks in any mode |
-| `--suppress-passing-files` | Hide the `PASSED TEST FILES` section in the final summary |
-| `--no-top-summary` | Hide `TOP MEMORY USERS` and `TOP DURATION` summary sections |
-| `--json` | Print a JSON run report (no runner text output) |
-| `--help`, `-h` | Print this help and exit |
+| Flag                       | Description                                                                                                                              |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `--test-list <file>`       | Run only the files listed in a JSON array file instead of scanning                                                                       |
+| `--file-pattern <regex>`   | Override the file discovery regex (default: `\.test\.vitest\.(?:js\|mjs\|cjs)$`)                                                         |
+| `--workers <n>`            | Number of parallel workers (default: `4` or `VITEST_WORKERS`)                                                                            |
+| `--solo-pattern <pat>`     | Run files matching this path substring solo (one at a time) before the worker pool; repeatable                                           |
+| `--no-error-details`       | Hide inline error blocks — show only counts in the summary                                                                               |
+| `--coverage-quiet`         | Implies `--coverage`; suppress per-file output and show only a live progress bar and final summaries                                     |
+| `--log-file <path>`        | Write a clean (ANSI-stripped) copy of all output to this file. Defaults to `coverage/coverage-run.log` when `--coverage-quiet` is active |
+| `--suppress-file-output`   | Suppress per-file runner output blocks in any mode                                                                                       |
+| `--suppress-passing-files` | Hide the `PASSED TEST FILES` section in the final summary                                                                                |
+| `--no-top-summary`         | Hide `TOP MEMORY USERS` and `TOP DURATION` summary sections                                                                              |
+| `--json`                   | Print a JSON run report (no runner text output)                                                                                          |
+| `--blobs-dir <path>`       | Directory for per-file coverage blobs (default: `.vitest-coverage-blobs`, relative to `cwd`)                                             |
+| `--no-merge-reports`       | Produce the coverage blobs but skip the merge and summary, leaving them in `--blobs-dir` for an external merge step                      |
+| `--help`, `-h`             | Print this help and exit                                                                                                                 |
 
 ### Test patterns
 
@@ -95,10 +97,10 @@ vitest-runner --bail
 
 ### Environment variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `VITEST_HEAP_MB` | *(none)* | `--max-old-space-size` ceiling passed to every child process |
-| `VITEST_WORKERS` | `4` | Maximum parallel worker slots in the non-solo phase (overridden by `--workers`) |
+| Variable         | Default  | Description                                                                     |
+| ---------------- | -------- | ------------------------------------------------------------------------------- |
+| `VITEST_HEAP_MB` | _(none)_ | `--max-old-space-size` ceiling passed to every child process                    |
+| `VITEST_WORKERS` | `4`      | Maximum parallel worker slots in the non-solo phase (overridden by `--workers`) |
 
 ### Examples
 
@@ -145,10 +147,10 @@ vitest-runner --json --no-top-summary
 ## Programmatic API
 
 ```js
-import { run } from 'vitest-runner';
+import { run } from "vitest-runner";
 
 // CommonJS
-const { run } = await require('vitest-runner');
+const { run } = await require("vitest-runner");
 ```
 
 ### `run(options)` → `Promise<number | object>`
@@ -156,10 +158,10 @@ const { run } = await require('vitest-runner');
 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.
 
 ```js
-import { run } from 'vitest-runner';
+import { run } from "vitest-runner";
 
 const code = await run({
-  testDir: 'src/tests',
+	testDir: "src/tests"
 });
 
 process.exit(code);
@@ -167,33 +169,38 @@ process.exit(code);
 
 #### Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `cwd` | `string` | `process.cwd()` | Absolute project root directory |
-| `testDir` | `string` | `cwd` | Directory (absolute or relative to `cwd`) to scan for `*.test.vitest.{js,mjs}` files |
-| `vitestConfig` | `string` | auto-detect | Explicit vitest config path; when omitted the runner walks standard config names (`vitest.config.ts`, `vite.config.ts`, etc.) relative to `cwd` |
-| `testPatterns` | `string[]` | `[]` | File / folder patterns to filter — empty means all files in `testDir` |
-| `testListFile` | `string` | `undefined` | Path to a JSON array of test file paths; when set, scanning is skipped entirely |
-| `testFilePattern` | `RegExp` | `DEFAULT_TEST_FILE_PATTERN` | Regex matched against file names during discovery (`*.test.vitest.{js,mjs,cjs}` by default) |
-| `vitestArgs` | `string[]` | `[]` | Extra CLI args forwarded verbatim to every vitest invocation |
-| `showErrorDetails` | `boolean` | `true` | Print inline error blocks under each failed file in the summary |
-| `coverageQuiet` | `boolean` | `false` | Suppress per-file output; show only the progress bar and final summaries |
-| `suppressFileOutput` | `boolean` | `false` | Suppress per-file runner output blocks in all modes |
-| `suppressPassingFiles` | `boolean` | `false` | Hide passed-file rows in the final summary |
-| `topSummary` | `boolean` | `true` | Show or hide top memory/duration summary sections (and JSON arrays) |
-| `json` | `boolean` | `false` | Return a JSON report object instead of printing text output |
-| `workers` | `number` | `4` | Maximum parallel worker slots (overrides `VITEST_WORKERS`) |
-| `worstCoverageCount` | `number` | `10` | Rows in the worst-coverage table after a coverage run (`0` disables it) |
-| `maxOldSpaceMb` | `number` | `undefined` | Global `--max-old-space-size` ceiling in MB (overrides `VITEST_HEAP_MB`) |
-| `earlyRunPatterns` | `string[]` | `[]` | Path substrings — matching files run solo (one at a time) before the parallel worker pool starts |
-| `perFileHeapOverrides` | `PerFileHeapOverride[]` | `[]` | Per-file minimum heap ceilings; the maximum of this and `maxOldSpaceMb` wins |
-| `conditions` | `string[]` | `[]` | Additional `--conditions` Node flags forwarded to children |
-| `nodeEnv` | `string` | `'development'` | Value written to `NODE_ENV` in child processes |
+| Option                 | Type                    | Default                        | Description                                                                                                                                                                                                                                              |
+| ---------------------- | ----------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwd`                  | `string`                | `process.cwd()`                | Absolute project root directory                                                                                                                                                                                                                          |
+| `testDir`              | `string`                | `cwd`                          | Directory (absolute or relative to `cwd`) to scan for `*.test.vitest.{js,mjs}` files                                                                                                                                                                     |
+| `vitestConfig`         | `string`                | auto-detect                    | Explicit vitest config path; when omitted the runner walks standard config names (`vitest.config.ts`, `vite.config.ts`, etc.) relative to `cwd`                                                                                                          |
+| `testPatterns`         | `string[]`              | `[]`                           | File / folder patterns to filter — empty means all files in `testDir`                                                                                                                                                                                    |
+| `testListFile`         | `string`                | `undefined`                    | Path to a JSON array of test file paths; when set, scanning is skipped entirely                                                                                                                                                                          |
+| `testFilePattern`      | `RegExp`                | `DEFAULT_TEST_FILE_PATTERN`    | Regex matched against file names during discovery (`*.test.vitest.{js,mjs,cjs}` by default)                                                                                                                                                              |
+| `vitestArgs`           | `string[]`              | `[]`                           | Extra CLI args forwarded verbatim to every vitest invocation                                                                                                                                                                                             |
+| `showErrorDetails`     | `boolean`               | `true`                         | Print inline error blocks under each failed file in the summary                                                                                                                                                                                          |
+| `coverageQuiet`        | `boolean`               | `false`                        | Suppress per-file output; show only the progress bar and final summaries                                                                                                                                                                                 |
+| `suppressFileOutput`   | `boolean`               | `false`                        | Suppress per-file runner output blocks in all modes                                                                                                                                                                                                      |
+| `suppressPassingFiles` | `boolean`               | `false`                        | Hide passed-file rows in the final summary                                                                                                                                                                                                               |
+| `topSummary`           | `boolean`               | `true`                         | Show or hide top memory/duration summary sections (and JSON arrays)                                                                                                                                                                                      |
+| `json`                 | `boolean`               | `false`                        | Return a JSON report object instead of printing text output                                                                                                                                                                                              |
+| `workers`              | `number`                | `4`                            | Maximum parallel worker slots (overrides `VITEST_WORKERS`)                                                                                                                                                                                               |
+| `worstCoverageCount`   | `number`                | `10`                           | Rows in the worst-coverage table after a coverage run (`0` disables it)                                                                                                                                                                                  |
+| `blobsDir`             | `string`                | `<cwd>/.vitest-coverage-blobs` | Directory for per-file coverage blobs. Relative paths resolve against `cwd`. Always cleared at the start of a coverage run                                                                                                                               |
+| `mergeReports`         | `boolean`               | `true`                         | When `true`, blobs are merged via `vitest --mergeReports`, the coverage summary is printed, and `blobsDir` is deleted. When `false`, the run stops after producing blobs — no merge, no summary — and `blobsDir` is left populated for an external merge |
+| `maxOldSpaceMb`        | `number`                | `undefined`                    | Global `--max-old-space-size` ceiling in MB (overrides `VITEST_HEAP_MB`)                                                                                                                                                                                 |
+| `earlyRunPatterns`     | `string[]`              | `[]`                           | Path substrings — matching files run solo (one at a time) before the parallel worker pool starts                                                                                                                                                         |
+| `perFileHeapOverrides` | `PerFileHeapOverride[]` | `[]`                           | Per-file minimum heap ceilings; the maximum of this and `maxOldSpaceMb` wins                                                                                                                                                                             |
+| `conditions`           | `string[]`              | `[]`                           | Additional `--conditions` Node flags forwarded to children                                                                                                                                                                                               |
+| `nodeEnv`              | `string`                | `'development'`                | Value written to `NODE_ENV` in child processes                                                                                                                                                                                                           |
 
 #### `PerFileHeapOverride`
 
 ```ts
-{ pattern: string; heapMb: number }
+{
+	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.
@@ -202,42 +209,40 @@ process.exit(code);
 
 ```js
 // Run all tests under src/tests/ (cwd defaults to process.cwd())
-await run({ testDir: 'src/tests' });
+await run({ testDir: "src/tests" });
 
 // Run only the config and metadata suites
 await run({
-  testDir: 'src/tests',
-  testPatterns: ['src/tests/config', 'src/tests/metadata'],
+	testDir: "src/tests",
+	testPatterns: ["src/tests/config", "src/tests/metadata"]
 });
 
 // Coverage run (OOM-safe blob + merge mode)
 await run({
-  testDir: 'src/tests',
-  vitestArgs: ['--coverage'],
+	testDir: "src/tests",
+	vitestArgs: ["--coverage"]
 });
 
 // Quiet coverage with live progress bar
 await run({
-  testDir: 'src/tests',
-  coverageQuiet: true,
+	testDir: "src/tests",
+	coverageQuiet: true
 });
 
 // Machine-readable output (no text logs)
 const report = await run({
-  testDir: 'src/tests',
-  json: true,
+	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 },
-  ],
+	testDir: "src/tests",
+	maxOldSpaceMb: 2048,
+	earlyRunPatterns: ["listener-cleanup/"],
+	perFileHeapOverrides: [{ pattern: "listener-cleanup/", heapMb: 6144 }]
 });
 ```
 
@@ -259,6 +264,28 @@ This avoids the OOM crash that occurs when a single vitest process holds coverag
 
 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).
 
+### 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:
+
+```js
+// 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
@@ -266,11 +293,7 @@ The log file path can be overridden with `--log-file <path>`. Passing `--log-fil
 A test list file is a plain JSON array of test file paths (relative to `cwd`):
 
 ```json
-[
-  "src/tests/auth/login.test.vitest.mjs",
-  "src/tests/auth/register.test.vitest.mjs",
-  "src/tests/config/defaults.test.vitest.mjs"
-]
+["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`.
@@ -281,7 +304,7 @@ Pass `--test-list <file>` (CLI) or `testListFile: 'path/to/list.json'` (API) to
 
 By default, the runner discovers files matching:
 
-```
+```text
 *.test.vitest.js
 *.test.vitest.mjs
 *.test.vitest.cjs
@@ -297,14 +320,14 @@ vitest-runner --file-pattern '\.spec\.ts$'
 ```
 
 ```js
-await run({ cwd, testDir: 'src', testFilePattern: /\.spec\.ts$/i });
+await run({ cwd, testDir: "src", testFilePattern: /\.spec\.ts$/i });
 ```
 
 ---
 
 ## Source layout
 
-```
+```text
 index.mjs              ← ESM entry (re-exports src/runner.mjs)
 index.cjs              ← CJS shim (dynamic import of index.mjs)
 bin/

package/bin/vitest-runner.mjs

@@ -79,6 +79,8 @@ try {
 		suppressPassingFiles: args.suppressPassingFiles,
 		topSummary: args.topSummary,
 		json: args.json,
+		mergeReports: args.mergeReports,
+		...(args.blobsDir !== undefined && { blobsDir: args.blobsDir }),
 		...(args.workers !== undefined && { workers: args.workers }),
 		...(args.soloPatterns.length > 0 && { earlyRunPatterns: args.soloPatterns })
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/vitest-runner",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Sequential Vitest runner to avoid OOM issues with large test suites",
 	"type": "module",
 	"main": "index.cjs",
@@ -24,7 +24,9 @@
 		"bin/"
 	],
 	"scripts": {
-		"lint": "eslint src/ bin/ index.mjs",
+		"lint": "eslint --config .configs/eslint.config.mjs .",
+		"format": "prettier --write . --config .configs/.prettierrc",
+		"format:check": "prettier --check . --config .configs/.prettierrc",
 		"test": "vitest run --config .configs/vitest.config.mjs",
 		"test:watch": "vitest --config .configs/vitest.config.mjs",
 		"test:coverage": "vitest run --coverage --config .configs/vitest.config.mjs",
@@ -39,10 +41,16 @@
 		"oom"
 	],
 	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@eslint/json": "^2.0.0",
+		"@eslint/markdown": "^8.0.2",
 		"@types/node": "^25.3.0",
-		"@vitest/coverage-v8": "^4.0.18",
+		"@vitest/coverage-v8": "^4.1.9",
+		"eslint": "^10.5.0",
+		"globals": "^17.6.0",
+		"prettier": "^3.8.4",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.18"
+		"vitest": "^4.1.9"
 	},
 	"dependencies": {
 		"chalk": "^5.4.1"
@@ -51,7 +59,7 @@
 		"vitest": ">=1.0.0"
 	},
 	"engines": {
-		"node": ">=18.0.0"
+		"node": ">=20.19.0"
 	},
 	"publishConfig": {
 		"access": "public"

package/src/cli/args.mjs

@@ -13,6 +13,8 @@
  * @property {boolean} suppressPassingFiles - Suppress the passed-files section in the final summary (`--suppress-passing-files`).
  * @property {boolean} topSummary - Show top-summary sections for memory and duration (`true` by default, disabled by `--no-top-summary`).
  * @property {boolean} json - Emit a JSON run report instead of text output (`--json`).
+ * @property {string|undefined} blobsDir - Directory for per-file coverage blobs (`--blobs-dir`); defaults to `<cwd>/.vitest-coverage-blobs`.
+ * @property {boolean} mergeReports - `false` when `--no-merge-reports` was passed; leaves blobs in `blobsDir` without merging.
  * @property {boolean} help - Whether `--help` / `-h` was passed.
  * @property {number|undefined} workers - Worker count from `--workers <n>`, or undefined.
  * @property {string[]} soloPatterns - Path substrings from `--solo-pattern <pattern>` (repeatable).
@@ -31,6 +33,8 @@ const RUNNER_FLAGS = new Set([
 	"--suppress-passing-files",
 	"--no-top-summary",
 	"--json",
+	"--blobs-dir",
+	"--no-merge-reports",
 	"--workers",
 	"--solo-pattern",
 	"--file-pattern",
@@ -63,6 +67,8 @@ export function parseArguments(args) {
 	let suppressPassingFiles = false;
 	let topSummary = true;
 	let json = false;
+	let blobsDir;
+	let mergeReports = true;
 	let workers;
 	let help = false;
 	let testFilePattern;
@@ -89,6 +95,12 @@ export function parseArguments(args) {
 			topSummary = false;
 		} else if (arg === "--json") {
 			json = true;
+		} else if (arg === "--blobs-dir") {
+			blobsDir = args[++i];
+		} else if (arg.startsWith("--blobs-dir=")) {
+			blobsDir = arg.slice("--blobs-dir=".length);
+		} else if (arg === "--no-merge-reports") {
+			mergeReports = false;
 		} else if (arg === "--workers") {
 			workers = parseInt(args[++i], 10);
 		} else if (arg.startsWith("--workers=")) {
@@ -124,6 +136,8 @@ export function parseArguments(args) {
 		suppressPassingFiles,
 		topSummary,
 		json,
+		blobsDir,
+		mergeReports,
 		help,
 		workers,
 		soloPatterns,

package/src/cli/help.mjs

@@ -21,7 +21,7 @@ ${chalk.bold("USAGE:")}
 
 ${chalk.bold("SPECIAL FLAGS:")}
   --test-list <file>      Run only the files listed in a JSON array file
-  --file-pattern <regex>  Override the file discovery regex (default: \.test\.vitest\.(?:js|mjs|cjs)$)
+  --file-pattern <regex>  Override the file discovery regex (default: \\.test\\.vitest\\.(?:js|mjs|cjs)$)
   --workers <n>           Number of parallel workers (default: 4 or VITEST_WORKERS)
   --solo-pattern <pat>    Run files matching this path substring solo first (repeatable)
   --no-error-details      Hide detailed error output (show only counts)
@@ -31,6 +31,8 @@ ${chalk.bold("SPECIAL FLAGS:")}
   --suppress-passing-files  Hide the PASSED TEST FILES section in the final summary
   --no-top-summary        Hide TOP MEMORY USERS and TOP DURATION sections
   --json                  Emit JSON summary output instead of text logs
+  --blobs-dir <path>      Directory for per-file coverage blobs (default: .vitest-coverage-blobs)
+  --no-merge-reports      Leave coverage blobs in --blobs-dir without merging (for an external merge)
   --help, -h              Show this help message
 
 ${chalk.bold("TEST PATTERNS:")}

package/src/core/discover.mjs

@@ -116,7 +116,7 @@ export async function discoverVitestFiles(opts) {
 			const content = await fs.readFile(resolvedListPath, "utf8");
 			testList = JSON.parse(content);
 		} catch (err) {
-			throw new Error(`Failed to read test list file "${resolvedListPath}": ${err.message}`);
+			throw new Error(`Failed to read test list file "${resolvedListPath}": ${err.message}`, { cause: err });
 		}
 
 		if (!Array.isArray(testList)) {

package/src/core/progress.mjs

@@ -157,8 +157,8 @@ export function createCoverageProgressTracker(total) {
 export const noopProgressTracker = {
 	/** @returns {void} */
 	onStart() {},
-	/** @param {boolean} _failedRun @returns {void} */
-	onComplete(_failedRun) {},
+	/** @param {boolean} ___failedRun @returns {void} */
+	onComplete(___failedRun) {},
 	/** @returns {void} */
 	finish() {}
 };

package/src/runner.mjs

@@ -35,8 +35,6 @@ import { runSingleFile, runMergeReports } from "./core/spawn.mjs";
 import { deduplicateErrors } from "./core/parse.mjs";
 import { createCoverageProgressTracker, noopProgressTracker } from "./core/progress.mjs";
 import { printQuietCoverageFailureDetails, printMergeOutput, printCoverageSummary } from "./core/report.mjs";
-import { formatDuration } from "./utils/duration.mjs";
-import { colourPct } from "./utils/ansi.mjs";
 
 /**
  * @typedef {Object} PerFileHeapOverride
@@ -61,6 +59,8 @@ import { colourPct } from "./utils/ansi.mjs";
  * @property {boolean} [json=false] - Return a JSON run report instead of printing text output.
  * @property {number} [workers=4] - Maximum number of parallel worker slots.
  * @property {number} [worstCoverageCount=10] - Rows in the worst-coverage table (0 = disable).
+ * @property {string} [blobsDir] - Directory for per-file coverage blobs (default `<cwd>/.vitest-coverage-blobs`). Relative paths resolve against `cwd`. Always cleared at the start of a coverage run.
+ * @property {boolean} [mergeReports=true] - When `true`, blobs are merged via `vitest --mergeReports`, the coverage summary is printed, and `blobsDir` is deleted at the end. When `false`, the run stops after producing blobs: no merge, no summary, and `blobsDir` is left populated for an external merge step.
  * @property {number} [maxOldSpaceMb] - Global `--max-old-space-size` ceiling; per-file overrides may raise it.
  * @property {string[]} [earlyRunPatterns=[]] - Path substrings — matching files run solo before the worker pool.
  * @property {PerFileHeapOverride[]} [perFileHeapOverrides=[]] - Per-file minimum heap overrides.
@@ -118,6 +118,8 @@ export async function run(opts) {
 		json = false,
 		workers = parseInt(process.env.VITEST_WORKERS ?? "4", 10),
 		worstCoverageCount = 10,
+		blobsDir: blobsDirOpt,
+		mergeReports = true,
 		earlyRunPatterns = [],
 		perFileHeapOverrides = [],
 		conditions = [],
@@ -147,7 +149,7 @@ export async function run(opts) {
 
 	// ─── COVERAGE MODE ───────────────────────────────────────────────────────────
 	if (hasCoverage) {
-		const blobsDir = path.resolve(cwd, ".vitest-coverage-blobs");
+		const blobsDir = path.resolve(cwd, blobsDirOpt ?? ".vitest-coverage-blobs");
 		// Temp coverage dirs live OUTSIDE blobsDir — vitest --mergeReports errors on
 		// any non-blob entry found inside the blobs directory.
 		const coverageTmpBase = path.resolve(cwd, ".vitest-coverage-tmp");
@@ -321,28 +323,38 @@ export async function run(opts) {
 			return 1;
 		}
 
-		if (!coverageQuiet && !suppressFileOutput && emitTextOutput) {
-			console.log(`\n${"=".repeat(80)}`);
-			console.log(`📊 Merging ${blobFiles.length} coverage blobs into final report...`);
-			console.log("=".repeat(80));
-		}
+		// When mergeReports is false, stop after producing the blobs: skip the merge
+		// step and the coverage summary, and leave blobsDir intact so an external step
+		// can merge these blobs together with a separately-produced blob set.
+		let mergeExitCode = 0;
+		let mergeOutput = "";
+		let coverageSummary = null;
 
-		const { exitCode: mergeExitCode, output: mergeOutput } = await runMergeReports(blobsDir, {
-			...spawnBase,
-			maxOldSpaceMb,
-			extraCoverageArgs,
-			quietOutput: coverageQuiet || json
-		});
+		if (mergeReports) {
+			if (!coverageQuiet && !suppressFileOutput && emitTextOutput) {
+				console.log(`\n${"=".repeat(80)}`);
+				console.log(`📊 Merging ${blobFiles.length} coverage blobs into final report...`);
+				console.log("=".repeat(80));
+			}
 
-		if (coverageQuiet && emitTextOutput) {
-			printMergeOutput(mergeExitCode, mergeOutput);
-		}
+			({ exitCode: mergeExitCode, output: mergeOutput } = await runMergeReports(blobsDir, {
+				...spawnBase,
+				maxOldSpaceMb,
+				extraCoverageArgs,
+				quietOutput: coverageQuiet || json
+			}));
 
-		const coverageSummary = await printCoverageSummary(cwd, extraCoverageArgs, worstCoverageCount, { silent: json });
+			if (coverageQuiet && emitTextOutput) {
+				printMergeOutput(mergeExitCode, mergeOutput);
+			}
+
+			coverageSummary = await printCoverageSummary(cwd, extraCoverageArgs, worstCoverageCount, { silent: json });
+		}
 
-		// Clean up blobs and temp dirs
+		// Clean up temp dirs always; only delete blobsDir when we consumed it via merge.
+		// With mergeReports:false the blobs must survive for the caller's external merge.
 		await Promise.all([
-			fs.rm(blobsDir, { recursive: true, force: true }).catch(() => {}),
+			...(mergeReports ? [fs.rm(blobsDir, { recursive: true, force: true }).catch(() => {})] : []),
 			fs.rm(coverageTmpBase, { recursive: true, force: true }).catch(() => {})
 		]);
 

package/types/src/cli/args.d.mts

@@ -45,6 +45,14 @@ export type ParsedArgs = {
      * - Emit a JSON run report instead of text output (`--json`).
      */
     json: boolean;
+    /**
+     * - Directory for per-file coverage blobs (`--blobs-dir`); defaults to `<cwd>/.vitest-coverage-blobs`.
+     */
+    blobsDir: string | undefined;
+    /**
+     * - `false` when `--no-merge-reports` was passed; leaves blobs in `blobsDir` without merging.
+     */
+    mergeReports: boolean;
     /**
      * - Whether `--help` / `-h` was passed.
      */

package/types/src/runner.d.mts

@@ -79,6 +79,14 @@ export type RunOptions = {
      * - Rows in the worst-coverage table (0 = disable).
      */
     worstCoverageCount?: number;
+    /**
+     * - Directory for per-file coverage blobs (default `<cwd>/.vitest-coverage-blobs`). Relative paths resolve against `cwd`. Always cleared at the start of a coverage run.
+     */
+    blobsDir?: string;
+    /**
+     * - When `true`, blobs are merged via `vitest --mergeReports`, the coverage summary is printed, and `blobsDir` is deleted at the end. When `false`, the run stops after producing blobs: no merge, no summary, and `blobsDir` is left populated for an external merge step.
+     */
+    mergeReports?: boolean;
     /**
      * - Global `--max-old-space-size` ceiling; per-file overrides may raise it.
      */