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

package/dist/chunks/{cli-api.d6IK1pnk.js → cli-api.CnmEXkxs.js}

@@ -5,15 +5,15 @@ import path, { resolve as resolve$1 } from 'node:path';
 import { noop, isPrimitive, createDefer, highlight, toArray, deepMerge, nanoid, slash, deepClone, notNullish } from '@vitest/utils';
 import { f as findUp, p as prompt } from './index.X0nbfr6-.js';
 import * as vite from 'vite';
-import { searchForWorkspaceRoot, version, mergeConfig, createServer } from 'vite';
-import { A as API_PATH, c as configFiles, d as defaultBrowserPort, w as workspacesFiles, a as defaultPort } from './constants.BZZyIeIE.js';
+import { searchForWorkspaceRoot, version, createServer, mergeConfig } from 'vite';
+import { A as API_PATH, c as configFiles, d as defaultBrowserPort, w as workspacesFiles, a as defaultPort } from './constants.DnKduX2e.js';
 import { generateFileHash, limitConcurrency, createFileTask, hasFailed, getTasks, getTests } from '@vitest/runner/utils';
 import { SnapshotManager } from '@vitest/snapshot/manager';
 import { ViteNodeRunner } from 'vite-node/client';
 import { ViteNodeServer } from 'vite-node/server';
-import { v as version$1 } from './cac.I9MLYfT-.js';
+import { v as version$1 } from './cac.DWaWHIIE.js';
 import { c as createBirpc } from './index.CJ0plNrh.js';
-import { p as parse, s as stringify, d as printError, f as formatProjectName, w as withLabel, e as errorBanner, h as divider, i as generateCodeFrame, R as ReportersMap, j as BlobReporter, r as readBlobs, H as HangingProcessReporter } from './index.CV36oG_L.js';
+import { p as parse, s as stringify, d as printError, f as formatProjectName, w as withLabel, e as errorBanner, h as divider, i as generateCodeFrame, R as ReportersMap, j as BlobReporter, r as readBlobs, H as HangingProcessReporter } from './index.Bter3jj9.js';
 import require$$0$3 from 'events';
 import require$$1$1 from 'https';
 import require$$2 from 'http';
@@ -28,8 +28,8 @@ import { g as getDefaultExportFromCjs } from './_commonjsHelpers.BFTU3MAI.js';
 import { parseErrorStacktrace } from '@vitest/utils/source-map';
 import crypto from 'node:crypto';
 import { distDir, rootDir } from '../path.js';
-import { R as RandomSequencer, i as isPackageExists, h as hash, V as VitestCache, g as getFilePoolName, d as isBrowserEnabled, r as resolveConfig, e as groupBy, f as getCoverageProvider, j as createPool, w as wildcardPatternToRegExp, a as resolveApiServerConfig, s as stdout } from './coverage.OGU09Jbh.js';
-import { c as convertTasksToEvents } from './typechecker.DnTrplSJ.js';
+import { R as RandomSequencer, i as isPackageExists, h as hash, V as VitestCache, g as getFilePoolName, d as isBrowserEnabled, r as resolveConfig, e as groupBy, f as getCoverageProvider, j as createPool, w as wildcardPatternToRegExp, a as resolveApiServerConfig, s as stdout } from './coverage.C73DaDgS.js';
+import { c as convertTasksToEvents } from './typechecker.BgzF-6iO.js';
 import { Console } from 'node:console';
 import c from 'tinyrainbow';
 import { createRequire } from 'node:module';
@@ -41,9 +41,9 @@ import pm from 'picomatch';
 import { glob, isDynamicPattern } from 'tinyglobby';
 import { normalizeRequestId, cleanUrl } from 'vite-node/utils';
 import { hoistMocksPlugin, automockPlugin } from '@vitest/mocker/node';
-import { c as configDefaults } from './defaults.DSxsTG0h.js';
+import { c as configDefaults } from './defaults.DpVH7vbg.js';
 import MagicString from 'magic-string';
-import { a as BenchmarkReportsMap } from './index.CmC5OK9L.js';
+import { a as BenchmarkReportsMap } from './index.JOzufsrU.js';
 import assert$1 from 'node:assert';
 import { serializeError } from '@vitest/utils/error';
 import readline from 'node:readline';
@@ -779,6 +779,14 @@ function requirePermessageDeflate () {
 	  this[kError].code = 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH';
 	  this[kError][kStatusCode] = 1009;
 	  this.removeListener('data', inflateOnData);
+
+	  //
+	  // The choice to employ `zlib.reset()` over `zlib.close()` is dictated by the
+	  // fact that in Node.js versions prior to 13.10.0, the callback for
+	  // `zlib.flush()` is not called if `zlib.close()` is used. Utilizing
+	  // `zlib.reset()` ensures that either the callback is invoked or an error is
+	  // emitted.
+	  //
 	  this.reset();
 	}
 
@@ -794,6 +802,12 @@ function requirePermessageDeflate () {
 	  // closed when an error is emitted.
 	  //
 	  this[kPerMessageDeflate]._inflate = null;
+
+	  if (this[kError]) {
+	    this[kCallback](this[kError]);
+	    return;
+	  }
+
 	  err[kStatusCode] = 1007;
 	  this[kCallback](err);
 	}
