@cldmv/vitest-runner 1.0.3 → 1.2.0

package/README.md

@@ -45,16 +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; implies `--coverage-quiet` when set without it. Defaults to `coverage/coverage-run.log` when `--coverage-quiet` is active |
-| `--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
 
@@ -91,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
 
@@ -128,6 +134,12 @@ 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
 ```
 
 ---
@@ -135,21 +147,21 @@ vitest-runner --no-error-details
 ## 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>`
+### `run(options)` → `Promise<number | object>`
 
-Runs the test suite and resolves with an exit code (`0` = all passed, `1` = any failure). Does **not** call `process.exit` — that is the caller's responsibility.
+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);
@@ -157,29 +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 |
-| `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.
@@ -188,34 +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
+});
+
+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 }]
 });
 ```
 
@@ -235,7 +262,29 @@ This avoids the OOM crash that occurs when a single vitest process holds coverag
 
 `--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` alone (without `--coverage-quiet`) also enables quiet mode and log mirroring.
+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.
 
 ---
 
@@ -244,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`.
@@ -259,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
@@ -275,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

@@ -3,7 +3,7 @@
  * @fileoverview CLI entry point for the vitest-runner binary.
  * @module vitest-runner/bin/vitest-runner
  *
- * Mirrors its own output to a log file when --coverage-quiet is set, then
+ * Mirrors its own output to a log file when --coverage-quiet or --log-file is set, then
  * delegates all logic to `src/runner.mjs` via the programmatic `run()` API.
  */
 
@@ -23,7 +23,7 @@ if (args.help) {
 
 // Mirror all output (excluding progress bar lines) to a log file
 // when running in --coverage-quiet mode (or when --log-file is set).
-if (args.coverageQuiet || args.logFile) {
+if ((args.coverageQuiet || args.logFile) && !args.json) {
 	const cwd = process.cwd();
 	const resolvedLogFile = args.logFile
 		? path.isAbsolute(args.logFile)
@@ -62,25 +62,36 @@ if (args.coverageQuiet || args.logFile) {
 const cwd = process.cwd();
 
 const vitestArgs = [...args.vitestPassthroughArgs];
-if ((args.coverageQuiet || args.logFile) && !vitestArgs.some((a) => a === "--coverage" || a.startsWith("--coverage."))) {
+if (args.coverageQuiet && !vitestArgs.some((a) => a === "--coverage" || a.startsWith("--coverage."))) {
 	vitestArgs.unshift("--coverage");
 }
 
-run({
-	cwd,
-	testPatterns: args.testPatterns,
-	testListFile: args.testListFile,
-	testFilePattern: args.testFilePattern,
-	vitestArgs,
-	showErrorDetails: args.showErrorDetails,
-	coverageQuiet: args.coverageQuiet,
-	...(args.workers !== undefined && { workers: args.workers }),
-	...(args.soloPatterns.length > 0 && { earlyRunPatterns: args.soloPatterns })
-})
-	.then((code) => {
-		process.exit(code);
-	})
-	.catch((err) => {
-		console.error("Fatal error:", err);
-		process.exit(1);
+try {
+	const runResult = await run({
+		cwd,
+		testPatterns: args.testPatterns,
+		testListFile: args.testListFile,
+		testFilePattern: args.testFilePattern,
+		vitestArgs,
+		showErrorDetails: args.showErrorDetails,
+		coverageQuiet: args.coverageQuiet,
+		suppressFileOutput: args.suppressFileOutput,
+		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 })
 	});
+
+	if (args.json) {
+		process.stdout.write(`${JSON.stringify(runResult, null, 2)}\n`);
+		process.exit(typeof runResult === "object" && runResult !== null && "exitCode" in runResult ? runResult.exitCode : 1);
+	}
+
+	process.exit(typeof runResult === "number" ? runResult : 1);
+} catch (err) {
+	console.error("Fatal error:", err);
+	process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/vitest-runner",
-	"version": "1.0.3",
+	"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

@@ -9,6 +9,12 @@
  * @property {boolean} showErrorDetails - `false` when `--no-error-details` was passed.
  * @property {boolean} coverageQuiet - Whether `--coverage-quiet` was passed.
  * @property {string|undefined} logFile - Path for the coverage run log (`--log-file`); defaults to `coverage/coverage-run.log`.
+ * @property {boolean} suppressFileOutput - Suppress per-file runner output blocks (`--suppress-file-output`).
+ * @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).
@@ -23,6 +29,12 @@ const RUNNER_FLAGS = new Set([
 	"--no-error-details",
 	"--coverage-quiet",
 	"--log-file",
+	"--suppress-file-output",
+	"--suppress-passing-files",
+	"--no-top-summary",
+	"--json",
+	"--blobs-dir",
+	"--no-merge-reports",
 	"--workers",
 	"--solo-pattern",
 	"--file-pattern",
@@ -51,6 +63,12 @@ export function parseArguments(args) {
 	let showErrorDetails = true;
 	let coverageQuiet = false;
 	let logFile;
+	let suppressFileOutput = false;
+	let suppressPassingFiles = false;
+	let topSummary = true;
+	let json = false;
+	let blobsDir;
+	let mergeReports = true;
 	let workers;
 	let help = false;
 	let testFilePattern;
@@ -69,6 +87,20 @@ export function parseArguments(args) {
 			logFile = args[++i];
 		} else if (arg.startsWith("--log-file=")) {
 			logFile = arg.slice("--log-file=".length);
+		} else if (arg === "--suppress-file-output") {
+			suppressFileOutput = true;
+		} else if (arg === "--suppress-passing-files") {
+			suppressPassingFiles = true;
+		} else if (arg === "--no-top-summary") {
+			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=")) {
@@ -100,6 +132,12 @@ export function parseArguments(args) {
 		showErrorDetails,
 		coverageQuiet,
 		logFile,
+		suppressFileOutput,
+		suppressPassingFiles,
+		topSummary,
+		json,
+		blobsDir,
+		mergeReports,
 		help,
 		workers,
 		soloPatterns,

package/src/cli/help.mjs

@@ -21,12 +21,18 @@ ${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)
   --coverage-quiet        Implies --coverage; show progress bar + final summaries only
-  --log-file <path>       Path for the coverage run log (default: coverage/coverage-run.log; implies --coverage-quiet)
+  --log-file <path>       Path for mirrored runner output (default: coverage/coverage-run.log with --coverage-quiet)
+  --suppress-file-output  Suppress per-file runner output blocks
+  --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/core/report.mjs

@@ -150,9 +150,18 @@ export function computeSummaryFromFinal(finalData) {
  * @param {string} cwd - Project root (used to make absolute file paths relative).
  * @param {string[]} extraCoverageArgs - Passthrough `--coverage.*` args (checked for `reportsDirectory`).
  * @param {number} [worstCount=10] - Number of worst-coverage files to show (0 = skip table).
- * @returns {Promise<void>}
+ * @param {{silent?: boolean}} [options] - Output controls.
+ * @returns {Promise<{
+ *  coverageDir: string,
+ *  total: object,
+ *  worstFiles: Array<{file: string, lines: number, stmts: number, fns: number, branches: number}>,
+ *  worstFilesShown: number,
+ *  worstFilesTotal: number,
+ *  summary: object
+ * }|null>}
  */
-export async function printCoverageSummary(cwd, extraCoverageArgs, worstCount = 10) {
+export async function printCoverageSummary(cwd, extraCoverageArgs, worstCount = 10, options = {}) {
+	const { silent = false } = options;
 	let coverageDir = path.resolve(cwd, "coverage");
 	const repoDirArg = extraCoverageArgs.find((a) => a.startsWith("--coverage.reportsDirectory="));
 	if (repoDirArg) {
@@ -170,8 +179,8 @@ export async function printCoverageSummary(cwd, extraCoverageArgs, worstCount =
 			const content = await fs.readFile(path.join(coverageDir, "coverage-final.json"), "utf8");
 			summary = computeSummaryFromFinal(JSON.parse(content));
 		} catch {
-			console.log(chalk.dim("  (no coverage JSON found — skipping summary)"));
-			return;
+			if (!silent) console.log(chalk.dim("  (no coverage JSON found — skipping summary)"));
+			return null;
 		}
 	}
 
@@ -188,29 +197,59 @@ export async function printCoverageSummary(cwd, extraCoverageArgs, worstCount =
 			}))
 			.filter((r) => Math.min(r.lines, r.stmts, r.fns, r.branches) < 100)
 			.sort((a, b) => Math.min(a.lines, a.stmts, a.fns, a.branches) - Math.min(b.lines, b.stmts, b.fns, b.branches));
+		const rowsToShow = fileRows.slice(0, worstCount);
 
-		console.log("\n" + chalk.bold("📉 WORST COVERAGE FILES (lowest metric)"));
-		console.log("-".repeat(80));
+		if (!silent) {
+			console.log("\n" + chalk.bold("📉 WORST COVERAGE FILES (lowest metric)"));
+			console.log("-".repeat(80));
 
-		const rowsToShow = fileRows.slice(0, worstCount);
-		rowsToShow.forEach(({ file, lines, stmts, fns, branches }) => {
-			const worst = Math.min(lines, stmts, fns, branches);
-			const extras = chalk.dim(
-				`lines ${lines.toFixed(0)}% | stmts ${stmts.toFixed(0)}% | fns ${fns.toFixed(0)}% | branches ${branches.toFixed(0)}%`
-			);
-			console.log(`  ${colourPct(chalk, worst)}%  ${chalk.dim(file)}  ${extras}`);
-		});
+			rowsToShow.forEach(({ file, lines, stmts, fns, branches }) => {
+				const worst = Math.min(lines, stmts, fns, branches);
+				const extras = chalk.dim(
+					`lines ${lines.toFixed(0)}% | stmts ${stmts.toFixed(0)}% | fns ${fns.toFixed(0)}% | branches ${branches.toFixed(0)}%`
+				);
+				console.log(`  ${colourPct(chalk, worst)}%  ${chalk.dim(file)}  ${extras}`);
+			});
+
+			if (fileRows.length > worstCount) {
+				console.log(chalk.dim(`  ... and ${fileRows.length - worstCount} more files`));
+			}
+		}
 
-		if (fileRows.length > worstCount) {
-			console.log(chalk.dim(`  ... and ${fileRows.length - worstCount} more files`));
+		const tl = total.lines?.pct ?? 0;
+		const ts = total.statements?.pct ?? 0;
+		const tf = total.functions?.pct ?? 0;
+		const tb = total.branches?.pct ?? 0;
+		if (!silent) {
+			console.log(
+				`\n  ${chalk.bold("Coverage")}  ${colourPct(chalk, tl)}% lines ${chalk.dim("|")} ${colourPct(chalk, ts)}% statements ${chalk.dim("|")} ${colourPct(chalk, tf)}% functions ${chalk.dim("|")} ${colourPct(chalk, tb)}% branches`
+			);
 		}
+		return {
+			coverageDir,
+			total,
+			worstFiles: rowsToShow,
+			worstFilesShown: rowsToShow.length,
+			worstFilesTotal: fileRows.length,
+			summary
+		};
 	}
 
 	const tl = total.lines?.pct ?? 0;
 	const ts = total.statements?.pct ?? 0;
 	const tf = total.functions?.pct ?? 0;
 	const tb = total.branches?.pct ?? 0;
-	console.log(
-		`\n  ${chalk.bold("Coverage")}  ${colourPct(chalk, tl)}% lines ${chalk.dim("|")} ${colourPct(chalk, ts)}% statements ${chalk.dim("|")} ${colourPct(chalk, tf)}% functions ${chalk.dim("|")} ${colourPct(chalk, tb)}% branches`
-	);
+	if (!silent) {
+		console.log(
+			`\n  ${chalk.bold("Coverage")}  ${colourPct(chalk, tl)}% lines ${chalk.dim("|")} ${colourPct(chalk, ts)}% statements ${chalk.dim("|")} ${colourPct(chalk, tf)}% functions ${chalk.dim("|")} ${colourPct(chalk, tb)}% branches`
+		);
+	}
+	return {
+		coverageDir,
+		total,
+		worstFiles: [],
+		worstFilesShown: 0,
+		worstFilesTotal: 0,
+		summary
+	};
 }

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
@@ -55,8 +53,14 @@ import { colourPct } from "./utils/ansi.mjs";
  * @property {string[]} [vitestArgs=[]] - Extra CLI args forwarded verbatim to every vitest invocation.
  * @property {boolean} [showErrorDetails=true] - Print inline error blocks under each failed file.
  * @property {boolean} [coverageQuiet=false] - Suppress per-file output; show only progress bar + summaries.
+ * @property {boolean} [suppressFileOutput=false] - Suppress per-file runner output blocks in all modes.
+ * @property {boolean} [suppressPassingFiles=false] - Hide passed-file rows in the final summary.
+ * @property {boolean} [topSummary=true] - Show top memory and duration summary sections.
+ * @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.
@@ -96,7 +100,7 @@ function getHeapForFile(filePath, globalMaxMb, overrides) {
  * pool for the non-solo phase) and return an exit code.
  *
  * @param {RunOptions} opts
- * @returns {Promise<number>} `0` on full pass, `1` on any failure.
+ * @returns {Promise<number|object>} `0`/`1` by default; JSON report object when `opts.json` is true.
  */
 export async function run(opts) {
 	const {
@@ -108,8 +112,14 @@ export async function run(opts) {
 		vitestArgs: rawVitestArgs = [],
 		showErrorDetails = true,
 		coverageQuiet = false,
+		suppressFileOutput = false,
+		suppressPassingFiles = false,
+		topSummary = true,
+		json = false,
 		workers = parseInt(process.env.VITEST_WORKERS ?? "4", 10),
 		worstCoverageCount = 10,
+		blobsDir: blobsDirOpt,
+		mergeReports = true,
 		earlyRunPatterns = [],
 		perFileHeapOverrides = [],
 		conditions = [],
@@ -119,6 +129,7 @@ export async function run(opts) {
 	} = opts;
 
 	const maxOldSpaceMb = opts.maxOldSpaceMb ?? (process.env.VITEST_HEAP_MB ? parseInt(process.env.VITEST_HEAP_MB, 10) : undefined);
+	const emitTextOutput = !json;
 
 	// Resolve vitest binary and config
 	const vitestBin = resolveBin(cwd, "vitest", "vitest");
@@ -138,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");
@@ -149,9 +160,28 @@ export async function run(opts) {
 		const allTestFiles = await discoverVitestFiles({ cwd, testDir, testPatterns, testListFile, testFilePattern, earlyRunPatterns });
 
 		if (allTestFiles.length === 0) {
-			console.log(
-				testPatterns.length > 0 ? `❌ No Vitest test files found matching: ${testPatterns.join(", ")}` : "❌ No Vitest test files found"
-			);
+			const noTestsMessage =
+				testPatterns.length > 0 ? `❌ No Vitest test files found matching: ${testPatterns.join(", ")}` : "❌ No Vitest test files found";
+			if (emitTextOutput) console.log(noTestsMessage);
+			if (json) {
+				return {
+					exitCode: 1,
+					mode: "coverage",
+					message: noTestsMessage,
+					options: {
+						cwd,
+						testDir,
+						testPatterns,
+						testListFile,
+						workers,
+						coverageQuiet,
+						suppressFileOutput,
+						suppressPassingFiles,
+						topSummary,
+						vitestArgs
+					}
+				};
+			}
 			return 1;
 		}
 
@@ -161,15 +191,17 @@ export async function run(opts) {
 
 		const soloFiles = allTestFiles.filter((f) => earlyRunPatterns.some((p) => f.replace(/\\/g, "/").includes(p)));
 		const parallelFiles = allTestFiles.filter((f) => !earlyRunPatterns.some((p) => f.replace(/\\/g, "/").includes(p)));
+		const suppressPerFileCoverageOutput = coverageQuiet || suppressFileOutput || json;
+		const showCoverageProgress = coverageQuiet && !json;
 
-		if (!coverageQuiet) {
+		if (!coverageQuiet && !suppressFileOutput && emitTextOutput) {
 			console.log(`\n🧪 Running ${allTestFiles.length} test files for coverage (blob + merge mode)`);
 			console.log(`⚙️  Workers: ${workers} (${soloFiles.length} solo first, then parallel)`);
 			if (maxOldSpaceMb) console.log(`🧠 Heap limit: ${maxOldSpaceMb} MB`);
 			console.log("");
 		}
 
-		const progress = coverageQuiet ? createCoverageProgressTracker(allTestFiles.length) : noopProgressTracker;
+		const progress = showCoverageProgress ? createCoverageProgressTracker(allTestFiles.length) : noopProgressTracker;
 		const coverageResults = [];
 		let blobIndex = 0;
 
@@ -182,7 +214,7 @@ export async function run(opts) {
 			const blobPath = path.join(blobsDir, `run-${blobIndex}.blob`);
 			blobIndex++;
 
-			if (!coverageQuiet) {
+			if (!suppressPerFileCoverageOutput && emitTextOutput) {
 				console.log(`\n${"=".repeat(80)}`);
 				console.log(`▶️  ${filePath}`);
 				console.log("=".repeat(80));
@@ -204,13 +236,13 @@ export async function run(opts) {
 				...spawnBase,
 				maxOldSpaceMb: getHeapForFile(filePath, maxOldSpaceMb, perFileHeapOverrides),
 				vitestArgs: blobArgs,
-				streamOutput: !coverageQuiet
+				streamOutput: !suppressPerFileCoverageOutput
 			});
 
 			coverageResults.push(result);
 			progress.onComplete(result.code !== 0);
 
-			if (!coverageQuiet) {
+			if (!suppressPerFileCoverageOutput && emitTextOutput) {
 				const durationSec = (result.duration / 1000).toFixed(2);
 				if (result.code === 0) {
 					const heapInfo = result.heapMb ? ` | ${result.heapMb} MB heap` : "";
@@ -223,7 +255,9 @@ export async function run(opts) {
 
 		// Phase 1: solo files — one at a time
 		for (const filePath of soloFiles) {
-			await runCoverageFile(filePath).catch((err) => console.error(`Error running ${filePath}:`, err));
+			await runCoverageFile(filePath).catch((err) => {
+				if (emitTextOutput) console.error(`Error running ${filePath}:`, err);
+			});
 		}
 
 		// Phase 2: parallel files with worker pool
@@ -234,7 +268,9 @@ export async function run(opts) {
 			while (coverageFileIndex < parallelFiles.length && coverageActivePromises.size < workers) {
 				const filePath = parallelFiles[coverageFileIndex++];
 				const promise = runCoverageFile(filePath)
-					.catch((err) => console.error(`Error running ${filePath}:`, err))
+					.catch((err) => {
+						if (emitTextOutput) console.error(`Error running ${filePath}:`, err);
+					})
 					.finally(() => coverageActivePromises.delete(promise));
 				coverageActivePromises.add(promise);
 			}
@@ -246,48 +282,158 @@ export async function run(opts) {
 
 		const blobFiles = (await fs.readdir(blobsDir).catch(() => [])).filter((f) => f.endsWith(".blob"));
 		if (blobFiles.length === 0) {
-			console.error("❌ No coverage blobs were generated — coverage report cannot be produced");
+			const message = "❌ No coverage blobs were generated — coverage report cannot be produced";
+			if (emitTextOutput) console.error(message);
+			if (json) {
+				return {
+					exitCode: 1,
+					mode: "coverage",
+					message,
+					options: {
+						cwd,
+						testDir,
+						testPatterns,
+						testListFile,
+						workers,
+						coverageQuiet,
+						suppressFileOutput,
+						suppressPassingFiles,
+						topSummary,
+						showErrorDetails,
+						worstCoverageCount,
+						vitestArgs
+					},
+					totals: {
+						testFiles: allTestFiles.length,
+						failedFiles: coverageResults.filter((r) => r.code !== 0).length,
+						passedFiles: coverageResults.filter((r) => r.code === 0).length
+					},
+					results: {
+						all: coverageResults,
+						failed: coverageResults.filter((r) => r.code !== 0)
+					},
+					merge: {
+						blobFiles: 0,
+						exitCode: 1,
+						output: ""
+					},
+					coverageSummary: null
+				};
+			}
 			return 1;
 		}
 
-		if (!coverageQuiet) {
-			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
-		});
+		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) {
-			printMergeOutput(mergeExitCode, mergeOutput);
-		}
+			({ exitCode: mergeExitCode, output: mergeOutput } = await runMergeReports(blobsDir, {
+				...spawnBase,
+				maxOldSpaceMb,
+				extraCoverageArgs,
+				quietOutput: coverageQuiet || json
+			}));
+
+			if (coverageQuiet && emitTextOutput) {
+				printMergeOutput(mergeExitCode, mergeOutput);
+			}
 
-		await printCoverageSummary(cwd, extraCoverageArgs, worstCoverageCount);
+			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(() => {})
 		]);
 
 		const coverageFailed = coverageResults.filter((r) => r.code !== 0);
-		if (coverageQuiet) printQuietCoverageFailureDetails(coverageFailed);
+		if (coverageQuiet && emitTextOutput) printQuietCoverageFailureDetails(coverageFailed);
+
+		const exitCode = coverageFailed.length > 0 ? 1 : mergeExitCode;
+		if (json) {
+			const coverageWithHeap = coverageResults.filter((r) => r.heapMb !== null);
+			return {
+				exitCode,
+				mode: "coverage",
+				options: {
+					cwd,
+					testDir,
+					testPatterns,
+					testListFile,
+					workers,
+					coverageQuiet,
+					suppressFileOutput,
+					suppressPassingFiles,
+					topSummary,
+					showErrorDetails,
+					worstCoverageCount,
+					vitestArgs
+				},
+				totals: {
+					testFiles: allTestFiles.length,
+					failedFiles: coverageFailed.length,
+					passedFiles: coverageResults.length - coverageFailed.length
+				},
+				results: {
+					all: coverageResults,
+					failed: coverageFailed
+				},
+				merge: {
+					blobFiles: blobFiles.length,
+					exitCode: mergeExitCode,
+					output: mergeOutput
+				},
+				coverageSummary,
+				...(topSummary
+					? {
+							topMemoryUsers: [...coverageWithHeap].sort((a, b) => b.heapMb - a.heapMb).slice(0, 10),
+							topDuration: [...coverageResults].sort((a, b) => b.duration - a.duration).slice(0, 10)
+						}
+					: {})
+			};
+		}
 
-		return coverageFailed.length > 0 ? 1 : mergeExitCode;
+		return exitCode;
 	}
 
 	// ─── STANDARD (NON-COVERAGE) MODE ────────────────────────────────────────────
 	const testFiles = await discoverVitestFiles({ cwd, testDir, testPatterns, testListFile, testFilePattern, earlyRunPatterns });
 
 	if (testFiles.length === 0) {
-		console.log(
-			testPatterns.length > 0 ? `❌ No Vitest test files found matching: ${testPatterns.join(", ")}` : "❌ No Vitest test files found"
-		);
+		const noTestsMessage =
+			testPatterns.length > 0 ? `❌ No Vitest test files found matching: ${testPatterns.join(", ")}` : "❌ No Vitest test files found";
+		if (emitTextOutput) console.log(noTestsMessage);
+		if (json) {
+			return {
+				exitCode: 1,
+				mode: "standard",
+				message: noTestsMessage,
+				options: {
+					cwd,
+					testDir,
+					testPatterns,
+					testListFile,
+					workers,
+					coverageQuiet,
+					suppressFileOutput,
+					suppressPassingFiles,
+					topSummary,
+					vitestArgs
+				}
+			};
+		}
 		return 1;
 	}
 
@@ -297,15 +443,17 @@ export async function run(opts) {
 	const scriptStartTime = Date.now();
 	const scriptStartTimeFormatted = new Date().toLocaleTimeString("en-US", { hour12: false });
 
-	if (testPatterns.length > 0) {
+	if (emitTextOutput && !suppressFileOutput && testPatterns.length > 0) {
 		console.log(`\n🧪 Running ${testFiles.length} test files matching: ${testPatterns.join(", ")}`);
-	} else {
+	} else if (emitTextOutput && !suppressFileOutput) {
 		console.log(`\n🧪 Running ${testFiles.length} test files (${soloFiles.length} solo first, then parallel)`);
 	}
-	console.log(`⚙️  Workers: ${workers}`);
-	if (maxOldSpaceMb) console.log(`🧠 Heap limit: ${maxOldSpaceMb} MB`);
-	if (vitestArgs.length > 0) console.log(`🔧 Vitest args: ${vitestArgs.join(" ")}`);
-	console.log("");
+	if (emitTextOutput && !suppressFileOutput) {
+		console.log(`⚙️  Workers: ${workers}`);
+		if (maxOldSpaceMb) console.log(`🧠 Heap limit: ${maxOldSpaceMb} MB`);
+		if (vitestArgs.length > 0) console.log(`🔧 Vitest args: ${vitestArgs.join(" ")}`);
+		console.log("");
+	}
 
 	const results = [...(_testResultsOverride ?? [])];
 
@@ -315,22 +463,27 @@ export async function run(opts) {
 	 * @returns {Promise<import('./core/spawn.mjs').SingleFileResult>}
 	 */
 	const runTestFile = async (filePath) => {
-		console.log(`\n${"=".repeat(80)}`);
-		console.log(`▶️  ${filePath}`);
-		console.log("=".repeat(80));
+		if (!suppressFileOutput && emitTextOutput) {
+			console.log(`\n${"=".repeat(80)}`);
+			console.log(`▶️  ${filePath}`);
+			console.log("=".repeat(80));
+		}
 
 		const result = await runSingleFile(filePath, {
 			...spawnBase,
 			maxOldSpaceMb: getHeapForFile(filePath, maxOldSpaceMb, perFileHeapOverrides),
-			vitestArgs
+			vitestArgs,
+			streamOutput: !suppressFileOutput && !json
 		});
 
-		const durationSec = (result.duration / 1000).toFixed(2);
-		if (result.code === 0) {
-			const heapInfo = result.heapMb ? ` | ${result.heapMb} MB heap` : "";
-			console.log(`\n✅ PASSED (${durationSec}s${heapInfo})\n`);
-		} else {
-			console.log(`\n❌ FAILED (exit code ${result.code}, ${durationSec}s)\n`);
+		if (!suppressFileOutput && emitTextOutput) {
+			const durationSec = (result.duration / 1000).toFixed(2);
+			if (result.code === 0) {
+				const heapInfo = result.heapMb ? ` | ${result.heapMb} MB heap` : "";
+				console.log(`\n✅ PASSED (${durationSec}s${heapInfo})\n`);
+			} else {
+				console.log(`\n❌ FAILED (exit code ${result.code}, ${durationSec}s)\n`);
+			}
 		}
 
 		return result;
@@ -340,7 +493,7 @@ export async function run(opts) {
 		// Phase 1: solo files
 		for (const filePath of soloFiles) {
 			const result = await runTestFile(filePath).catch((err) => {
-				console.error(`Error running ${filePath}:`, err);
+				if (emitTextOutput) console.error(`Error running ${filePath}:`, err);
 				return null;
 			});
 			if (result) results.push(result);
@@ -355,7 +508,9 @@ export async function run(opts) {
 				const filePath = parallelFiles[index++];
 				const promise = runTestFile(filePath)
 					.then((result) => results.push(result))
-					.catch((err) => console.error(`Error running ${filePath}:`, err))
+					.catch((err) => {
+						if (emitTextOutput) console.error(`Error running ${filePath}:`, err);
+					})
 					.finally(() => activePromises.delete(promise));
 				activePromises.add(promise);
 			}
@@ -373,12 +528,69 @@ export async function run(opts) {
 	const totalDuration = results.reduce((s, r) => s + r.duration, 0);
 	const failedFiles = results.filter((r) => r.code !== 0);
 	const passedFiles = results.filter((r) => r.code === 0);
+	const exitCode = failedFiles.length > 0 ? 1 : 0;
+	const scriptMemory = process.memoryUsage();
+	const scriptHeapMb = Math.round(scriptMemory.heapUsed / 1024 / 1024);
+	const scriptRssMb = Math.round(scriptMemory.rss / 1024 / 1024);
+	const withHeap = results.filter((r) => r.heapMb !== null);
+	const actualDurationSec = ((Date.now() - scriptStartTime) / 1000).toFixed(2);
+	const testsDurationSec = (totalDuration / 1000).toFixed(2);
+
+	if (json) {
+		return {
+			exitCode,
+			mode: "standard",
+			options: {
+				cwd,
+				testDir,
+				testPatterns,
+				testListFile,
+				workers,
+				coverageQuiet,
+				suppressFileOutput,
+				suppressPassingFiles,
+				topSummary,
+				showErrorDetails,
+				worstCoverageCount,
+				vitestArgs
+			},
+			totals: {
+				testFilesPass: totalTestFilesPass,
+				testFilesFail: totalTestFilesFail,
+				testsPass: totalTestsPass,
+				testsFail: totalTestsFail,
+				testsSkip: totalTestsSkip,
+				totalTests: totalTestsPass + totalTestsFail + totalTestsSkip
+			},
+			timing: {
+				startAt: scriptStartTimeFormatted,
+				wallClockSeconds: Number(actualDurationSec),
+				testsSeconds: Number(testsDurationSec)
+			},
+			heap: {
+				scriptHeapMb,
+				scriptRssMb,
+				maxHeapMb: withHeap.length > 0 ? Math.max(...withHeap.map((r) => r.heapMb)) : null,
+				avgHeapMb: withHeap.length > 0 ? Number((withHeap.reduce((sum, r) => sum + r.heapMb, 0) / withHeap.length).toFixed(0)) : null
+			},
+			results: {
+				all: results,
+				passed: passedFiles,
+				failed: failedFiles
+			},
+			...(topSummary
+				? {
+						topMemoryUsers: [...withHeap].sort((a, b) => b.heapMb - a.heapMb).slice(0, 10),
+						topDuration: [...results].sort((a, b) => b.duration - a.duration).slice(0, 10)
+					}
+				: {})
+		};
+	}
 
 	console.log("\n" + "=".repeat(80));
 
 	// Top memory users
-	const withHeap = results.filter((r) => r.heapMb !== null);
-	if (withHeap.length > 0) {
+	if (topSummary && withHeap.length > 0) {
 		console.log("\n" + chalk.bold("🧠 TOP MEMORY USERS"));
 		console.log("-".repeat(80));
 		[...withHeap]
@@ -390,7 +602,7 @@ export async function run(opts) {
 	}
 
 	// Top duration
-	if (results.length > 0) {
+	if (topSummary && results.length > 0) {
 		console.log("\n" + chalk.bold("⏱️  TOP DURATION"));
 		console.log("-".repeat(80));
 		[...results]
@@ -403,7 +615,7 @@ export async function run(opts) {
 	}
 
 	// Passed files
-	if (passedFiles.length > 0) {
+	if (passedFiles.length > 0 && !suppressPassingFiles) {
 		console.log("\n" + "=".repeat(80));
 		console.log(chalk.bold.green("✓ PASSED TEST FILES"));
 		console.log("=".repeat(80));
@@ -468,13 +680,8 @@ export async function run(opts) {
 	console.log(`      ${chalk.bold("Tests")}  ${testsParts.join(` ${chalk.dim("|")} `)} ${chalk.dim(`(${totalTests})`)}`);
 	console.log(`   ${chalk.bold("Start at")}  ${scriptStartTimeFormatted}`);
 
-	const actualDurationSec = ((Date.now() - scriptStartTime) / 1000).toFixed(2);
-	const testsDurationSec = (totalDuration / 1000).toFixed(2);
 	console.log(`   ${chalk.bold("Duration")}  ${actualDurationSec}s ${chalk.dim(`(tests ${testsDurationSec}s)`)}`);
 
-	const scriptMemory = process.memoryUsage();
-	const scriptHeapMb = Math.round(scriptMemory.heapUsed / 1024 / 1024);
-	const scriptRssMb = Math.round(scriptMemory.rss / 1024 / 1024);
 	if (withHeap.length > 0) {
 		const maxHeap = Math.max(...withHeap.map((r) => r.heapMb));
 		const avgHeap = (withHeap.reduce((s, r) => s + r.heapMb, 0) / withHeap.length).toFixed(0);
@@ -483,9 +690,7 @@ export async function run(opts) {
 		console.log(`       ${chalk.bold("Heap")}  script ${scriptHeapMb} MB (RSS ${scriptRssMb} MB)`);
 	}
 
-	if (failedFiles.length > 0) {
-		return 1;
-	}
+	if (failedFiles.length > 0) return 1;
 
 	console.log(`\n✅ All ${passedFiles.length} test files passed\n`);
 	return 0;

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

@@ -29,6 +29,30 @@ export type ParsedArgs = {
      * - Path for the coverage run log (`--log-file`); defaults to `coverage/coverage-run.log`.
      */
     logFile: string | undefined;
+    /**
+     * - Suppress per-file runner output blocks (`--suppress-file-output`).
+     */
+    suppressFileOutput: boolean;
+    /**
+     * - Suppress the passed-files section in the final summary (`--suppress-passing-files`).
+     */
+    suppressPassingFiles: boolean;
+    /**
+     * - Show top-summary sections for memory and duration (`true` by default, disabled by `--no-top-summary`).
+     */
+    topSummary: boolean;
+    /**
+     * - 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/core/report.d.mts

@@ -42,6 +42,29 @@ export function computeSummaryFromFinal(finalData: Record<string, object>): {
  * @param {string} cwd - Project root (used to make absolute file paths relative).
  * @param {string[]} extraCoverageArgs - Passthrough `--coverage.*` args (checked for `reportsDirectory`).
  * @param {number} [worstCount=10] - Number of worst-coverage files to show (0 = skip table).
- * @returns {Promise<void>}
+ * @param {{silent?: boolean}} [options] - Output controls.
+ * @returns {Promise<{
+ *  coverageDir: string,
+ *  total: object,
+ *  worstFiles: Array<{file: string, lines: number, stmts: number, fns: number, branches: number}>,
+ *  worstFilesShown: number,
+ *  worstFilesTotal: number,
+ *  summary: object
+ * }|null>}
  */
-export function printCoverageSummary(cwd: string, extraCoverageArgs: string[], worstCount?: number): Promise<void>;
+export function printCoverageSummary(cwd: string, extraCoverageArgs: string[], worstCount?: number, options?: {
+    silent?: boolean;
+}): Promise<{
+    coverageDir: string;
+    total: object;
+    worstFiles: Array<{
+        file: string;
+        lines: number;
+        stmts: number;
+        fns: number;
+        branches: number;
+    }>;
+    worstFilesShown: number;
+    worstFilesTotal: number;
+    summary: object;
+} | null>;

package/types/src/runner.d.mts

@@ -3,9 +3,9 @@
  * pool for the non-solo phase) and return an exit code.
  *
  * @param {RunOptions} opts
- * @returns {Promise<number>} `0` on full pass, `1` on any failure.
+ * @returns {Promise<number|object>} `0`/`1` by default; JSON report object when `opts.json` is true.
  */
-export function run(opts: RunOptions): Promise<number>;
+export function run(opts: RunOptions): Promise<number | object>;
 export { formatDuration } from "./utils/duration.mjs";
 export { buildNodeOptions } from "./utils/env.mjs";
 export type PerFileHeapOverride = {
@@ -55,6 +55,22 @@ export type RunOptions = {
      * - Suppress per-file output; show only progress bar + summaries.
      */
     coverageQuiet?: boolean;
+    /**
+     * - Suppress per-file runner output blocks in all modes.
+     */
+    suppressFileOutput?: boolean;
+    /**
+     * - Hide passed-file rows in the final summary.
+     */
+    suppressPassingFiles?: boolean;
+    /**
+     * - Show top memory and duration summary sections.
+     */
+    topSummary?: boolean;
+    /**
+     * - Return a JSON run report instead of printing text output.
+     */
+    json?: boolean;
     /**
      * - Maximum number of parallel worker slots.
      */
@@ -63,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.
      */