vitest 3.2.0-beta.2 → 3.2.0-beta.3

package/dist/chunks/{coverage.OGU09Jbh.js → coverage.C73DaDgS.js}

@@ -2,27 +2,27 @@ import fs, { statSync, realpathSync, promises as promises$1, mkdirSync, existsSy
 import { relative, resolve, dirname, isAbsolute, join as join$1, normalize } from 'pathe';
 import pm from 'picomatch';
 import c from 'tinyrainbow';
-import { c as configDefaults, e as benchmarkConfigDefaults, a as coverageConfigDefaults } from './defaults.DSxsTG0h.js';
+import { c as configDefaults, e as benchmarkConfigDefaults, a as coverageConfigDefaults } from './defaults.DpVH7vbg.js';
 import crypto from 'node:crypto';
 import { slash, createDefer, shuffle, toArray } from '@vitest/utils';
 import { builtinModules, createRequire } from 'node:module';
 import path, { win32, dirname as dirname$1, join, resolve as resolve$1 } from 'node:path';
 import process$1 from 'node:process';
-import fsPromises, { writeFile, rename, stat, unlink } from 'node:fs/promises';
+import fs$1, { writeFile, rename, stat, unlink } from 'node:fs/promises';
 import { fileURLToPath as fileURLToPath$1, pathToFileURL as pathToFileURL$1, URL as URL$1 } from 'node:url';
 import assert from 'node:assert';
 import v8 from 'node:v8';
 import { format, inspect } from 'node:util';
-import { e as extraInlineDeps, d as defaultBrowserPort, b as defaultInspectPort, a as defaultPort } from './constants.BZZyIeIE.js';
+import { version, mergeConfig } from 'vite';
+import { e as extraInlineDeps, d as defaultBrowserPort, b as defaultInspectPort, a as defaultPort } from './constants.DnKduX2e.js';
 import { a as isWindows } from './env.Dq0hM4Xv.js';
 import * as nodeos from 'node:os';
 import nodeos__default from 'node:os';
 import { isatty } from 'node:tty';
-import { version } from 'vite';
 import EventEmitter from 'node:events';
 import { c as createBirpc } from './index.CJ0plNrh.js';
 import Tinypool$1, { Tinypool } from 'tinypool';
-import { w as wrapSerializableConfig, a as Typechecker } from './typechecker.DnTrplSJ.js';
+import { w as wrapSerializableConfig, a as Typechecker } from './typechecker.BgzF-6iO.js';
 import { MessageChannel } from 'node:worker_threads';
 import { hasFailed } from '@vitest/runner/utils';
 import { rootDir } from '../path.js';
@@ -39,9 +39,12 @@ function groupBy(collection, iteratee) {
 	}, {});
 }
 function stdout() {
+	// @ts-expect-error Node.js maps process.stdout to console._stdout
+	// eslint-disable-next-line no-console
 	return console._stdout || process.stdout;
 }
 function escapeRegExp(s) {
+	// From https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
 	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function wildcardPatternToRegExp(pattern) {
@@ -116,7 +119,9 @@ class ResultsCache {
 		}
 		const resultsCache = await fs.promises.readFile(this.cachePath, "utf8");
 		const { results, version } = JSON.parse(resultsCache || "[]");
-		if (Number(version.split(".")[1]) >= 30) {
+		const [major, minor] = version.split(".");
+		// handling changed in 0.30.0
+		if (major > 0 || Number(minor) >= 30) {
 			this.cache = new Map(results);
 			this.version = version;
 			results.forEach(([spec]) => {
@@ -134,6 +139,7 @@ class ResultsCache {
 				return;
 			}
 			const duration = result.duration || 0;
+			// store as relative, so cache would be the same in CI and locally
 			const relativePath = relative(this.root, file.filepath);
 			this.cache.set(`${file.projectName || ""}:${relativePath}`, {
 				duration: duration >= 0 ? duration : 0,
@@ -2363,7 +2369,7 @@ async function findUp$1(name, {
 	while (directory) {
 		const filePath = isAbsoluteName ? name : path.join(directory, name);
 		try {
-			const stats = await fsPromises.stat(filePath); // eslint-disable-line no-await-in-loop
+			const stats = await fs$1.stat(filePath); // eslint-disable-line no-await-in-loop
 			if ((type === 'file' && stats.isFile()) || (type === 'directory' && stats.isDirectory())) {
 				return filePath;
 			}
@@ -2528,7 +2534,9 @@ function getTransformMode(patterns, filename) {
 async function groupFilesByEnv(files) {
 	const filesWithEnv = await Promise.all(files.map(async ({ moduleId: filepath, project, testLines }) => {
 		const code = await promises$1.readFile(filepath, "utf-8");
+		// 1. Check for control comments in the file
 		let env = code.match(/@(?:vitest|jest)-environment\s+([\w-]+)\b/)?.[1];
+		// 2. Check for globals
 		if (!env) {
 			for (const [glob, target] of project.config.environmentMatchGlobs || []) {
 				if (pm.isMatch(filepath, glob, { cwd: project.config.root })) {
@@ -2537,10 +2545,12 @@ async function groupFilesByEnv(files) {
 				}
 			}
 		}
+		// 3. Fallback to global env
 		env ||= project.config.environment || "node";
 		const transformMode = getTransformMode(project.config.testTransformMode, filepath);
 		let envOptionsJson = code.match(/@(?:vitest|jest)-environment-options\s+(.+)/)?.[1];
 		if (envOptionsJson?.endsWith("*/")) {
+			// Trim closing Docblock characters the above regex might have captured
 			envOptionsJson = envOptionsJson.slice(0, -2);
 		}
 		const envOptions = JSON.parse(envOptionsJson || "null");
@@ -2660,8 +2670,10 @@ function createMethodsRPC(project, options = {}) {
 		}
 	};
 }
+// serialize rollup error on server to preserve details as a test error
 function handleRollupError(e) {
 	if (e instanceof Error && ("plugin" in e || "frame" in e || "id" in e)) {
+		// eslint-disable-next-line no-throw-literal
 		throw {
 			name: e.name,
 			message: e.message,
@@ -2790,6 +2802,7 @@ function createForksPool(ctx, { execArgv, env }) {
 					channel
 				});
 			} catch (error) {
+				// Worker got stuck and won't terminate - this may cause process to hang
 				if (error instanceof Error && /Failed to terminate worker/.test(error.message)) {
 					ctx.state.addProcessTimeoutCause(`Failed to terminate worker while running ${paths.join(", ")}.`);
 				} else if (ctx.isCancelling && error instanceof Error && /The task has been cancelled/.test(error.message)) {
@@ -2802,6 +2815,7 @@ function createForksPool(ctx, { execArgv, env }) {
 			}
 		}
 		return async (specs, invalidates) => {
+			// Cancel pending tasks from pool when possible
 			ctx.onCancel(() => pool.cancelPendingTasks());
 			const configs = new WeakMap();
 			const getConfig = (project) => {
@@ -2822,9 +2836,14 @@ function createForksPool(ctx, { execArgv, env }) {
 				if (isolated) {
 					results.push(...await Promise.allSettled(files.map(({ file, environment, project }) => runFiles(project, getConfig(project), [file], environment, invalidates))));
 				} else {
+					// When isolation is disabled, we still need to isolate environments and workspace projects from each other.
+					// Tasks are still running parallel but environments are isolated between tasks.
 					const grouped = groupBy(files, ({ project, environment }) => project.name + environment.name + JSON.stringify(environment.options));
 					for (const group of Object.values(grouped)) {
+						// Push all files to pool's queue
 						results.push(...await Promise.allSettled(group.map(({ file, environment, project }) => runFiles(project, getConfig(project), [file], environment, invalidates))));
+						// Once all tasks are running or finished, recycle worker for isolation.
+						// On-going workers will run in the previous environment.
 						await new Promise((resolve) => pool.queueSize === 0 ? resolve() : pool.once("drain", resolve));
 						await pool.recycleWorkers();
 					}
@@ -2844,6 +2863,7 @@ function createForksPool(ctx, { execArgv, env }) {
 					}
 					const filesByOptions = groupBy(files, ({ project, environment }) => project.name + JSON.stringify(environment.options));
 					for (const files of Object.values(filesByOptions)) {
+						// Always run environments isolated between each other
 						await pool.recycleWorkers();
 						const filenames = files.map((f) => f.file);
 						await runFiles(files[0].project, getConfig(files[0].project), filenames, files[0].environment, invalidates);
@@ -2933,6 +2953,7 @@ function createThreadsPool(ctx, { execArgv, env }) {
 					name
 				});
 			} catch (error) {
+				// Worker got stuck and won't terminate - this may cause process to hang
 				if (error instanceof Error && /Failed to terminate worker/.test(error.message)) {
 					ctx.state.addProcessTimeoutCause(`Failed to terminate worker while running ${paths.join(", ")}. \nSee https://vitest.dev/guide/common-errors.html#failed-to-terminate-worker for troubleshooting.`);
 				} else if (ctx.isCancelling && error instanceof Error && /The task has been cancelled/.test(error.message)) {
@@ -2946,6 +2967,7 @@ function createThreadsPool(ctx, { execArgv, env }) {
 			}
 		}
 		return async (specs, invalidates) => {
+			// Cancel pending tasks from pool when possible
 			ctx.onCancel(() => pool.cancelPendingTasks());
 			const configs = new WeakMap();
 			const getConfig = (project) => {
@@ -2965,9 +2987,14 @@ function createThreadsPool(ctx, { execArgv, env }) {
 				if (isolated) {
 					results.push(...await Promise.allSettled(files.map(({ file, environment, project }) => runFiles(project, getConfig(project), [file], environment, invalidates))));
 				} else {
+					// When isolation is disabled, we still need to isolate environments and workspace projects from each other.
+					// Tasks are still running parallel but environments are isolated between tasks.
 					const grouped = groupBy(files, ({ project, environment }) => project.name + environment.name + JSON.stringify(environment.options));
 					for (const group of Object.values(grouped)) {
+						// Push all files to pool's queue
 						results.push(...await Promise.allSettled(group.map(({ file, environment, project }) => runFiles(project, getConfig(project), [file], environment, invalidates))));
+						// Once all tasks are running or finished, recycle worker for isolation.
+						// On-going workers will run in the previous environment.
 						await new Promise((resolve) => pool.queueSize === 0 ? resolve() : pool.once("drain", resolve));
 						await pool.recycleWorkers();
 					}
@@ -2987,6 +3014,7 @@ function createThreadsPool(ctx, { execArgv, env }) {
 					}
 					const filesByOptions = groupBy(files, ({ project, environment }) => project.name + JSON.stringify(environment.options));
 					for (const files of Object.values(filesByOptions)) {
+						// Always run environments isolated between each other
 						await pool.recycleWorkers();
 						const filenames = files.map((f) => f.file);
 						await runFiles(files[0].project, getConfig(files[0].project), filenames, files[0].environment, invalidates);
@@ -3021,6 +3049,7 @@ function createTypecheckPool(vitest) {
 		}
 		promisesMap.get(project)?.resolve();
 		rerunTriggered.delete(project);
+		// triggered by TSC watcher, not Vitest watcher, so we need to emulate what Vitest does in this case
 		if (vitest.config.watch && !vitest.runningPromise) {
 			await vitest.report("onFinished", files, []);
 			await vitest.report("onWatcherStart", files, [...project.config.typecheck.ignoreSourceErrors ? [] : sourceErrors, ...vitest.state.getUnhandledErrors()]);
@@ -3060,7 +3089,7 @@ function createTypecheckPool(vitest) {
 	}
 	async function startTypechecker(project, files) {
 		if (project.typechecker) {
-			return project.typechecker;
+			return;
 		}
 		const checker = await createWorkspaceTypechecker(project, files);
 		await checker.collectTests();
@@ -3085,6 +3114,7 @@ function createTypecheckPool(vitest) {
 			const project = specsByProject[name][0].project;
 			const files = specsByProject[name].map((spec) => spec.moduleId);
 			const promise = createDefer();
+			// check that watcher actually triggered rerun
 			const _p = new Promise((resolve) => {
 				const _i = setInterval(() => {
 					if (!project.typechecker || rerunTriggered.has(project)) {
@@ -3109,7 +3139,7 @@ function createTypecheckPool(vitest) {
 			}
 			promises.push(promise);
 			promisesMap.set(project, promise);
-			startTypechecker(project, files);
+			promises.push(startTypechecker(project, files));
 		}
 		await Promise.all(promises);
 	}
@@ -3285,6 +3315,7 @@ function createVmForksPool(ctx, { execArgv, env }) {
 					channel
 				});
 			} catch (error) {
+				// Worker got stuck and won't terminate - this may cause process to hang
 				if (error instanceof Error && /Failed to terminate worker/.test(error.message)) {
 					ctx.state.addProcessTimeoutCause(`Failed to terminate worker while running ${paths.join(", ")}.`);
 				} else if (ctx.isCancelling && error instanceof Error && /The task has been cancelled/.test(error.message)) {
@@ -3297,6 +3328,7 @@ function createVmForksPool(ctx, { execArgv, env }) {
 			}
 		}
 		return async (specs, invalidates) => {
+			// Cancel pending tasks from pool when possible
 			ctx.onCancel(() => pool.cancelPendingTasks());
 			const configs = new Map();
 			const getConfig = (project) => {
@@ -3330,9 +3362,11 @@ function getMemoryLimit$1(config) {
 	if (typeof memory === "number") {
 		return stringToBytes(limit, config.watch ? memory / 2 : memory);
 	}
+	// If totalmem is not supported we cannot resolve percentage based values like 0.5, "50%"
 	if (typeof limit === "number" && limit > 1 || typeof limit === "string" && limit.at(-1) !== "%") {
 		return stringToBytes(limit);
 	}
+	// just ignore "memoryLimit" value because we cannot detect memory limit
 	return null;
 }
 
@@ -3414,6 +3448,7 @@ function createVmThreadsPool(ctx, { execArgv, env }) {
 					name
 				});
 			} catch (error) {
+				// Worker got stuck and won't terminate - this may cause process to hang
 				if (error instanceof Error && /Failed to terminate worker/.test(error.message)) {
 					ctx.state.addProcessTimeoutCause(`Failed to terminate worker while running ${paths.join(", ")}. \nSee https://vitest.dev/guide/common-errors.html#failed-to-terminate-worker for troubleshooting.`);
 				} else if (ctx.isCancelling && error instanceof Error && /The task has been cancelled/.test(error.message)) {
@@ -3427,6 +3462,7 @@ function createVmThreadsPool(ctx, { execArgv, env }) {
 			}
 		}
 		return async (specs, invalidates) => {
+			// Cancel pending tasks from pool when possible
 			ctx.onCancel(() => pool.cancelPendingTasks());
 			const configs = new Map();
 			const getConfig = (project) => {
@@ -3459,9 +3495,11 @@ function getMemoryLimit(config) {
 	if (typeof memory === "number") {
 		return stringToBytes(limit, config.watch ? memory / 2 : memory);
 	}
+	// If totalmem is not supported we cannot resolve percentage based values like 0.5, "50%"
 	if (typeof limit === "number" && limit > 1 || typeof limit === "string" && limit.at(-1) !== "%") {
 		return stringToBytes(limit);
 	}
+	// just ignore "memoryLimit" value because we cannot detect memory limit
 	return null;
 }
 
@@ -3499,6 +3537,8 @@ function createPool(ctx) {
 		vmForks: null,
 		typescript: null
 	};
+	// in addition to resolve.conditions Vite also adds production/development,
+	// see: https://github.com/vitejs/vite/blob/af2aa09575229462635b7cbb6d248ca853057ba2/packages/vite/src/node/plugins/resolve.ts#L1056-L1080
 	const viteMajor = Number(version.split(".")[0]);
 	const potentialConditions = new Set(viteMajor >= 6 ? ctx.vite.config.ssr.resolve?.conditions ?? [] : [
 		"production",
@@ -3519,6 +3559,8 @@ function createPool(ctx) {
 		}
 		return condition;
 	}).flatMap((c) => ["--conditions", c]);
+	// Instead of passing whole process.execArgv to the workers, pick allowed options.
+	// Some options may crash worker, e.g. --prof, --title. nodejs/node#41103
 	const execArgv = process.execArgv.filter((execArg) => execArg.startsWith("--cpu-prof") || execArg.startsWith("--heap-prof") || execArg.startsWith("--diagnostic-dir"));
 	async function executeTests(method, files, invalidate) {
 		const options = {
@@ -3533,6 +3575,7 @@ function createPool(ctx) {
 				...ctx.config.env
 			}
 		};
+		// env are case-insensitive on Windows, but spawned processes don't support it
 		if (isWindows) {
 			for (const name in options.env) {
 				options.env[name.toUpperCase()] = options.env[name];
@@ -3654,6 +3697,7 @@ class BaseSequencer {
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
+	// async so it can be extended by other sequelizers
 	async shard(files) {
 		const { config } = this.ctx;
 		const { index, count } = config.shard;
@@ -3669,6 +3713,7 @@ class BaseSequencer {
 			};
 		}).sort((a, b) => a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0).slice(shardStart, shardEnd).map(({ spec }) => spec);
 	}
+	// async so it can be extended by other sequelizers
 	async sort(files) {
 		const cache = this.ctx.cache;
 		return [...files].sort((a, b) => {
@@ -3679,17 +3724,21 @@ class BaseSequencer {
 			if (!aState || !bState) {
 				const statsA = cache.getFileStats(keyA);
 				const statsB = cache.getFileStats(keyB);
+				// run unknown first
 				if (!statsA || !statsB) {
 					return !statsA && statsB ? -1 : !statsB && statsA ? 1 : 0;
 				}
+				// run larger files first
 				return statsB.size - statsA.size;
 			}
+			// run failed first
 			if (aState.failed && !bState.failed) {
 				return -1;
 			}
 			if (!aState.failed && bState.failed) {
 				return 1;
 			}
+			// run longer first
 			return bState.duration - aState.duration;
 		});
 	}
@@ -3824,9 +3873,10 @@ function resolveConfig$1(vitest, options, viteConfig) {
 	if (resolved.minWorkers) {
 		resolved.minWorkers = resolveInlineWorkerOption(resolved.minWorkers);
 	}
-	resolved.browser ??= {};
+	// run benchmark sequentially by default
 	resolved.fileParallelism ??= mode !== "benchmark";
 	if (!resolved.fileParallelism) {
+		// ignore user config, parallelism cannot be implemented without limiting workers
 		resolved.maxWorkers = 1;
 		resolved.minWorkers = 1;
 	}
@@ -3842,13 +3892,19 @@ function resolveConfig$1(vitest, options, viteConfig) {
 			throw new Error(`You cannot use ${inspectOption} without "--no-file-parallelism", "poolOptions.threads.singleThread" or "poolOptions.forks.singleFork"`);
 		}
 	}
+	// apply browser CLI options only if the config already has the browser config and not disabled manually
+	if (vitest._cliOptions.browser && resolved.browser && (resolved.browser.enabled !== false || vitest._cliOptions.browser.enabled)) {
+		resolved.browser = mergeConfig(resolved.browser, vitest._cliOptions.browser);
+	}
+	resolved.browser ??= {};
 	const browser = resolved.browser;
-	if (browser.enabled && viteConfig.test?.browser) {
+	if (browser.enabled) {
 		if (!browser.name && !browser.instances) {
 			throw new Error(`Vitest Browser Mode requires "browser.name" (deprecated) or "browser.instances" options, none were set.`);
 		}
 		const instances = browser.instances;
 		if (browser.name && browser.instances) {
+			// --browser=chromium filters configs to a single one
 			browser.instances = browser.instances.filter((instance) => instance.browser === browser.name);
 		}
 		if (browser.instances && !browser.instances.length) {
@@ -3856,6 +3912,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 		}
 	}
 	const playwrightChromiumOnly = isPlaywrightChromiumOnly(vitest, resolved);
+	// Browser-mode "Playwright + Chromium" only features:
 	if (browser.enabled && !playwrightChromiumOnly) {
 		const browserConfig = { browser: {
 			provider: browser.provider,
@@ -3912,6 +3969,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 	resolved.deps.web.transformGlobPattern ??= [];
 	resolved.setupFiles = toArray(resolved.setupFiles || []).map((file) => resolvePath(file, resolved.root));
 	resolved.globalSetup = toArray(resolved.globalSetup || []).map((file) => resolvePath(file, resolved.root));
+	// override original exclude array for cases where user re-uses same object in test.exclude
 	resolved.coverage.exclude = [
 		...resolved.coverage.exclude,
 		...resolved.setupFiles.map((file) => `${resolved.coverage.allowExternal ? "**/" : ""}${relative(resolved.root, file)}`),
@@ -3942,6 +4000,8 @@ function resolveConfig$1(vitest, options, viteConfig) {
 	if (resolved.cliExclude) {
 		resolved.exclude.push(...resolved.cliExclude);
 	}
+	// vitenode will try to import such file with native node,
+	// but then our mocker will not work properly
 	if (resolved.server.deps.inline !== true) {
 		const ssrOptions = viteConfig.ssr;
 		if (ssrOptions?.noExternal === true && resolved.server.deps.inline == null) {
@@ -4055,6 +4115,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 		}
 	}
 	if (typeof resolved.workspace === "string") {
+		// if passed down from the CLI and it's relative, resolve relative to CWD
 		resolved.workspace = typeof options.workspace === "string" && options.workspace[0] === "." ? resolve(process.cwd(), options.workspace) : resolvePath(resolved.workspace, resolved.root);
 	}
 	if (!builtinPools.includes(resolved.pool)) {
@@ -4074,6 +4135,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 			...benchmarkConfigDefaults,
 			...resolved.benchmark
 		};
+		// override test config
 		resolved.coverage.enabled = false;
 		resolved.typecheck.enabled = false;
 		resolved.include = resolved.benchmark.include;
@@ -4088,6 +4150,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 		if (options.outputFile) {
 			resolved.benchmark.outputFile = options.outputFile;
 		}
+		// --compare from cli
 		if (options.compare) {
 			resolved.benchmark.compare = options.compare;
 		}
@@ -4099,6 +4162,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 		resolved.diff = resolvePath(resolved.diff, resolved.root);
 		resolved.forceRerunTriggers.push(resolved.diff);
 	}
+	// the server has been created, we don't need to override vite.server options
 	const api = resolveApiServerConfig(options, defaultPort);
 	resolved.api = {
 		...api,
@@ -4107,8 +4171,18 @@ function resolveConfig$1(vitest, options, viteConfig) {
 	if (options.related) {
 		resolved.related = toArray(options.related).map((file) => resolve(resolved.root, file));
 	}
+	/*
+	* Reporters can be defined in many different ways:
+	* { reporter: 'json' }
+	* { reporter: { onFinish() { method() } } }
+	* { reporter: ['json', { onFinish() { method() } }] }
+	* { reporter: [[ 'json' ]] }
+	* { reporter: [[ 'json' ], 'html'] }
+	* { reporter: [[ 'json', { outputFile: 'test.json' } ], 'html'] }
+	*/
 	if (options.reporters) {
 		if (!Array.isArray(options.reporters)) {
+			// Reporter name, e.g. { reporters: 'json' }
 			if (typeof options.reporters === "string") {
 				resolved.reporters = [[options.reporters, {}]];
 			} else {
@@ -4118,18 +4192,24 @@ function resolveConfig$1(vitest, options, viteConfig) {
 			resolved.reporters = [];
 			for (const reporter of options.reporters) {
 				if (Array.isArray(reporter)) {
+					// Reporter with options, e.g. { reporters: [ [ 'json', { outputFile: 'test.json' } ] ] }
 					resolved.reporters.push([reporter[0], reporter[1] || {}]);
 				} else if (typeof reporter === "string") {
+					// Reporter name in array, e.g. { reporters: ["html", "json"]}
 					resolved.reporters.push([reporter, {}]);
 				} else {
+					// Inline reporter, e.g. { reporter: [{ onFinish() { method() } }] }
 					resolved.reporters.push(reporter);
 				}
 			}
 		}
 	}
 	if (mode !== "benchmark") {
+		// @ts-expect-error "reporter" is from CLI, should be absolute to the running directory
+		// it is passed down as "vitest --reporter ../reporter.js"
 		const reportersFromCLI = resolved.reporter;
 		const cliReporters = toArray(reportersFromCLI || []).map((reporter) => {
+			// ./reporter.js || ../reporter.js, but not .reporters/reporter.js
 			if (/^\.\.?\//.test(reporter)) {
 				return resolve(process.cwd(), reporter);
 			}
@@ -4141,6 +4221,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 	}
 	if (!resolved.reporters.length) {
 		resolved.reporters.push(["default", {}]);
+		// also enable github-actions reporter as a default
 		if (process.env.GITHUB_ACTIONS === "true") {
 			resolved.reporters.push(["github-actions", {}]);
 		}
@@ -4168,6 +4249,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 		resolved.sequence.shuffle = tests;
 	}
 	if (!resolved.sequence?.sequencer) {
+		// CLI flag has higher priority
 		resolved.sequence.sequencer = resolved.sequence.shuffle ? RandomSequencer : BaseSequencer;
 	}
 	resolved.sequence.groupOrder ??= 0;
@@ -4188,11 +4270,11 @@ function resolveConfig$1(vitest, options, viteConfig) {
 	if (resolved.typecheck.enabled) {
 		logger.console.warn(c.yellow("Testing types with tsc and vue-tsc is an experimental feature.\nBreaking changes might not follow SemVer, please pin Vitest's version when using it."));
 	}
-	resolved.browser ??= {};
 	resolved.browser.enabled ??= false;
 	resolved.browser.headless ??= isCI;
 	resolved.browser.isolate ??= true;
 	resolved.browser.fileParallelism ??= options.fileParallelism ?? mode !== "benchmark";
+	// disable in headless mode by default, and if CI is detected
 	resolved.browser.ui ??= resolved.browser.headless === true ? false : !isCI;
 	if (resolved.browser.screenshotDirectory) {
 		resolved.browser.screenshotDirectory = resolve(resolved.root, resolved.browser.screenshotDirectory);
@@ -4217,6 +4299,7 @@ function resolveConfig$1(vitest, options, viteConfig) {
 		resolved.browser.provider = "preview";
 	}
 	resolved.browser.api = resolveApiServerConfig(resolved.browser, defaultBrowserPort) || { port: defaultBrowserPort };
+	// enable includeTaskLocation by default in UI mode
 	if (resolved.browser.enabled) {
 		if (resolved.browser.ui) {
 			resolved.includeTaskLocation ??= true;
@@ -4242,14 +4325,17 @@ function isBrowserEnabled(config) {
 	return Boolean(config.browser?.enabled);
 }
 function resolveCoverageReporters(configReporters) {
+	// E.g. { reporter: "html" }
 	if (!Array.isArray(configReporters)) {
 		return [[configReporters, {}]];
 	}
 	const resolvedReporters = [];
 	for (const reporter of configReporters) {
 		if (Array.isArray(reporter)) {
+			// E.g. { reporter: [ ["html", { skipEmpty: true }], ["lcov"], ["json", { file: "map.json" }] ]}
 			resolvedReporters.push([reporter[0], reporter[1] || {}]);
 		} else {
+			// E.g. { reporter: ["html", "json"]}
 			resolvedReporters.push([reporter, {}]);
 		}
 	}
@@ -4268,6 +4354,7 @@ function isPlaywrightChromiumOnly(vitest, config) {
 	}
 	for (const instance of browser.instances) {
 		const name = instance.name || (config.name ? `${config.name} (${instance.browser})` : instance.browser);
+		// browser config is filtered out
 		if (!vitest.matchesProjectFilter(name)) {
 			continue;
 		}
@@ -4375,6 +4462,7 @@ class BaseCoverageProvider {
 		}
 		const testFilenames = testFiles.join();
 		const filename = resolve(this.coverageFilesDirectory, `coverage-${uniqueId++}.json`);
+		// If there's a result from previous run, overwrite it
 		entry[transformMode][testFilenames] = filename;
 		const promise = promises$1.writeFile(filename, JSON.stringify(coverage), "utf-8");
 		this.pendingPromises.push(promise);
@@ -4406,6 +4494,7 @@ class BaseCoverageProvider {
 	async cleanAfterRun() {
 		this.coverageFiles = new Map();
 		await promises$1.rm(this.coverageFilesDirectory, { recursive: true });
+		// Remove empty reports directory, e.g. when only text-reporter is used
 		if (readdirSync(this.options.reportsDirectory).length === 0) {
 			await promises$1.rm(this.options.reportsDirectory, { recursive: true });
 		}
@@ -4417,6 +4506,7 @@ class BaseCoverageProvider {
 	}
 	async reportCoverage(coverageMap, { allTestsRun }) {
 		await this.generateReports(coverageMap || this.createCoverageMap(), allTestsRun);
+		// In watch mode we need to preserve the previous results if cleanOnRerun is disabled
 		const keepResults = !this.options.cleanOnRerun && this.ctx.config.watch;
 		if (!keepResults) {
 			await this.cleanAfterRun();
@@ -4466,6 +4556,7 @@ class BaseCoverageProvider {
 				thresholds: globThresholds
 			});
 		}
+		// Global threshold is for all files, even if they are included by glob patterns
 		for (const file of files) {
 			const fileCoverage = coverageMap.fileCoverageFor(file);
 			globalCoverageMap.addFileCoverage(fileCoverage);
@@ -4490,6 +4581,7 @@ class BaseCoverageProvider {
 			if (thresholds.branches === undefined && thresholds.functions === undefined && thresholds.lines === undefined && thresholds.statements === undefined) {
 				continue;
 			}
+			// Construct list of coverage summaries where thresholds are compared against
 			const summaries = this.options.thresholds?.perFile ? coverageMap.files().map((file) => ({
 				file,
 				summary: coverageMap.fileCoverageFor(file).toSummary()
@@ -4497,6 +4589,7 @@ class BaseCoverageProvider {
 				file: null,
 				summary: coverageMap.getCoverageSummary()
 			}];
+			// Check thresholds of each summary
 			for (const { summary, file } of summaries) {
 				for (const thresholdKey of THRESHOLD_KEYS) {
 					const threshold = thresholds[thresholdKey];
@@ -4568,6 +4661,7 @@ class BaseCoverageProvider {
 					const absoluteThreshold = threshold * -1;
 					const actual = Math.max(...summaries.map((summary) => summary[key].total - summary[key].covered));
 					if (actual < absoluteThreshold) {
+						// If everything was covered, set new threshold to 100% (since a threshold of 0 would be considered as 0%)
 						const updatedThreshold = actual === 0 ? 100 : actual * -1;
 						thresholdsToUpdate.push([key, updatedThreshold]);
 					}
@@ -4627,6 +4721,7 @@ class BaseCoverageProvider {
 		return async function transformFile(filename) {
 			let lastError;
 			for (const { root, vitenode, isBrowserEnabled } of servers) {
+				// On Windows root doesn't start with "/" while filenames do
 				if (!filename.startsWith(root) && !filename.startsWith(`/${root}`)) {
 					continue;
 				}
@@ -4642,6 +4737,7 @@ class BaseCoverageProvider {
 					lastError = error;
 				}
 			}
+			// All vite-node servers failed to transform the file
 			throw lastError;
 		};
 	}
@@ -4670,6 +4766,7 @@ function resolveGlobThresholds(thresholds) {
 }
 function assertConfigurationModule(config) {
 	try {
+		// @ts-expect-error -- Intentional unsafe null pointer check as wrapped in try-catch
 		if (typeof config.test.coverage.thresholds !== "object") {
 			throw new TypeError("Expected config.test.coverage.thresholds to be an object");
 		}
@@ -4681,13 +4778,16 @@ function assertConfigurationModule(config) {
 function resolveConfig(configModule) {
 	const mod = configModule.exports.default;
 	try {
+		// Check for "export default { test: {...} }"
 		if (mod.$type === "object") {
 			return mod;
 		}
+		// "export default defineConfig(...)"
 		let config = resolveDefineConfig(mod);
 		if (config) {
 			return config;
 		}
+		// "export default mergeConfig(..., defineConfig(...))"
 		if (mod.$type === "function-call" && mod.$callee === "mergeConfig") {
 			config = resolveMergeConfig(mod);
 			if (config) {
@@ -4695,19 +4795,23 @@ function resolveConfig(configModule) {
 			}
 		}
 	} catch (error) {
+		// Reduce magicast's verbose errors to readable ones
 		throw new Error(error instanceof Error ? error.message : String(error));
 	}
 	throw new Error("Failed to update coverage thresholds. Configuration file is too complex.");
 }
 function resolveDefineConfig(mod) {
 	if (mod.$type === "function-call" && mod.$callee === "defineConfig") {
+		// "export default defineConfig({ test: {...} })"
 		if (mod.$args[0].$type === "object") {
 			return mod.$args[0];
 		}
 		if (mod.$args[0].$type === "arrow-function-expression") {
 			if (mod.$args[0].$body.$type === "object") {
+				// "export default defineConfig(() => ({ test: {...} }))"
 				return mod.$args[0].$body;
 			}
+			// "export default defineConfig(() => mergeConfig({...}, ...))"
 			const config = resolveMergeConfig(mod.$args[0].$body);
 			if (config) {
 				return config;