@@ -3511,7 +3525,7 @@ function requireWebsocket () {
 	  if (parsedUrl.protocol !== 'ws:' && !isSecure && !isIpcUrl) {
 	    invalidUrlMessage =
 	      'The URL\'s protocol must be one of "ws:", "wss:", ' +
-	      '"http:", "https", or "ws+unix:"';
+	      '"http:", "https:", or "ws+unix:"';
 	  } else if (isIpcUrl && !parsedUrl.pathname) {
 	    invalidUrlMessage = "The URL's pathname is empty";
 	  } else if (parsedUrl.hash) {
@@ -5035,7 +5049,10 @@ function clearId(id) {
 	return id?.replace(/\?v=\w+$/, "") || "";
 }
 
+// Serialization support utils.
 function cloneByOwnProperties(value) {
+	// Clones the value's properties into a new Object. The simpler approach of
+	// Object.assign() won't work in the case that properties are not enumerable.
 	return Object.getOwnPropertyNames(value).reduce((clone, prop) => ({
 		...clone,
 		[prop]: value[prop]
@@ -5061,12 +5078,15 @@ function stringifyReplace(key, value) {
 
 function isValidApiRequest(config, req) {
 	const url = new URL(req.url ?? "", "http://localhost");
+	// validate token. token is injected in ui/tester/orchestrator html, which is cross origin protected.
 	try {
 		const token = url.searchParams.get("token");
 		if (token && crypto.timingSafeEqual(Buffer.from(token), Buffer.from(config.api.token))) {
 			return true;
 		}
-	} catch {}
+	} 
+	// an error is thrown when the length is incorrect
+catch {}
 	return false;
 }
 
@@ -5267,6 +5287,7 @@ class BrowserSessions {
 		this.sessions.delete(sessionId);
 	}
 	createSession(sessionId, project, pool) {
+		// this promise only waits for the WS connection with the orhcestrator to be established
 		const defer = createDefer();
 		const timeout = setTimeout(() => {
 			defer.reject(new Error(`Failed to connect to the browser session "${sessionId}" [${project.name}] within the timeout.`));
@@ -5489,6 +5510,7 @@ class Logger {
 			this.log(PAD + c.dim(c.green(`UI started at http://${host}:${c.bold(port)}${base}`)));
 		} else if (this.ctx.config.api?.port) {
 			const resolvedUrls = this.ctx.server.resolvedUrls;
+			// workaround for https://github.com/vitejs/vite/issues/15438, it was fixed in vite 5.1
 			const fallbackUrl = `http://${this.ctx.config.api.host || "localhost"}:${this.ctx.config.api.port}`;
 			const origin = resolvedUrls?.local[0] ?? resolvedUrls?.network[0] ?? fallbackUrl;
 			this.log(PAD + c.dim(c.green(`API started at ${new URL("/", origin)}`)));
@@ -5552,6 +5574,8 @@ class Logger {
 		};
 		const onExit = (signal, exitCode) => {
 			cleanup();
+			// Interrupted signals don't set exit code automatically.
+			// Use same exit code as node: https://nodejs.org/api/process.html#signal-events
 			if (process.exitCode === undefined) {
 				process.exitCode = exitCode !== undefined ? 128 + exitCode : Number(signal);
 			}
@@ -5615,7 +5639,8 @@ class VitestPackageInstaller {
 		});
 		if (install) {
 			const packageName = version ? `${dependency}@${version}` : dependency;
-			await (await import('./index.CK1YOQaa.js')).installPackage(packageName, { dev: true });
+			await (await import('./index.D3XRDfWc.js')).installPackage(packageName, { dev: true });
+			// TODO: somehow it fails to load the package after installation, remove this when it's fixed
 			process.stderr.write(c.yellow(`\nPackage ${packageName} installed, re-run the command to start.\n`));
 			process.exit();
 			return true;
@@ -5627,6 +5652,7 @@ class VitestPackageInstaller {
 function serializeConfig(config, coreConfig, viteConfig) {
 	const optimizer = config.deps?.optimizer;
 	const poolOptions = config.poolOptions;
+	// Resolve from server.config to avoid comparing against default value
 	const isolate = viteConfig?.test?.isolate;
 	return {
 		environmentOptions: config.environmentOptions,
@@ -5799,6 +5825,7 @@ function generateCssFilenameHash(filepath) {
 	return hash("md5", filepath, "hex").slice(0, 6);
 }
 function generateScopedClassName(strategy, name, filename) {
+	// should be configured by Vite defaults
 	if (strategy === "scoped") {
 		return null;
 	}
@@ -5823,6 +5850,8 @@ function clearScreen(logger) {
 let lastType;
 let lastMsg;
 let sameCount = 0;
+// Only initialize the timeFormatter when the timestamp option is used, and
+// reuse it across all loggers
 let timeFormatter;
 function getTimeFormatter() {
 	timeFormatter ??= new Intl.DateTimeFormat(undefined, {
@@ -5832,6 +5861,10 @@ function getTimeFormatter() {
 	});
 	return timeFormatter;
 }
+// This is copy-pasted and needs to be synced from time to time. Ideally, Vite's `createLogger` should accept a custom `console`
+// https://github.com/vitejs/vite/blob/main/packages/vite/src/node/logger.ts?rgh-link-date=2024-10-16T23%3A29%3A19Z
+// When Vitest supports only Vite 6 and above, we can use Vite's `createLogger({ console })`
+// https://github.com/vitejs/vite/pull/18379
 function createViteLogger(console, level = "info", options = {}) {
 	const loggedErrors = new WeakSet();
 	const { prefix = "[vite]", allowClearScreen = true } = options;
@@ -5912,6 +5945,7 @@ function createViteLogger(console, level = "info", options = {}) {
 	};
 	return logger;
 }
+// silence warning by Vite for statically not analyzable dynamic import
 function silenceImportViteIgnoreWarning(logger) {
 	return {
 		...logger,
@@ -5934,6 +5968,8 @@ function isCSS(id) {
 function isCSSModule(id) {
 	return cssModuleRE.test(id);
 }
+// inline css requests are expected to just return the
+// string content directly and not the proxy module
 function isInline(id) {
 	return cssInlineRE.test(id);
 }
@@ -5965,6 +6001,8 @@ function CSSEnablerPlugin(ctx) {
 			if (!isCSS(id)) {
 				return;
 			}
+			// css plugin inside Vite won't do anything if the code is empty
+			// but it will put __vite__updateStyle anyway
 			if (!shouldProcessCSS(id)) {
 				return { code: "" };
 			}
@@ -5977,6 +6015,9 @@ function CSSEnablerPlugin(ctx) {
 				return;
 			}
 			if (isCSSModule(id) && !isInline(id)) {
+				// return proxy for css modules, so that imported module has names:
+				// styles.foo returns a "foo" instead of "undefined"
+				// we don't use code content to generate hash for "scoped", because it's empty
 				const scopeStrategy = typeof ctx.config.css !== "boolean" && ctx.config.css.modules?.classNameStrategy || "stable";
 				const proxyReturn = getCSSModuleProxyReturn(scopeStrategy, relative(ctx.config.root, id));
 				const code = `export default new Proxy(Object.create(null), {
@@ -6477,6 +6518,10 @@ function stripLiteralDetailed(code, options) {
 
 const metaUrlLength = "import.meta.url".length;
 const locationString = "self.location".padEnd(metaUrlLength, " ");
+// Vite transforms new URL('./path', import.meta.url) to new URL('/path.js', import.meta.url)
+// This makes "href" equal to "http://localhost:3000/path.js" in the browser, but if we keep it like this,
+// then in tests the URL will become "file:///path.js".
+// To battle this, we replace "import.meta.url" with "self.location" in the code to keep the browser behavior.
 function NormalizeURLPlugin() {
 	return {
 		name: "vitest:normalize-url",
@@ -6490,6 +6535,7 @@ function NormalizeURLPlugin() {
 			const assetImportMetaUrlRE = /\bnew\s+URL\s*\(\s*(?:'[^']+'|"[^"]+"|`[^`]+`)\s*,\s*(?:'' \+ )?import\.meta\.url\s*(?:,\s*)?\)/g;
 			let updatedCode = code;
 			let match;
+			// eslint-disable-next-line no-cond-assign
 			while (match = assetImportMetaUrlRE.exec(cleanString)) {
 				const { 0: exp, index } = match;
 				const metaUrlIndex = index + exp.indexOf("import.meta.url");
@@ -6543,6 +6589,8 @@ function resolveOptimizerConfig(_testOptions, viteOptions, testConfig, viteCache
 			include
 		};
 	}
+	// `optimizeDeps.disabled` is deprecated since v5.1.0-beta.1
+	// https://github.com/vitejs/vite/pull/15184
 	if (major >= 5 && minor >= 1 || major >= 6) {
 		if (newConfig.optimizeDeps.disabled) {
 			newConfig.optimizeDeps.noDiscovery = true;
@@ -6566,6 +6614,8 @@ function deleteDefineConfig(viteConfig) {
 		try {
 			replacement = typeof val === "string" ? JSON.parse(val) : val;
 		} catch {
+			// probably means it contains reference to some variable,
+			// like this: "__VAR__": "process.env.VAR"
 			continue;
 		}
 		if (key.startsWith("import.meta.env.")) {
@@ -6626,6 +6676,8 @@ function VitestOptimizer() {
 	};
 }
 
+// so people can reassign envs at runtime
+// import.meta.env.VITE_NAME = 'app' -> process.env.VITE_NAME = 'app'
 function SsrReplacerPlugin() {
 	return {
 		name: "vitest:ssr-replacer",
@@ -6662,6 +6714,8 @@ function VitestProjectResolver(ctx) {
 		enforce: "pre",
 		async resolveId(id, _, { ssr }) {
 			if (id === "vitest" || id.startsWith("@vitest/") || id.startsWith("vitest/")) {
+				// always redirect the request to the root vitest plugin since
+				// it will be the one used to run Vitest
 				const resolved = await ctx.server.pluginContainer.resolveId(id, undefined, {
 					skip: new Set([plugin]),
 					ssr
@@ -6681,6 +6735,7 @@ function VitestCoreResolver(ctx) {
 				return resolve(distDir, "index.js");
 			}
 			if (id.startsWith("@vitest/") || id.startsWith("vitest/")) {
+				// ignore actual importer, we want it to be resolved relative to the root
 				return this.resolve(id, join(ctx.config.root, "index.html"), { skipSelf: true });
 			}
 		}
@@ -6705,6 +6760,7 @@ function WorkspaceVitestPlugin(project, options) {
 				};
 				if (!name) {
 					if (typeof options.workspacePath === "string") {
+						// if there is a package.json, read the name from it
 						const dir = options.workspacePath.endsWith("/") ? options.workspacePath.slice(0, -1) : dirname(options.workspacePath);
 						const pkgJsonPath = resolve(dir, "package.json");
 						if (existsSync(pkgJsonPath)) {
@@ -6745,22 +6801,27 @@ function WorkspaceVitestPlugin(project, options) {
 						color
 					} }
 				};
-				if (project.vitest._options.browser && viteConfig.test?.browser) {
-					viteConfig.test.browser = mergeConfig(viteConfig.test.browser, project.vitest._options.browser);
-				}
 				config.test.defines = defines;
+				const isUserBrowserEnabled = viteConfig.test?.browser?.enabled;
+				const isBrowserEnabled = isUserBrowserEnabled ?? (viteConfig.test?.browser && project.vitest._cliOptions.browser?.enabled);
+				// keep project names to potentially filter it out
 				const workspaceNames = [name];
-				if (viteConfig.test?.browser?.enabled) {
-					if (viteConfig.test.browser.name && !viteConfig.test.browser.instances?.length) {
-						const browser = viteConfig.test.browser.name;
-						workspaceNames.push(name ? `${name} (${browser})` : browser);
-					}
-					viteConfig.test.browser.instances?.forEach((instance) => {
-						instance.name ??= name ? `${name} (${instance.browser})` : instance.browser;
-						workspaceNames.push(instance.name);
-					});
+				const browser = viteConfig.test.browser || {};
+				if (isBrowserEnabled && browser.name && !browser.instances?.length) {
+					// vitest injects `instances` in this case later on
+					workspaceNames.push(name ? `${name} (${browser.name})` : browser.name);
 				}
+				viteConfig.test?.browser?.instances?.forEach((instance) => {
+					// every instance is a potential project
+					instance.name ??= name ? `${name} (${instance.browser})` : instance.browser;
+					if (isBrowserEnabled) {
+						workspaceNames.push(instance.name);
+					}
+				});
 				const filters = project.vitest.config.project;
+				// if there is `--project=...` filter, check if any of the potential projects match
+				// if projects don't match, we ignore the test project altogether
+				// if some of them match, they will later be filtered again by `resolveWorkspace`
 				if (filters.length) {
 					const hasProject = workspaceNames.some((name) => {
 						return project.vitest.matchesProjectFilter(name);
@@ -6881,6 +6942,8 @@ class TestSpecification {
 }
 
 async function createViteServer(inlineConfig) {
+	// Vite prints an error (https://github.com/vitejs/vite/issues/14328)
+	// But Vitest works correctly either way
 	const error = console.error;
 	console.error = (...args) => {
 		if (typeof args[0] === "string" && args[0].includes("WebSocket server error:")) {
@@ -6942,6 +7005,8 @@ class TestProject {
 		}
 		return this._hash;
 	}
+	// "provide" is a property, not a method to keep the context when destructed in the global setup,
+	// making it a method would be a breaking change, and can be done in Vitest 3 at minimum
 	/**
 	* Provide a value to the test context. This value will be available to all tests with `inject`.
 	*/
@@ -6951,6 +7016,7 @@ class TestProject {
 		} catch (err) {
 			throw new Error(`Cannot provide "${key}" because it's not serializable.`, { cause: err });
 		}
+		// casting `any` because the default type is `never` since `ProvidedContext` is empty
 		this._provided[key] = value;
 	};
 	/**
@@ -6960,6 +7026,8 @@ class TestProject {
 		if (this.isRootProject()) {
 			return this._provided;
 		}
+		// globalSetup can run even if core workspace is not part of the test run
+		// so we need to inherit its provided context
 		return {
 			...this.vitest.getRootProject().getProvidedContext(),
 			...this._provided
@@ -6986,6 +7054,7 @@ class TestProject {
 		if (!this._vite) {
 			throw new Error("The server was not set. It means that `project.vite` was called before the Vite server was established.");
 		}
+		// checking it once should be enough
 		Object.defineProperty(this, "vite", {
 			configurable: true,
 			writable: true,
@@ -7000,6 +7069,12 @@ class TestProject {
 		if (!this._config) {
 			throw new Error("The config was not set. It means that `project.config` was called before the Vite server was established.");
 		}
+		// checking it once should be enough
+		// Object.defineProperty(this, 'config', {
+		//   configurable: true,
+		//   writable: true,
+		//   value: this._config,
+		// })
 		return this._config;
 	}
 	/**
@@ -7079,6 +7154,7 @@ class TestProject {
 	get logger() {
 		return this.vitest.logger;
 	}
+	// it's possible that file path was imported with different queries (?raw, ?url, etc)
 	/** @deprecated use `.vite` or `.browser.vite` directly */
 	getModulesByFilepath(file) {
 		const set = this.server.moduleGraph.getModulesByFile(file) || this.browser?.vite.moduleGraph.getModulesByFile(file);
@@ -7172,6 +7248,9 @@ class TestProject {
 			expandDirectories: false
 		};
 		const files = await glob(include, globOptions);
+		// keep the slashes consistent with Vite
+		// we are not using the pathe here because it normalizes the drive letter on Windows
+		// and we want to keep it the same as working dir
 		return files.map((file) => slash(path.resolve(cwd, file)));
 	}
 	/**
@@ -7213,6 +7292,7 @@ class TestProject {
 			return testFiles.filter((t) => {
 				const testFile = relative(dir, t).toLocaleLowerCase();
 				return filters.some((f) => {
+					// if filter is a full file path, we should include it if it's in the same folder
 					if (isAbsolute(f) && t.startsWith(f)) {
 						return true;
 					}
@@ -7303,6 +7383,7 @@ class TestProject {
 		this._setHash();
 		for (const _providedKey in this.config.provide) {
 			const providedKey = _providedKey;
+			// type is very strict here, so we cast it to any
 			this.provide(providedKey, this.config.provide[providedKey]);
 		}
 		this.closingPromise = undefined;
@@ -7321,6 +7402,7 @@ class TestProject {
 		});
 	}
 	_serializeOverriddenConfig() {
+		// TODO: serialize the config _once_ or when needed
 		const config = serializeConfig(this.config, this.vitest.config, this.vite.config);
 		if (!this.vitest.configOverride) {
 			return config;
@@ -7350,6 +7432,7 @@ class TestProject {
 	_provideObject(context) {
 		for (const _providedKey in context) {
 			const providedKey = _providedKey;
+			// type is very strict here, so we cast it to any
 			this.provide(providedKey, context[providedKey]);
 		}
 	}
@@ -7419,6 +7502,8 @@ function generateHash(str) {
 
 async function resolveProjects(vitest, cliOptions, workspaceConfigPath, projectsDefinition, names) {
 	const { configFiles, projectConfigs, nonConfigDirectories } = await resolveTestProjectConfigs(vitest, workspaceConfigPath, projectsDefinition);
+	// cli options that affect the project config,
+	// not all options are allowed to be overridden
 	const overridesOptions = [
 		"logHeapUsage",
 		"allowOnly",
@@ -7450,7 +7535,10 @@ async function resolveProjects(vitest, cliOptions, workspaceConfigPath, projects
 	const concurrent = limitConcurrency(nodeos__default.availableParallelism?.() || nodeos__default.cpus().length || 5);
 	projectConfigs.forEach((options, index) => {
 		const configRoot = workspaceConfigPath ? dirname(workspaceConfigPath) : vitest.config.root;
+		// if extends a config file, resolve the file path
 		const configFile = typeof options.extends === "string" ? resolve(configRoot, options.extends) : options.extends === true ? vitest.vite.config.configFile || false : false;
+		// if `root` is configured, resolve it relative to the workspace file or vite root (like other options)
+		// if `root` is not specified, inline configs use the same root as the root project
 		const root = options.root ? resolve(configRoot, options.root) : vitest.config.root;
 		projectPromises.push(concurrent(() => initializeProject(index, vitest, {
 			...options,
@@ -7463,6 +7551,7 @@ async function resolveProjects(vitest, cliOptions, workspaceConfigPath, projects
 		})));
 	});
 	for (const path of fileProjects) {
+		// if file leads to the root config, then we can just reuse it because we already initialized it
 		if (vitest.vite.config.configFile === path) {
 			const project = getDefaultTestProject(vitest);
 			if (project) {
@@ -7478,6 +7567,7 @@ async function resolveProjects(vitest, cliOptions, workspaceConfigPath, projects
 			test: cliOverrides
 		})));
 	}
+	// pretty rare case - the glob didn't match anything and there are no inline configs
 	if (!projectPromises.length) {
 		throw new Error([
 			"No projects were found. Make sure your configuration is correct. ",
@@ -7491,6 +7581,7 @@ async function resolveProjects(vitest, cliOptions, workspaceConfigPath, projects
 	for (const result of resolvedProjectsPromises) {
 		if (result.status === "rejected") {
 			if (result.reason instanceof VitestFilteredOutProjectError) {
+				// filter out filtered out projects
 				continue;
 			}
 			errors.push(result.reason);
@@ -7501,6 +7592,7 @@ async function resolveProjects(vitest, cliOptions, workspaceConfigPath, projects
 	if (errors.length) {
 		throw new AggregateError(errors, "Failed to initialize projects. There were errors during projects setup. See below for more details.");
 	}
+	// project names are guaranteed to be unique
 	for (const project of resolvedProjects) {
 		const name = project.name;
 		if (names.has(name)) {
@@ -7545,10 +7637,12 @@ async function resolveBrowserProjects(vitest, names, resolvedProjects) {
 			].filter(Boolean).join("")));
 		}
 		const originalName = project.config.name;
+		// if original name is in the --project=name filter, keep all instances
 		const filteredInstances = vitest.matchesProjectFilter(originalName) ? instances : instances.filter((instance) => {
 			const newName = instance.name;
 			return vitest.matchesProjectFilter(newName);
 		});
+		// every project was filtered out
 		if (!filteredInstances.length) {
 			removeProjects.add(project);
 			return;
@@ -7628,13 +7722,19 @@ function cloneConfig(project, { browser,...config }) {
 	}, overrideConfig);
 }
 async function resolveTestProjectConfigs(vitest, workspaceConfigPath, projectsDefinition) {
+	// project configurations that were specified directly
 	const projectsOptions = [];
+	// custom config files that were specified directly or resolved from a directory
 	const projectsConfigFiles = [];
+	// custom glob matches that should be resolved as directories or config files
 	const projectsGlobMatches = [];
+	// directories that don't have a config file inside, but should be treated as projects
 	const nonConfigProjectDirectories = [];
 	for (const definition of projectsDefinition) {
 		if (typeof definition === "string") {
 			const stringOption = definition.replace("<rootDir>", vitest.config.root);
+			// if the string doesn't contain a glob, we can resolve it directly
+			// ['./vitest.config.js']
 			if (!isDynamicPattern(stringOption)) {
 				const file = resolve(vitest.config.root, stringOption);
 				if (!existsSync(file)) {
@@ -7643,6 +7743,7 @@ async function resolveTestProjectConfigs(vitest, workspaceConfigPath, projectsDe
 					throw new Error(`${note} references a non-existing file or a directory: ${file}`);
 				}
 				const stats = await promises.stat(file);
+				// user can specify a config file directly
 				if (stats.isFile()) {
 					projectsConfigFiles.push(file);
 				} else if (stats.isDirectory()) {
@@ -7654,6 +7755,7 @@ async function resolveTestProjectConfigs(vitest, workspaceConfigPath, projectsDe
 						nonConfigProjectDirectories.push(directory);
 					}
 				} else {
+					// should never happen
 					throw new TypeError(`Unexpected file type: ${file}`);
 				}
 			} else {
@@ -7685,6 +7787,8 @@ async function resolveTestProjectConfigs(vitest, workspaceConfigPath, projectsDe
 		};
 		const projectsFs = await glob(projectsGlobMatches, globOptions);
 		await Promise.all(projectsFs.map(async (path) => {
+			// directories are allowed with a glob like `packages/*`
+			// in this case every directory is treated as a project
 			if (path.endsWith("/")) {
 				const configFile = await resolveDirectoryConfig(path);
 				if (configFile) {
@@ -7706,6 +7810,8 @@ async function resolveTestProjectConfigs(vitest, workspaceConfigPath, projectsDe
 }
 async function resolveDirectoryConfig(directory) {
 	const files = new Set(await promises.readdir(directory));
+	// default resolution looks for vitest.config.* or vite.config.* files
+	// this simulates how `findUp` works in packages/vitest/src/node/create.ts:29
 	const configFile = configFiles.find((file) => files.has(file));
 	if (configFile) {
 		return resolve(directory, configFile);
@@ -7718,6 +7824,7 @@ function getDefaultTestProject(vitest) {
 	if (!filter.length) {
 		return project;
 	}
+	// check for the project name and browser names
 	const hasProjects = getPotentialProjectNames(project).some((p) => vitest.matchesProjectFilter(p));
 	if (hasProjects) {
 		return project;
@@ -7839,6 +7946,7 @@ class VitestSpecifications {
 		const files = [];
 		const dir = process.cwd();
 		const parsedFilters = filters.map((f) => parseFilter(f));
+		// Require includeTaskLocation when a location filter is passed
 		if (!this.vitest.config.includeTaskLocation && parsedFilters.some((f) => f.lineNumber !== undefined)) {
 			throw new IncludeTaskLocationDisabledError();
 		}
@@ -7846,6 +7954,7 @@ class VitestSpecifications {
 			...f,
 			filename: resolve(dir, f.filename)
 		})));
+		// Key is file and val specifies whether we have matched this file with testLocation
 		const testLocHasMatch = {};
 		await Promise.all(this.vitest.projects.map(async (project) => {
 			const { testFiles, typecheckTestFiles } = await project.globTestFiles(parsedFilters.map((f) => f.filename));
@@ -7913,6 +8022,8 @@ class VitestSpecifications {
 		if (matcher && related.some((file) => matcher(file))) {
 			return specs;
 		}
+		// don't run anything if no related sources are found
+		// if we are in watch mode, we want to process all tests
 		if (!this.vitest.config.watch && !related.length) {
 			return [];
 		}
@@ -7922,6 +8033,7 @@ class VitestSpecifications {
 		}));
 		const runningTests = [];
 		for (const [specification, deps] of testGraphs) {
+			// if deps or the test itself were changed
 			if (related.some((path) => path === specification.moduleId || deps.has(path))) {
 				runningTests.push(specification);
 			}
@@ -8097,6 +8209,7 @@ class TestCase extends ReportedTaskImplementation {
 	*/
 	diagnostic() {
 		const result = this.task.result;
+		// startTime should always be available if the test has properly finished
 		if (!result || !result.startTime) {
 			return undefined;
 		}
@@ -8418,6 +8531,7 @@ class StateManager {
 			return keys.map((key) => this.filesMap.get(key)).flat().filter((file) => file && !file.local);
 		}
 		return Array.from(this.filesMap.values()).flat().filter((file) => !file.local).sort((f1, f2) => {
+			// print typecheck files first
 			if (f1.meta?.typecheck && f2.meta?.typecheck) {
 				return 0;
 			}
@@ -8446,6 +8560,8 @@ class StateManager {
 			const existing = this.filesMap.get(file.filepath) || [];
 			const otherFiles = existing.filter((i) => i.projectName !== file.projectName || i.meta.typecheck !== file.meta.typecheck);
 			const currentFile = existing.find((i) => i.projectName === file.projectName);
+			// keep logs for the previous file because it should always be initiated before the collections phase
+			// which means that all logs are collected during the collection and not inside tests
 			if (currentFile) {
 				file.logs = currentFile.logs;
 			}
@@ -8466,6 +8582,7 @@ class StateManager {
 				return;
 			}
 			const filtered = files.filter((file) => file.projectName !== project.config.name);
+			// always keep a File task, so we can associate logs with it
 			if (!filtered.length) {
 				this.filesMap.set(path, [fileTask]);
 			} else {
@@ -8500,6 +8617,7 @@ class StateManager {
 			if (task) {
 				task.result = result;
 				task.meta = meta;
+				// skipped with new PendingError
 				if (result?.state === "skip") {
 					task.mode = "skip";
 				}
@@ -8552,6 +8670,9 @@ class TestRun {
 	}
 	async updated(update, events) {
 		this.vitest.state.updateTasks(update);
+		// TODO: what is the order or reports here?
+		// "onTaskUpdate" in parallel with others or before all or after all?
+		// TODO: error handling - what happens if custom reporter throws an error?
 		await this.vitest.report("onTaskUpdate", update);
 		for (const [id, event] of events) {
 			await this.reportEvent(id, event).catch((error) => {
@@ -8560,6 +8681,7 @@ class TestRun {
 		}
 	}
 	async end(specifications, errors, coverage) {
+		// specification won't have the File task if they were filtered by the --shard command
 		const modules = specifications.map((spec) => spec.testModule).filter((s) => s != null);
 		const files = modules.map((m) => m.task);
 		const state = this.vitest.isCancelling ? "interrupted" : process.exitCode ? "failed" : "passed";
@@ -8584,6 +8706,9 @@ class TestRun {
 		if (event === "suite-finished") {
 			assert$1(entity.type === "suite" || entity.type === "module", "Entity type must be suite or module");
 			if (entity.state() === "skipped") {
+				// everything inside suite or a module is skipped,
+				// so we won't get any children events
+				// we need to report everything manually
 				await this.reportChildren(entity.children);
 			}
 			if (entity.type === "module") {
@@ -8738,6 +8863,7 @@ class VitestWatcher {
 			this.changedTests.add(id);
 			this.scheduleRerun(id);
 		} else {
+			// it's possible that file was already there but watcher triggered "add" event instead
 			const needsRerun = this.handleFileChanged(id);
 			if (needsRerun) {
 				this.scheduleRerun(id);
@@ -8760,6 +8886,8 @@ class VitestWatcher {
 			return moduleGraph.getModulesByFile(filepath)?.size;
 		});
 		if (!projects.length) {
+			// if there are no modules it's possible that server was restarted
+			// we don't have information about importers anymore, so let's check if the file is a test file at least
 			if (this.vitest.state.filesMap.has(filepath) || this.vitest.projects.some((project) => project._isCachedTestFile(filepath))) {
 				this.changedTests.add(filepath);
 				return true;
@@ -8773,6 +8901,7 @@ class VitestWatcher {
 				continue;
 			}
 			this.invalidates.add(filepath);
+			// one of test files that we already run, or one of test files that we can run
 			if (this.vitest.state.filesMap.has(filepath) || project._isCachedTestFile(filepath)) {
 				this.changedTests.add(filepath);
 				files.push(filepath);
@@ -8844,7 +8973,7 @@ class Vitest {
 	resolvedProjects = [];
 	/** @internal */ _browserLastPort = defaultBrowserPort;
 	/** @internal */ _browserSessions = new BrowserSessions();
-	/** @internal */ _options = {};
+	/** @internal */ _cliOptions = {};
 	/** @internal */ reporters = [];
 	/** @internal */ vitenode = undefined;
 	/** @internal */ runner = undefined;
@@ -8860,8 +8989,9 @@ class Vitest {
 	_cache;
 	_snapshot;
 	_workspaceConfigPath;
-	constructor(mode, options = {}) {
+	constructor(mode, cliOptions, options = {}) {
 		this.mode = mode;
+		this._cliOptions = cliOptions;
 		this.logger = new Logger(this, options.stdout, options.stderr);
 		this.packageInstaller = options.packageInstaller || new VitestPackageInstaller();
 		this.specifications = new VitestSpecifications(this);
@@ -8922,12 +9052,11 @@ class Vitest {
 		return this._cache;
 	}
 	/** @deprecated internal */
-	setServer(options, server, cliOptions) {
-		return this._setServer(options, server, cliOptions);
+	setServer(options, server) {
+		return this._setServer(options, server);
 	}
 	/** @internal */
-	async _setServer(options, server, cliOptions) {
-		this._options = options;
+	async _setServer(options, server) {
 		this.watcher.unregisterWatcher();
 		clearTimeout(this._rerunTimer);
 		this.restartsCount += 1;
@@ -8966,6 +9095,7 @@ class Vitest {
 			}
 		});
 		if (this.config.watch) {
+			// hijack server restart
 			const serverRestart = server.restart;
 			server.restart = async (...args) => {
 				await Promise.all(this._onRestartListeners.map((fn) => fn()));
@@ -8973,6 +9103,7 @@ class Vitest {
 				await this.close();
 				await serverRestart(...args);
 			};
+			// since we set `server.hmr: false`, Vite does not auto restart itself
 			server.watcher.on("change", async (file) => {
 				file = normalize(file);
 				const isConfig = file === server.config.configFile || this.projects.some((p) => p.vite.config.configFile === file) || file === this._workspaceConfigPath;
@@ -8988,7 +9119,7 @@ class Vitest {
 		try {
 			await this.cache.results.readFromCache();
 		} catch {}
-		const projects = await this.resolveProjects(cliOptions);
+		const projects = await this.resolveProjects(this._cliOptions);
 		this.resolvedProjects = projects;
 		this.projects = projects;
 		await Promise.all(projects.flatMap((project) => {
@@ -8999,7 +9130,7 @@ class Vitest {
 				injectTestProjects: this.injectTestProject
 			}));
 		}));
-		if (options.browser?.enabled) {
+		if (this._cliOptions.browser?.enabled) {
 			const browserProjects = this.projects.filter((p) => p.config.browser.enabled);
 			if (!browserProjects.length) {
 				throw new Error(`Vitest received --browser flag, but no project had a browser configuration.`);
@@ -9029,7 +9160,7 @@ class Vitest {
 	*/
 	injectTestProject = async (config) => {
 		const currentNames = new Set(this.projects.map((p) => p.name));
-		const projects = await resolveProjects(this, this._options, undefined, Array.isArray(config) ? config : [config], currentNames);
+		const projects = await resolveProjects(this, this._cliOptions, undefined, Array.isArray(config) ? config : [config], currentNames);
 		this.projects.push(...projects);
 		return projects;
 	};
@@ -9116,7 +9247,10 @@ class Vitest {
 		}
 		const workspaceConfigPath = await this.resolveWorkspaceConfigPath();
 		this._workspaceConfigPath = workspaceConfigPath;
+		// user doesn't have a workspace config, return default project
 		if (!workspaceConfigPath) {
+			// user can filter projects with --project flag, `getDefaultTestProject`
+			// returns the project only if it matches the filter
 			const project = getDefaultTestProject(this);
 			if (!project) {
 				return [];
@@ -9207,6 +9341,7 @@ class Vitest {
 	}
 	async collect(filters) {
 		const files = await this.specifications.getRelevantTestSpecifications(filters);
+		// if run with --changed, don't exit if no tests are found
 		if (!files.length) {
 			return {
 				testModules: [],
@@ -9243,15 +9378,18 @@ class Vitest {
 		}
 		this.filenamePattern = filters && filters?.length > 0 ? filters : undefined;
 		const files = await this.specifications.getRelevantTestSpecifications(filters);
+		// if run with --changed, don't exit if no tests are found
 		if (!files.length) {
 			const throwAnError = !this.config.watch || !(this.config.changed || this.config.related?.length);
 			await this._testRun.start([]);
 			const coverage = await this.coverageProvider?.generateCoverage?.({ allTestsRun: true });
+			// set exit code before calling `onTestRunEnd` so the lifecycle is consistent
 			if (throwAnError) {
 				const exitCode = this.config.passWithNoTests ? 0 : 1;
 				process.exitCode = exitCode;
 			}
 			await this._testRun.end([], [], coverage);
+			// Report coverage for uncovered files
 			await this.reportCoverage(coverage, true);
 			if (throwAnError) {
 				throw new FilesNotFoundError(this.mode);
@@ -9262,6 +9400,7 @@ class Vitest {
 			unhandledErrors: []
 		};
 		if (files.length) {
+			// populate once, update cache on watch
 			await this.cache.stats.populateStats(this.config.root, files);
 			testModules = await this.runFiles(files, true);
 		}
@@ -9281,6 +9420,7 @@ class Vitest {
 		} finally {
 			await this.report("onInit", this);
 		}
+		// populate test files cache so watch mode can trigger a file rerun
 		await this.globTestSpecifications();
 		if (this.config.watch) {
 			await this.report("onWatcherStart");
@@ -9335,9 +9475,11 @@ class Vitest {
 	}
 	async runFiles(specs, allTestsRun) {
 		await this._testRun.start(specs);
+		// previous run
 		await this.runningPromise;
 		this._onCancelListeners = [];
 		this.isCancelling = false;
+		// schedule the new run
 		this.runningPromise = (async () => {
 			try {
 				if (!this.pool) {
@@ -9369,6 +9511,7 @@ class Vitest {
 					unhandledErrors: this.state.getUnhandledErrors()
 				};
 			} finally {
+				// TODO: wait for coverage only if `onFinished` is defined
 				const coverage = await this.coverageProvider?.generateCoverage({ allTestsRun });
 				const errors = this.state.getUnhandledErrors();
 				this._checkUnhandledErrors(errors);
@@ -9378,6 +9521,7 @@ class Vitest {
 		})().finally(() => {
 			this.runningPromise = undefined;
 			this.isFirstRun = false;
+			// all subsequent runs will treat this as a fresh run
 			this.config.changed = false;
 			this.config.related = undefined;
 		});
@@ -9390,9 +9534,11 @@ class Vitest {
 	async collectTests(specifications) {
 		const filepaths = specifications.map((spec) => spec.moduleId);
 		this.state.collectPaths(filepaths);
+		// previous run
 		await this.runningPromise;
 		this._onCancelListeners = [];
 		this.isCancelling = false;
+		// schedule the new run
 		this.runningPromise = (async () => {
 			if (!this.pool) {
 				this.pool = createPool(this);
@@ -9408,6 +9554,8 @@ class Vitest {
 				this.state.catchError(err, "Unhandled Error");
 			}
 			const files = this.state.getFiles();
+			// can only happen if there was a syntax error in describe block
+			// or there was an error importing a file
 			if (hasFailed(files)) {
 				process.exitCode = 1;
 			}
@@ -9417,6 +9565,7 @@ class Vitest {
 			};
 		})().finally(() => {
 			this.runningPromise = undefined;
+			// all subsequent runs will treat this as a fresh run
 			this.config.changed = false;
 			this.config.related = undefined;
 		});
@@ -9479,11 +9628,13 @@ class Vitest {
 	}
 	/** @internal */
 	async changeNamePattern(pattern, files = this.state.getFilepaths(), trigger) {
+		// Empty test name pattern should reset filename pattern as well
 		if (pattern === "") {
 			this.filenamePattern = undefined;
 		}
 		const testNamePattern = pattern ? new RegExp(pattern) : undefined;
 		this.configOverride.testNamePattern = testNamePattern;
+		// filter only test files that have tests matching the pattern
 		if (testNamePattern) {
 			files = files.filter((filepath) => {
 				const files = this.state.getFiles([filepath]);
@@ -9510,6 +9661,7 @@ class Vitest {
 	* @param files The list of files on the file system
 	*/
 	async updateSnapshot(files) {
+		// default to failed files
 		files = files || [...this.state.getFailedFilepaths(), ...this.snapshot.summary.uncheckedKeysByFile.map((s) => s.filePath)];
 		this.enableSnapshotUpdate();
 		try {
@@ -9557,11 +9709,13 @@ class Vitest {
 		this.configOverride.testNamePattern = undefined;
 	}
 	_rerunTimer;
+	// we can't use a single `triggerId` yet because vscode extension relies on this
 	async scheduleRerun(triggerId) {
 		const currentCount = this.restartsCount;
 		clearTimeout(this._rerunTimer);
 		await this.runningPromise;
 		clearTimeout(this._rerunTimer);
+		// server restarted
 		if (this.restartsCount !== currentCount) {
 			return;
 		}
@@ -9570,6 +9724,7 @@ class Vitest {
 				this.watcher.invalidates.clear();
 				return;
 			}
+			// server restarted
 			if (this.restartsCount !== currentCount) {
 				return;
 			}
@@ -9579,6 +9734,7 @@ class Vitest {
 			if (this.filenamePattern) {
 				const filteredFiles = await this.globTestSpecifications(this.filenamePattern);
 				files = files.filter((file) => filteredFiles.some((f) => f.moduleId === file));
+				// A file that does not match the current filename pattern was changed
 				if (files.length === 0) {
 					return;
 				}
@@ -9586,6 +9742,7 @@ class Vitest {
 			this.watcher.changedTests.clear();
 			const triggerIds = new Set(triggerId.map((id) => relative(this.config.root, id)));
 			const triggerLabel = Array.from(triggerIds).join(", ");
+			// get file specifications and filter them if needed
 			const specifications = files.flatMap((file) => this.getModuleSpecifications(file)).filter((specification) => {
 				if (this._onFilterWatchedSpecification.length === 0) {
 					return true;
@@ -9629,6 +9786,7 @@ class Vitest {
 		}
 		if (this.coverageProvider) {
 			await this.coverageProvider.reportCoverage(coverage, { allTestsRun });
+			// notify coverage iframe reload
 			for (const reporter of this.reporters) {
 				if (reporter instanceof WebSocketReporter) {
 					reporter.onFinishedReportCoverage();
@@ -9647,10 +9805,13 @@ class Vitest {
 				if (this.coreWorkspaceProject && !teardownProjects.includes(this.coreWorkspaceProject)) {
 					teardownProjects.push(this.coreWorkspaceProject);
 				}
+				// do teardown before closing the server
 				for (const project of teardownProjects.reverse()) {
 					await project._teardownGlobalSetup();
 				}
 				const closePromises = this.projects.map((w) => w.close());
+				// close the core workspace server only once
+				// it's possible that it's not initialized at all because it's not running any tests
 				if (this.coreWorkspaceProject && !this.projects.includes(this.coreWorkspaceProject)) {
 					closePromises.push(this.coreWorkspaceProject.close().then(() => this._vite = undefined));
 				}
@@ -9707,7 +9868,7 @@ class Vitest {
 		await Promise.all(this.reporters.map((r) => r[name]?.(
 			// @ts-expect-error let me go
 			...args
-)));
+		)));
 	}
 	/** @internal */
 	async _globTestFilepaths() {
@@ -9730,6 +9891,7 @@ class Vitest {
 	getModuleProjects(filepath) {
 		return this.projects.filter((project) => {
 			return project.getModulesByFilepath(filepath).size;
+			// TODO: reevaluate || project.browser?.moduleGraph.getModulesByFile(id)?.size
 		});
 	}
 	/**
@@ -9780,7 +9942,8 @@ class Vitest {
 	* Check if the project with a given name should be included.
 	*/
 	matchesProjectFilter(name) {
-		const projects = this._config?.project || this._options?.project;
+		const projects = this._config?.project || this._cliOptions?.project;
+		// no filters applied, any project can be included
 		if (!projects || !projects.length) {
 			return true;
 		}
@@ -9796,11 +9959,11 @@ function assert(condition, property, name = property) {
 	}
 }
 
-async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
+async function VitestPlugin(options = {}, vitest = new Vitest("test", deepClone(options))) {
 	const userConfig = deepMerge({}, options);
 	async function UIPlugin() {
-		await ctx.packageInstaller.ensureInstalled("@vitest/ui", options.root || process.cwd(), ctx.version);
-		return (await import('@vitest/ui')).default(ctx);
+		await vitest.packageInstaller.ensureInstalled("@vitest/ui", options.root || process.cwd(), vitest.version);
+		return (await import('@vitest/ui')).default(vitest);
 	}
 	return [
 		{
@@ -9811,10 +9974,17 @@ async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
 			},
 			async config(viteConfig) {
 				if (options.watch) {
+					// Earlier runs have overwritten values of the `options`.
+					// Reset it back to initial user config before setting up the server again.
 					options = deepMerge({}, userConfig);
 				}
+				// preliminary merge of options to be able to create server options for vite
+				// however to allow vitest plugins to modify vitest config values
+				// this is repeated in configResolved where the config is final
 				const testConfig = deepMerge({}, configDefaults, removeUndefinedValues(viteConfig.test ?? {}), options);
 				testConfig.api = resolveApiServerConfig(testConfig, defaultPort);
+				// store defines for globalThis to make them
+				// reassignable when running in worker in src/runtime/setup.ts
 				const defines = deleteDefineConfig(viteConfig);
 				options.defines = defines;
 				let open = false;
@@ -9856,11 +10026,13 @@ async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
 						deps: testConfig.deps ?? viteConfig.test?.deps
 					}
 				};
-				if (ctx.configOverride.project) {
-					options.project = ctx.configOverride.project;
+				if (vitest.configOverride.project) {
+					// project filter was set by the user, so we need to filter the project
+					options.project = vitest.configOverride.project;
 				}
-				config.customLogger = createViteLogger(ctx.logger, viteConfig.logLevel || "warn", { allowClearScreen: false });
+				config.customLogger = createViteLogger(vitest.logger, viteConfig.logLevel || "warn", { allowClearScreen: false });
 				config.customLogger = silenceImportViteIgnoreWarning(config.customLogger);
+				// we want inline dependencies to be resolved by analyser plugin so module graph is populated correctly
 				if (viteConfig.ssr?.noExternal !== true) {
 					const inline = testConfig.server?.deps?.inline;
 					if (inline === true) {
@@ -9868,13 +10040,17 @@ async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
 					} else {
 						const noExternal = viteConfig.ssr?.noExternal;
 						const noExternalArray = typeof noExternal !== "undefined" ? toArray(noExternal) : undefined;
+						// filter the same packages
 						const uniqueInline = inline && noExternalArray ? inline.filter((dep) => !noExternalArray.includes(dep)) : inline;
 						config.ssr = { noExternal: uniqueInline };
 					}
 				}
+				// chokidar fsevents is unstable on macos when emitting "ready" event
 				if (process.platform === "darwin" && process.env.VITE_TEST_WATCHER_DEBUG) {
 					const watch = config.server.watch;
 					if (watch) {
+						// eslint-disable-next-line ts/ban-ts-comment
+						// @ts-ignore Vite 6 compat
 						watch.useFsEvents = false;
 						watch.usePolling = false;
 					}
@@ -9885,7 +10061,7 @@ async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
 					config.css.modules ??= {};
 					if (config.css.modules) {
 						config.css.modules.generateScopedName = (name, filename) => {
-							const root = ctx.config.root || options.root || process.cwd();
+							const root = vitest.config.root || options.root || process.cwd();
 							return generateScopedClassName(classNameStrategy, name, relative(root, filename));
 						};
 					}
@@ -9900,14 +10076,20 @@ async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
 				if ("alias" in viteConfigTest) {
 					delete viteConfigTest.alias;
 				}
+				// viteConfig.test is final now, merge it for real
 				options = deepMerge({}, configDefaults, viteConfigTest, options);
 				options.api = resolveApiServerConfig(options, defaultPort);
+				// we replace every "import.meta.env" with "process.env"
+				// to allow reassigning, so we need to put all envs on process.env
 				const { PROD, DEV,...envs } = viteConfig.env;
+				// process.env can have only string values and will cast string on it if we pass other type,
+				// so we are making them truthy
 				process.env.PROD ??= PROD ? "1" : "";
 				process.env.DEV ??= DEV ? "1" : "";
 				for (const name in envs) {
 					process.env[name] ??= envs[name];
 				}
+				// don't watch files in run mode
 				if (!options.watch) {
 					viteConfig.server.watch = null;
 				}
@@ -9917,7 +10099,7 @@ async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
 					configurable: true
 				});
 				const originalName = options.name;
-				if (options.browser?.enabled && options.browser?.instances) {
+				if (options.browser?.instances) {
 					options.browser.instances.forEach((instance) => {
 						instance.name ??= originalName ? `${originalName} (${instance.browser})` : instance.browser;
 					});
@@ -9928,13 +10110,15 @@ async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
 				async handler(server) {
 					if (options.watch && process.env.VITE_TEST_WATCHER_DEBUG) {
 						server.watcher.on("ready", () => {
+							// eslint-disable-next-line no-console
 							console.log("[debug] watcher is ready");
 						});
 					}
-					await ctx._setServer(options, server, userConfig);
+					await vitest._setServer(options, server);
 					if (options.api && options.watch) {
-						(await Promise.resolve().then(function () { return setup$1; })).setup(ctx);
+						(await Promise.resolve().then(function () { return setup$1; })).setup(vitest);
 					}
+					// #415, in run mode we don't need the watcher, close it would improve the performance
 					if (!options.watch) {
 						await server.watcher.close();
 					}
@@ -9942,9 +10126,9 @@ async function VitestPlugin(options = {}, ctx = new Vitest("test")) {
 			}
 		},
 		SsrReplacerPlugin(),
-		...CSSEnablerPlugin(ctx),
-		CoverageTransform(ctx),
-		VitestCoreResolver(ctx),
+		...CSSEnablerPlugin(vitest),
+		CoverageTransform(vitest),
+		VitestCoreResolver(vitest),
 		options.ui ? await UIPlugin() : null,
 		...MocksPlugins(),
 		VitestOptimizer(),
@@ -9961,15 +10145,16 @@ function removeUndefinedValues(obj) {
 }
 
 async function createVitest(mode, options, viteOverrides = {}, vitestOptions = {}) {
-	const ctx = new Vitest(mode, vitestOptions);
+	const ctx = new Vitest(mode, deepClone(options), vitestOptions);
 	const root = slash(resolve$1(options.root || process.cwd()));
 	const configPath = options.config === false ? false : options.config ? resolve$1(root, options.config) : await findUp(configFiles, { cwd: root });
 	options.config = configPath;
+	const { browser: _removeBrowser,...restOptions } = options;
 	const config = {
 		configFile: configPath,
 		configLoader: options.configLoader,
 		mode: options.mode || mode,
-		plugins: await VitestPlugin(options, ctx)
+		plugins: await VitestPlugin(restOptions, ctx)
 	};
 	const server = await createViteServer(mergeConfig(config, mergeConfig(viteOverrides, { root: options.root })));
 	if (ctx.config.api?.port) {
@@ -10100,6 +10285,7 @@ class WatchFilter {
 		const lines = str.split(/\r?\n/);
 		for (const line of lines) {
 			const columns = "columns" in this.stdout ? this.stdout.columns : 80;
+			// We have to take care of screen width in case of long lines
 			rows += 1 + Math.floor(Math.max(stripVTControlCharacters(line).length - 1, 0) / columns);
 		}
 		this.write(`${ESC}1G`);
@@ -10154,6 +10340,8 @@ ${keys.map((i) => c.dim("  press ") + c.reset([i[0]].flat().map(c.bold).join(",
 function registerConsoleShortcuts(ctx, stdin = process.stdin, stdout) {
 	let latestFilename = "";
 	async function _keypressHandler(str, key) {
+		// Cancel run and exit when ctrl-c or esc is pressed.
+		// If cancelling takes long and key is pressed multiple times, exit forcefully.
 		if (str === "" || str === "\x1B" || key && key.ctrl && key.name === "c") {
 			if (!ctx.isCancelling) {
 				ctx.logger.log(c.red("Cancelling test run. Press CTRL+c again to exit forcefully.\n"));
@@ -10162,6 +10350,7 @@ function registerConsoleShortcuts(ctx, stdin = process.stdin, stdout) {
 			}
 			return ctx.exit(true);
 		}
+		// window not support suspend
 		if (!isWindows && key && key.ctrl && key.name === "z") {
 			process.kill(process.ppid, "SIGTSTP");
 			process.kill(process.pid, "SIGTSTP");
@@ -10174,31 +10363,40 @@ function registerConsoleShortcuts(ctx, stdin = process.stdin, stdout) {
 			}
 			return;
 		}
+		// quit
 		if (name === "q") {
 			return ctx.exit(true);
 		}
+		// help
 		if (name === "h") {
 			return printShortcutsHelp();
 		}
+		// update snapshot
 		if (name === "u") {
 			return ctx.updateSnapshot();
 		}
+		// rerun all tests
 		if (name === "a" || name === "return") {
 			const files = await ctx._globTestFilepaths();
 			return ctx.changeNamePattern("", files, "rerun all tests");
 		}
+		// rerun current pattern tests
 		if (name === "r") {
 			return ctx.rerunFiles();
 		}
+		// rerun only failed tests
 		if (name === "f") {
 			return ctx.rerunFailed();
 		}
+		// change project filter
 		if (name === "w") {
 			return inputProjectName();
 		}
+		// change testNamePattern
 		if (name === "t") {
 			return inputNamePattern();
 		}
+		// change fileNamePattern
 		if (name === "p") {
 			return inputFilePattern();
 		}
@@ -10224,6 +10422,7 @@ function registerConsoleShortcuts(ctx, stdin = process.stdin, stdout) {
 				const reg = new RegExp(str);
 				return tests.map((test) => test.name).filter((testName) => testName.match(reg));
 			} catch {
+				// `new RegExp` may throw error when input is invalid regexp
 				return [];
 			}
 		});
@@ -10232,6 +10431,7 @@ function registerConsoleShortcuts(ctx, stdin = process.stdin, stdout) {
 			return;
 		}
 		const files = ctx.state.getFilepaths();
+		// if running in standalone mode, Vitest instance doesn't know about any test file
 		const cliFiles = ctx.config.standalone && !files.length ? await ctx._globTestFilepaths() : undefined;
 		await ctx.changeNamePattern(filter?.trim() || "", cliFiles, "change pattern");
 	}
@@ -10361,6 +10561,7 @@ async function prepareVitest(mode, options = {}, viteOverrides, vitestOptions) {
 	if (options.run) {
 		options.watch = false;
 	}
+	// this shouldn't affect _application root_ that can be changed inside config
 	const root = resolve(options.root || process.cwd());
 	const ctx = await createVitest(mode, options, viteOverrides, vitestOptions);
 	const environmentPackage = getEnvPackageName(ctx.config.environment);