@vitest/browser 4.0.0-beta.1 → 4.0.0-beta.11

package/dist/index.js

@@ -1,25 +1,28 @@
 import { ManualMockedModule, RedirectedModule, AutomockedModule, AutospiedModule, MockerRegistry } from '@vitest/mocker';
 import { dynamicImportPlugin, ServerMockResolver, interceptorPlugin } from '@vitest/mocker/node';
 import c from 'tinyrainbow';
-import { getFilePoolName, distDir, resolveApiServerConfig, resolveFsAllow, isFileServingAllowed, createDebugger, isValidApiRequest, createViteLogger, createViteServer } from 'vitest/node';
-import fs, { readFileSync, lstatSync, promises, existsSync } from 'node:fs';
+import { isValidApiRequest, isFileServingAllowed, distDir, resolveApiServerConfig, resolveFsAllow, rolldownVersion, createDebugger, createViteLogger, createViteServer } from 'vitest/node';
+import fs, { readFileSync, lstatSync, createReadStream, promises, existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { slash as slash$1, toArray, createDefer } from '@vitest/utils';
+import { slash as slash$1, toArray, deepMerge, createDefer } from '@vitest/utils/helpers';
 import MagicString from 'magic-string';
 import sirv from 'sirv';
-import * as vite from 'vite';
 import { coverageConfigDefaults } from 'vitest/config';
 import { fileURLToPath } from 'node:url';
 import crypto from 'node:crypto';
-import { mkdir, rm, readFile as readFile$1 } from 'node:fs/promises';
+import { mkdir, rm, readFile as readFile$1, writeFile as writeFile$1 } from 'node:fs/promises';
 import { parseErrorStacktrace, parseStacktrace } from '@vitest/utils/source-map';
-import { P as PlaywrightBrowserProvider, W as WebdriverBrowserProvider } from './webdriver-KA1WiV0q.js';
+import { PlaywrightBrowserProvider } from './providers/playwright.js';
+import { WebdriverBrowserProvider } from './providers/webdriverio.js';
 import { resolve as resolve$1, basename as basename$1, dirname as dirname$1, normalize as normalize$1 } from 'node:path';
-import { WebSocketServer } from 'ws';
 import * as nodeos from 'node:os';
+import { platform } from 'node:os';
+import { PNG } from 'pngjs';
+import pm from 'pixelmatch';
+import { WebSocketServer } from 'ws';
 import { performance } from 'node:perf_hooks';
 
-var version = "4.0.0-beta.1";
+var version = "4.0.0-beta.11";
 
 const _DRIVE_LETTER_START_RE = /^[A-Za-z]:\//;
 function normalizeWindowsPath(input = "") {
@@ -324,27 +327,28 @@ const stringify = (value, replacer, space) => {
 function replacer(code, values) {
 	return code.replace(/\{\s*(\w+)\s*\}/g, (_, key) => values[key] ?? _);
 }
-const builtinProviders = [
-	"webdriverio",
-	"playwright",
-	"preview"
-];
 async function getBrowserProvider(options, project) {
-	if (options.provider == null || builtinProviders.includes(options.provider)) {
-		const providers = await import('./providers.js');
-		const provider = options.provider || "preview";
-		return providers[provider];
+	const browser = project.config.browser.name;
+	const name = project.name ? `[${project.name}] ` : "";
+	if (!browser) {
+		throw new Error(`${name}Browser name is required. Please, set \`test.browser.instances[].browser\` option manually.`);
 	}
-	let customProviderModule;
-	try {
-		customProviderModule = await project.import(options.provider);
-	} catch (error) {
-		throw new Error(`Failed to load custom BrowserProvider from ${options.provider}`, { cause: error });
+	if (options.provider == null || "_cli" in options.provider && typeof options.provider.factory !== "function") {
+		const providers = await import('./index-CwoiDq7G.js');
+		const name = options.provider?.name || "preview";
+		if (!(name in providers)) {
+			throw new Error(`Unknown browser provider "${name}". Available providers: ${Object.keys(providers).join(", ")}.`);
+		}
+		return providers[name]().factory(project);
+	}
+	const supportedBrowsers = options.provider.supportedBrowser || [];
+	if (supportedBrowsers.length && !supportedBrowsers.includes(browser)) {
+		throw new Error(`${name}Browser "${browser}" is not supported by the browser provider "${options.provider.name}". Supported browsers: ${supportedBrowsers.join(", ")}.`);
 	}
-	if (customProviderModule.default == null) {
-		throw new Error(`Custom BrowserProvider loaded from ${options.provider} was not the default export`);
+	if (typeof options.provider.factory !== "function") {
+		throw new TypeError(`The "${name}" browser provider does not provide a "factory" function. Received ${typeof options.provider.factory}.`);
 	}
-	return customProviderModule.default;
+	return options.provider.factory(project);
 }
 function slash(path) {
 	return path.replace(/\\/g, "/").replace(/\/+/g, "/");
@@ -355,7 +359,7 @@ async function resolveOrchestrator(globalServer, url, res) {
 	// it's possible to open the page without a context
 	if (!sessionId) {
 		const contexts = [...globalServer.children].flatMap((p) => [...p.state.orchestrators.keys()]);
-		sessionId = contexts[contexts.length - 1] ?? "none";
+		sessionId = contexts.at(-1) ?? "none";
 	}
 	// it's ok to not have a session here, especially in the preview provider
 	// because the user could refresh the page which would remove the session id from the url
@@ -364,13 +368,13 @@ async function resolveOrchestrator(globalServer, url, res) {
 	if (!browserProject) {
 		return;
 	}
-	// ignore uknown pages
+	// ignore unknown pages
 	if (sessionId && sessionId !== "none" && !globalServer.vitest._browserSessions.sessionIds.has(sessionId)) {
 		return;
 	}
 	const injectorJs = typeof globalServer.injectorJs === "string" ? globalServer.injectorJs : await globalServer.injectorJs;
 	const injector = replacer(injectorJs, {
-		__VITEST_PROVIDER__: JSON.stringify(browserProject.config.browser.provider || "preview"),
+		__VITEST_PROVIDER__: JSON.stringify(browserProject.config.browser.provider?.name || "preview"),
 		__VITEST_CONFIG__: JSON.stringify(browserProject.wrapSerializedConfig()),
 		__VITEST_VITE_CONFIG__: JSON.stringify({ root: browserProject.vite.config.root }),
 		__VITEST_METHOD__: JSON.stringify("orchestrate"),
@@ -388,7 +392,7 @@ async function resolveOrchestrator(globalServer, url, res) {
 			for (const attr in script.attrs || {}) {
 				html += `${attr}="${script.attrs[attr]}" `;
 			}
-			html += `>${script.children}</script>`;
+			html += `>${script.children}<\/script>`;
 			return html;
 		}).join("\n");
 	}
@@ -402,15 +406,15 @@ async function resolveOrchestrator(globalServer, url, res) {
 			"{__VITEST_INJECTOR__}",
 			"{__VITEST_ERROR_CATCHER__}",
 			"{__VITEST_SCRIPTS__}",
-			`<script type="module" crossorigin src="${base}${jsEntry}"></script>`
+			`<script type="module" crossorigin src="${base}${jsEntry}"><\/script>`
 		].join("\n"));
 	}
 	return replacer(baseHtml, {
 		__VITEST_FAVICON__: globalServer.faviconUrl,
 		__VITEST_TITLE__: "Vitest Browser Runner",
 		__VITEST_SCRIPTS__: globalServer.orchestratorScripts,
-		__VITEST_INJECTOR__: `<script type="module">${injector}</script>`,
-		__VITEST_ERROR_CATCHER__: `<script type="module" src="${globalServer.errorCatcherUrl}"></script>`,
+		__VITEST_INJECTOR__: `<script type="module">${injector}<\/script>`,
+		__VITEST_ERROR_CATCHER__: `<script type="module" src="${globalServer.errorCatcherUrl}"><\/script>`,
 		__VITEST_SESSION_ID__: JSON.stringify(sessionId)
 	});
 }
@@ -671,6 +675,31 @@ var BrowserPlugin = (parentServer, base = "/") => {
 					}
 					next();
 				});
+				// handle attachments the same way as in packages/ui/node/index.ts
+				server.middlewares.use((req, res, next) => {
+					if (!req.url) {
+						return next();
+					}
+					const url = new URL(req.url, "http://localhost");
+					if (url.pathname !== "/__vitest_attachment__") {
+						return next();
+					}
+					const path = url.searchParams.get("path");
+					const contentType = url.searchParams.get("contentType");
+					if (!isValidApiRequest(parentServer.config, req) || !contentType || !path) {
+						return next();
+					}
+					const fsPath = decodeURIComponent(path);
+					if (!isFileServingAllowed(parentServer.vite.config, fsPath)) {
+						return next();
+					}
+					try {
+						res.setHeader("content-type", contentType);
+						return createReadStream(fsPath).pipe(res).on("close", () => res.end());
+					} catch (err) {
+						return next(err);
+					}
+				});
 			}
 		},
 		{
@@ -680,8 +709,7 @@ var BrowserPlugin = (parentServer, base = "/") => {
 				// this plugin can be used in different projects, but all of them
 				// have the same `include` pattern, so it doesn't matter which project we use
 				const project = parentServer.project;
-				const { testFiles: allTestFiles } = await project.globTestFiles();
-				const browserTestFiles = allTestFiles.filter((file) => getFilePoolName(project, file) === "browser");
+				const { testFiles: browserTestFiles } = await project.globTestFiles();
 				const setupFiles = toArray(project.config.setupFiles);
 				// replace env values - cannot be reassign at runtime
 				const define = {};
@@ -723,7 +751,7 @@ var BrowserPlugin = (parentServer, base = "/") => {
 					entries.push(project.config.diff);
 				}
 				if (parentServer.vitest.coverageProvider) {
-					const coverage = parentServer.vitest.config.coverage;
+					const coverage = parentServer.vitest._coverageOptions;
 					const provider = coverage.provider;
 					if (provider === "v8") {
 						const path = tryResolve("@vitest/coverage-v8", [parentServer.config.root]);
@@ -744,9 +772,8 @@ var BrowserPlugin = (parentServer, base = "/") => {
 				const include = [
 					"vitest > expect-type",
 					"vitest > @vitest/snapshot > magic-string",
-					"vitest > chai",
-					"vitest > chai > loupe",
-					"vitest > @vitest/runner > strip-literal",
+					"vitest > @vitest/expect > chai",
+					"vitest > @vitest/expect > chai > loupe",
 					"vitest > @vitest/utils > loupe",
 					"@vitest/browser > @testing-library/user-event",
 					"@vitest/browser > @testing-library/dom"
@@ -835,7 +862,7 @@ var BrowserPlugin = (parentServer, base = "/") => {
 					viteConfig.esbuild ||= {};
 					viteConfig.esbuild.legalComments = "inline";
 				}
-				const defaultPort = parentServer.vitest._browserLastPort++;
+				const defaultPort = parentServer.vitest.state._data.browserLastPort++;
 				const api = resolveApiServerConfig(viteConfig.test?.browser || {}, defaultPort);
 				viteConfig.server = {
 					...viteConfig.server,
@@ -859,7 +886,7 @@ var BrowserPlugin = (parentServer, base = "/") => {
 					return;
 				}
 				const s = new MagicString(code, { filename });
-				s.prepend(`import.meta.vitest = __vitest_index__;\n`);
+				s.prepend(`Object.defineProperty(import.meta, 'vitest', { get() { return typeof __vitest_worker__ !== 'undefined' && __vitest_worker__.filepath === "${filename.replace(/"/g, "\\\"")}" ? __vitest_index__ : undefined } });\n`);
 				return {
 					code: s.toString(),
 					map: s.generateMap({ hires: true })
@@ -890,10 +917,6 @@ var BrowserPlugin = (parentServer, base = "/") => {
 				if (!projectBrowser) {
 					return;
 				}
-				if (!parentServer.testerScripts) {
-					const testerScripts = await parentServer.formatScripts(parentServer.config.browser.testerScripts);
-					parentServer.testerScripts = testerScripts;
-				}
 				const stateJs = typeof parentServer.stateJs === "string" ? parentServer.stateJs : await parentServer.stateJs;
 				const testerTags = [];
 				const isDefaultTemplate = resolve(distRoot, "client/tester/tester.html") === projectBrowser.testerFilepath;
@@ -976,7 +999,6 @@ body {
 						},
 						injectTo: "head"
 					} : null,
-					...parentServer.testerScripts,
 					...testerTags
 				].filter((s) => s != null);
 			}
@@ -1005,7 +1027,7 @@ body {
 						});
 					}
 				};
-				return { optimizeDeps: "rolldownVersion" in vite ? { rollupOptions: { plugins: [rolldownPlugin] } } : { esbuildOptions: { plugins: [esbuildPlugin] } } };
+				return { optimizeDeps: rolldownVersion ? { rollupOptions: { plugins: [rolldownPlugin] } } : { esbuildOptions: { plugins: [esbuildPlugin] } } };
 			}
 		}
 	];
@@ -1027,7 +1049,8 @@ function getRequire() {
 }
 function resolveCoverageFolder(vitest) {
 	const options = vitest.config;
-	const htmlReporter = options.coverage?.enabled ? toArray(options.coverage.reporter).find((reporter) => {
+	const coverageOptions = vitest._coverageOptions;
+	const htmlReporter = coverageOptions?.enabled ? toArray(options.coverage.reporter).find((reporter) => {
 		if (typeof reporter === "string") {
 			return reporter === "html";
 		}
@@ -1037,7 +1060,7 @@ function resolveCoverageFolder(vitest) {
 		return undefined;
 	}
 	// reportsDirectory not resolved yet
-	const root = resolve(options.root || process.cwd(), options.coverage.reportsDirectory || coverageConfigDefaults.reportsDirectory);
+	const root = resolve(options.root || process.cwd(), coverageOptions.reportsDirectory || coverageConfigDefaults.reportsDirectory);
 	const subdir = Array.isArray(htmlReporter) && htmlReporter.length > 1 && "subdir" in htmlReporter[1] ? htmlReporter[1].subdir : undefined;
 	if (!subdir || typeof subdir !== "string") {
 		return [root, `/${basename(root)}/`];
@@ -1650,7 +1673,7 @@ _Mime_extensionToType = new WeakMap(), _Mime_typeToExtension = new WeakMap(), _M
 var mime = new Mime(types)._freeze();
 
 function assertFileAccess(path, project) {
-	if (!isFileServingAllowed(path, project.vite) && !isFileServingAllowed(path, project.vitest.server)) {
+	if (!isFileServingAllowed(path, project.vite) && !isFileServingAllowed(path, project.vitest.vite)) {
 		throw new Error(`Access denied to "${path}". See Vite config documentation for "server.fs": https://vitejs.dev/config/server-options.html#server-fs-strict.`);
 	}
 }
@@ -2353,44 +2376,73 @@ function selectAll() {
 }
 
 const screenshot = async (context, name, options = {}) => {
-	if (!context.testPath) {
-		throw new Error(`Cannot take a screenshot without a test path`);
-	}
 	options.save ??= true;
 	if (!options.save) {
 		options.base64 = true;
 	}
-	const path = options.path ? resolve(dirname(context.testPath), options.path) : resolveScreenshotPath(context.testPath, name, context.project.config);
+	const { buffer, path } = await takeScreenshot(context, name, options);
+	return returnResult(options, path, buffer);
+};
+/**
+* Takes a screenshot using the provided browser context and returns a buffer and the expected screenshot path.
+*
+* **Note**: the returned `path` indicates where the screenshot *might* be found.
+* It is not guaranteed to exist, especially if `options.save` is `false`.
+*
+* @throws {Error} If the function is not called within a test or if the browser provider does not support screenshots.
+*/
+async function takeScreenshot(context, name, options) {
+	if (!context.testPath) {
+		throw new Error(`Cannot take a screenshot without a test path`);
+	}
+	const path = resolveScreenshotPath(context.testPath, name, context.project.config, options.path);
 	const savePath = normalize$1(path);
 	await mkdir(dirname(path), { recursive: true });
 	if (context.provider instanceof PlaywrightBrowserProvider) {
+		const mask = options.mask?.map((selector) => context.iframe.locator(selector));
 		if (options.element) {
 			const { element: selector,...config } = options;
-			const element = context.iframe.locator(`${selector}`);
+			const element = context.iframe.locator(selector);
 			const buffer = await element.screenshot({
 				...config,
+				mask,
 				path: options.save ? savePath : undefined
 			});
-			return returnResult(options, path, buffer);
+			return {
+				buffer,
+				path
+			};
 		}
 		const buffer = await context.iframe.locator("body").screenshot({
 			...options,
+			mask,
 			path: options.save ? savePath : undefined
 		});
-		return returnResult(options, path, buffer);
+		return {
+			buffer,
+			path
+		};
 	}
 	if (context.provider instanceof WebdriverBrowserProvider) {
 		const page = context.provider.browser;
 		const element = !options.element ? await page.$("body") : await page.$(`${options.element}`);
-		const buffer = await element.saveScreenshot(savePath);
+		// webdriverio expects the path to contain the extension and only works with PNG files
+		const savePathWithExtension = savePath.endsWith(".png") ? savePath : `${savePath}.png`;
+		const buffer = await element.saveScreenshot(savePathWithExtension);
 		if (!options.save) {
-			await rm(savePath, { force: true });
+			await rm(savePathWithExtension, { force: true });
 		}
-		return returnResult(options, path, buffer);
+		return {
+			buffer,
+			path
+		};
 	}
 	throw new Error(`Provider "${context.provider.name}" does not support screenshots`);
-};
-function resolveScreenshotPath(testPath, name, config) {
+}
+function resolveScreenshotPath(testPath, name, config, customPath) {
+	if (customPath) {
+		return resolve(dirname(testPath), customPath);
+	}
 	const dir = dirname(testPath);
 	const base = basename(testPath);
 	if (config.browser.screenshotDirectory) {
@@ -2411,6 +2463,401 @@ function returnResult(options, path, buffer) {
 	return path;
 }
 
+const codec = {
+	decode: (buffer, options) => {
+		const { data, alpha, bpp, color, colorType, depth, height, interlace, palette, width } = PNG.sync.read(Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer), options);
+		return {
+			metadata: {
+				alpha,
+				bpp,
+				color,
+				colorType,
+				depth,
+				height,
+				interlace,
+				palette,
+				width
+			},
+			data
+		};
+	},
+	encode: ({ data, metadata: { height, width } }, options) => {
+		const png = new PNG({
+			height,
+			width
+		});
+		png.data = Buffer.isBuffer(data) ? data : Buffer.from(data);
+		return PNG.sync.write(png, options);
+	}
+};
+
+function getCodec(type) {
+	switch (type) {
+		case "png": return codec;
+		default: throw new Error(`No codec found for type ${type}`);
+	}
+}
+
+const defaultOptions$1 = {
+	allowedMismatchedPixelRatio: undefined,
+	allowedMismatchedPixels: undefined,
+	threshold: .1,
+	includeAA: false,
+	alpha: .1,
+	aaColor: [
+		255,
+		255,
+		0
+	],
+	diffColor: [
+		255,
+		0,
+		0
+	],
+	diffColorAlt: undefined,
+	diffMask: false
+};
+const pixelmatch = (reference, actual, { createDiff,...options }) => {
+	if (reference.metadata.height !== actual.metadata.height || reference.metadata.width !== actual.metadata.width) {
+		return {
+			pass: false,
+			diff: null,
+			message: `Expected image dimensions to be ${reference.metadata.width}×${reference.metadata.height}px, but received ${actual.metadata.width}×${actual.metadata.height}px.`
+		};
+	}
+	const optionsWithDefaults = {
+		...defaultOptions$1,
+		...options
+	};
+	const diffBuffer = createDiff ? new Uint8Array(reference.data.length) : undefined;
+	const mismatchedPixels = pm(reference.data, actual.data, diffBuffer, reference.metadata.width, reference.metadata.height, optionsWithDefaults);
+	const imageArea = reference.metadata.width * reference.metadata.height;
+	let allowedMismatchedPixels = Math.min(optionsWithDefaults.allowedMismatchedPixels ?? Number.POSITIVE_INFINITY, (optionsWithDefaults.allowedMismatchedPixelRatio ?? Number.POSITIVE_INFINITY) * imageArea);
+	if (allowedMismatchedPixels === Number.POSITIVE_INFINITY) {
+		allowedMismatchedPixels = 0;
+	}
+	const pass = mismatchedPixels <= allowedMismatchedPixels;
+	return {
+		pass,
+		diff: diffBuffer ?? null,
+		message: pass ? null : `${mismatchedPixels} pixels (ratio ${(Math.ceil(mismatchedPixels / imageArea * 100) / 100).toFixed(2)}) differ.`
+	};
+};
+
+const comparators = new Map(Object.entries({ pixelmatch }));
+function getComparator(comparator) {
+	if (comparators.has(comparator)) {
+		return comparators.get(comparator);
+	}
+	throw new Error(`Unrecognized comparator ${comparator}`);
+}
+
+const defaultOptions = {
+	comparatorName: "pixelmatch",
+	comparatorOptions: {},
+	screenshotOptions: {
+		animations: "disabled",
+		caret: "hide",
+		fullPage: false,
+		maskColor: "#ff00ff",
+		omitBackground: false,
+		scale: "device"
+	},
+	timeout: 5e3,
+	resolveDiffPath: ({ arg, ext, root, attachmentsDir, browserName, platform, testFileDirectory, testFileName }) => resolve(root, attachmentsDir, testFileDirectory, testFileName, `${arg}-${browserName}-${platform}${ext}`),
+	resolveScreenshotPath: ({ arg, ext, root, screenshotDirectory, testFileDirectory, testFileName, browserName }) => resolve(root, testFileDirectory, screenshotDirectory, testFileName, `${arg}-${browserName}-${platform}${ext}`)
+};
+const supportedExtensions = ["png"];
+function resolveOptions({ context, name, options, testName }) {
+	if (context.testPath === undefined) {
+		throw new Error("`resolveOptions` has to be used in a test file");
+	}
+	const resolvedOptions = deepMerge(Object.create(null), defaultOptions, context.project.config.browser.expect?.toMatchScreenshot ?? {}, options);
+	const extensionFromName = extname(name);
+	// technically the type is a lie, but we check beneath and reassign otherwise
+	let extension = extensionFromName.replace(/^\./, "");
+	// when `type` will be supported in `screenshotOptions`:
+	// - `'png'` should end up in `defaultOptions.screenshotOptions.type`
+	// - this condition should be switched around
+	// - the assignment should be `resolvedOptions.screenshotOptions.type = extension`
+	// - everything using `extension` should use `resolvedOptions.screenshotOptions.type`
+	if (supportedExtensions.includes(extension) === false) {
+		extension = "png";
+	}
+	const { root } = context.project.serializedConfig;
+	const resolvePathData = {
+		arg: sanitizeArg(
+			// remove the extension only if it ends up being used
+			extensionFromName.endsWith(extension) ? basename(name, extensionFromName) : name
+		),
+		ext: `.${extension}`,
+		platform: platform(),
+		root,
+		screenshotDirectory: relative(root, join(root, context.project.config.browser.screenshotDirectory ?? "__screenshots__")),
+		attachmentsDir: relative(root, context.project.config.attachmentsDir),
+		testFileDirectory: relative(root, dirname(context.testPath)),
+		testFileName: basename(context.testPath),
+		testName: sanitize(testName, false),
+		browserName: context.project.config.browser.name
+	};
+	return {
+		codec: getCodec(extension),
+		comparator: getComparator(resolvedOptions.comparatorName),
+		resolvedOptions,
+		paths: {
+			reference: resolvedOptions.resolveScreenshotPath(resolvePathData),
+			get diffs() {
+				const diffs = {
+					reference: resolvedOptions.resolveDiffPath({
+						...resolvePathData,
+						arg: `${resolvePathData.arg}-reference`
+					}),
+					actual: resolvedOptions.resolveDiffPath({
+						...resolvePathData,
+						arg: `${resolvePathData.arg}-actual`
+					}),
+					diff: resolvedOptions.resolveDiffPath({
+						...resolvePathData,
+						arg: `${resolvePathData.arg}-diff`
+					})
+				};
+				Object.defineProperty(this, "diffs", { value: diffs });
+				return diffs;
+			}
+		}
+	};
+}
+/**
+* Sanitizes a string by removing or transforming characters to ensure it is
+* safe for use as a filename or path segment. It supports two modes:
+*
+* 1. Non-path mode (`keepPaths === false`):
+*    - Replaces one or more whitespace characters (`\s+`) with a single hyphen (`-`).
+*    - Removes any character that is not a word character (`\w`) or a hyphen (`-`).
+*    - Collapses multiple consecutive hyphens (`-{2,}`) into a single hyphen.
+*
+* 2. Path-preserving mode (`keepPaths === true`):
+*    - Splits the input string on the path separator.
+*    - Sanitizes each path segment individually in non-path mode.
+*    - Joins the sanitized segments back together.
+*
+* @param input - The raw string to sanitize.
+* @param keepPaths - If `false`, performs a flat sanitization (drops path segments).
+* If `true`, treats `input` as a path: each segment is sanitized independently,
+* preserving separators.
+*/
+function sanitize(input, keepPaths) {
+	if (keepPaths === false) {
+		return input.replace(/\s+/g, "-").replace(/[^\w-]+/g, "").replace(/-{2,}/g, "-");
+	}
+	return input.split("/").map((path) => sanitize(path, false)).join("/");
+}
+/**
+* Takes a string, treats it as a potential path or filename, and ensures it cannot
+* escape the root directory or contain invalid characters. Internally, it:
+*
+* 1. Prepends the path separator to the raw input to form a path-like string.
+* 2. Uses {@linkcode relative|relative('/', <that-path>)} to compute a relative
+* path from the root, which effectively strips any leading separators and prevents
+* traversal above the root.
+* 3. Passes the resulting relative path into {@linkcode sanitize|sanitize(..., true)},
+* preserving any path separators but sanitizing each segment.
+*
+* @param input - The raw string to clean.
+*/
+function sanitizeArg(input) {
+	return sanitize(relative("/", join("/", input)), true);
+}
+/**
+* Takes a screenshot and decodes it using the provided codec.
+*
+* The screenshot is taken as a base64 string and then decoded into the format
+* expected by the comparator.
+*
+* @returns `Promise` resolving to the decoded screenshot data
+*/
+function takeDecodedScreenshot({ codec, context, element, name, screenshotOptions }) {
+	return takeScreenshot(context, name, {
+		...screenshotOptions,
+		save: false,
+		element
+	}).then(({ buffer }) => codec.decode(buffer, {}));
+}
+/**
+* Creates a promise that resolves to `null` after the specified timeout.
+* If the timeout is `0`, the promise resolves immediately.
+*
+* @param timeout - The delay in milliseconds before the promise resolves
+* @returns `Promise` that resolves to `null` after the timeout
+*/
+function asyncTimeout(timeout) {
+	return new Promise((resolve) => {
+		if (timeout === 0) {
+			resolve(null);
+		} else {
+			setTimeout(() => resolve(null), timeout);
+		}
+	});
+}
+
+const screenshotMatcher = async (context, name, testName, options) => {
+	if (!context.testPath) {
+		throw new Error(`Cannot compare screenshots without a test path`);
+	}
+	const { element } = options;
+	const { codec, comparator, paths, resolvedOptions: { comparatorOptions, screenshotOptions, timeout } } = resolveOptions({
+		context,
+		name,
+		testName,
+		options
+	});
+	const referenceFile = await readFile$1(paths.reference).catch(() => null);
+	const reference = referenceFile && await codec.decode(await readFile$1(paths.reference), {});
+	const abortController = new AbortController();
+	const stableScreenshot = getStableScreenshots({
+		codec,
+		comparator,
+		comparatorOptions,
+		context,
+		element,
+		name: `${Date.now()}-${basename(paths.reference)}`,
+		reference,
+		screenshotOptions,
+		signal: abortController.signal
+	});
+	const value = await (timeout === 0 ? stableScreenshot : Promise.race([stableScreenshot, asyncTimeout(timeout).finally(() => {
+		abortController.abort();
+	})]));
+	// case #01
+	//  - impossible to get a stable screenshot to compare against
+	//  - fail
+	if (value === null || value.actual === null) {
+		return {
+			pass: false,
+			reference: referenceFile && paths.reference,
+			actual: null,
+			diff: null,
+			message: `Could not capture a stable screenshot within ${timeout}ms.`
+		};
+	}
+	const { updateSnapshot } = context.project.serializedConfig.snapshotOptions;
+	// if there's no reference or if we want to update snapshots, we have to finish the comparison early
+	if (reference === null || updateSnapshot === "all") {
+		const shouldCreateReference = updateSnapshot !== "none";
+		const referencePath = shouldCreateReference ? paths.reference : paths.diffs.reference;
+		await writeScreenshot(referencePath, await codec.encode(value.actual, {}));
+		// case #02
+		//  - got a stable screenshot, but there is no reference and we don't want to update screenshots
+		//  - fail
+		if (updateSnapshot !== "all") {
+			return {
+				pass: false,
+				reference: referencePath,
+				actual: null,
+				diff: null,
+				message: `No existing reference screenshot found${shouldCreateReference ? "; a new one was created. Review it before running tests again." : "."}`
+			};
+		}
+		// case #03
+		//  - got a stable screenshot, there is no reference, but we want to update screenshots
+		//  - pass
+		return { pass: true };
+	}
+	// case #04
+	//  - got a stable screenshot with no retries and there's a reference
+	//  - pass
+	if (referenceFile && value.retries === 0) {
+		return { pass: true };
+	}
+	const finalResult = await comparator(reference, value.actual, {
+		createDiff: true,
+		...comparatorOptions
+	});
+	if (finalResult.pass === false && finalResult.diff !== null) {
+		const diff = await codec.encode({
+			data: finalResult.diff,
+			metadata: {
+				height: reference.metadata.height,
+				width: reference.metadata.width
+			}
+		}, {});
+		await writeScreenshot(paths.diffs.diff, diff);
+	}
+	// case #05
+	//  - reference matches stable screenshot
+	//  - pass
+	if (finalResult.pass === true) {
+		return { pass: true };
+	}
+	const actual = await codec.encode(value.actual, {});
+	await writeScreenshot(paths.diffs.actual, actual);
+	// case #06
+	//  - fallback, reference does NOT match stable screenshot
+	//  - fail
+	return {
+		pass: false,
+		reference: paths.reference,
+		actual: paths.diffs.actual,
+		diff: finalResult.diff && paths.diffs.diff,
+		message: `Screenshot does not match the stored reference.${finalResult.message === null ? "" : `\n${finalResult.message}`}`
+	};
+};
+async function writeScreenshot(path, image) {
+	try {
+		await mkdir(dirname(path), { recursive: true });
+		await writeFile$1(path, image);
+	} catch {
+		throw new Error("Couldn't write file to fs");
+	}
+}
+/**
+* Takes screenshots repeatedly until the page reaches a visually stable state.
+*
+* This function compares consecutive screenshots and continues taking new ones
+* until two consecutive screenshots match according to the provided comparator.
+*
+* The process works as follows:
+*
+* 1. Uses as baseline an optional reference screenshot or takes a new screenshot
+* 2. Takes a screenshot and compares with baseline
+* 3. If they match, the page is considered stable and the function returns
+* 4. If they don't match, it continues with the newer screenshot as the baseline
+* 5. Repeats until stability is achieved or the operation is aborted
+*
+* @returns `Promise` resolving to an object containing the retry count and
+* final screenshot
+*/
+async function getStableScreenshots({ codec, context, comparator, comparatorOptions, element, name, reference, screenshotOptions, signal }) {
+	const screenshotArgument = {
+		codec,
+		context,
+		element,
+		name,
+		screenshotOptions
+	};
+	let retries = 0;
+	let decodedBaseline = reference;
+	while (signal.aborted === false) {
+		if (decodedBaseline === null) {
+			decodedBaseline = takeDecodedScreenshot(screenshotArgument);
+		}
+		const [image1, image2] = await Promise.all([decodedBaseline, takeDecodedScreenshot(screenshotArgument)]);
+		const comparatorResult = (await comparator(image1, image2, {
+			...comparatorOptions,
+			createDiff: false
+		})).pass;
+		decodedBaseline = image2;
+		if (comparatorResult) {
+			break;
+		}
+		retries += 1;
+	}
+	return {
+		retries,
+		actual: await decodedBaseline
+	};
+}
+
 const selectOptions = async (context, selector, userValues, options = {}) => {
 	if (context.provider instanceof PlaywrightBrowserProvider) {
 		const value = userValues;
@@ -2551,7 +2998,8 @@ var builtinCommands = {
 	__vitest_dragAndDrop: dragAndDrop,
 	__vitest_hover: hover,
 	__vitest_cleanup: keyboardCleanup,
-	__vitest_viewport: viewport
+	__vitest_viewport: viewport,
+	__vitest_screenshotMatcher: screenshotMatcher
 };
 
 class BrowserServerState {
@@ -2595,22 +3043,7 @@ class ProjectBrowser {
 		if (this.provider) {
 			return;
 		}
-		const Provider = await getBrowserProvider(project.config.browser, project);
-		this.provider = new Provider();
-		const browser = project.config.browser.name;
-		const name = project.name ? `[${project.name}] ` : "";
-		if (!browser) {
-			throw new Error(`${name}Browser name is required. Please, set \`test.browser.instances[].browser\` option manually.`);
-		}
-		const supportedBrowsers = this.provider.getSupportedBrowsers();
-		if (supportedBrowsers.length && !supportedBrowsers.includes(browser)) {
-			throw new Error(`${name}Browser "${browser}" is not supported by the browser provider "${this.provider.name}". Supported browsers: ${supportedBrowsers.join(", ")}.`);
-		}
-		const providerOptions = project.config.browser.providerOptions;
-		await this.provider.initialize(project, {
-			browser,
-			options: providerOptions
-		});
+		this.provider = await getBrowserProvider(project.config.browser, project);
 	}
 	parseErrorStacktrace(e, options = {}) {
 		return this.parent.parseErrorStacktrace(e, options);
@@ -2631,7 +3064,6 @@ function wrapConfig(config) {
 
 class ParentBrowserProject {
 	orchestratorScripts;
-	testerScripts;
 	faviconUrl;
 	prefixOrchestratorUrl;
 	prefixTesterUrl;
@@ -2677,18 +3109,19 @@ class ParentBrowserProject {
 				return result?.map;
 			},
 			getUrlId: (id) => {
-				const mod = this.vite.moduleGraph.getModuleById(id);
+				const moduleGraph = this.vite.environments.client.moduleGraph;
+				const mod = moduleGraph.getModuleById(id);
 				if (mod) {
 					return id;
 				}
 				const resolvedPath = resolve(this.vite.config.root, id.slice(1));
-				const modUrl = this.vite.moduleGraph.getModuleById(resolvedPath);
+				const modUrl = moduleGraph.getModuleById(resolvedPath);
 				if (modUrl) {
 					return resolvedPath;
 				}
 				// some browsers (looking at you, safari) don't report queries in stack traces
 				// the next best thing is to try the first id that this file resolves to
-				const files = this.vite.moduleGraph.getModulesByFile(resolvedPath);
+				const files = moduleGraph.getModulesByFile(resolvedPath);
 				if (files && files.size) {
 					return files.values().next().value.id;
 				}
@@ -2719,7 +3152,7 @@ class ParentBrowserProject {
 			"webdriverio",
 			"preview"
 		];
-		const providerName = project.config.browser.provider || "preview";
+		const providerName = project.config.browser.provider?.name || "preview";
 		if (builtinProviders.includes(providerName)) {
 			this.locatorsUrl = join("/@fs/", distRoot, "locators", `${providerName}.js`);
 		}
@@ -2841,7 +3274,7 @@ function defaultSerialize(i) {
   return i;
 }
 const defaultDeserialize = defaultSerialize;
-const { clearTimeout, setTimeout } = globalThis;
+const { clearTimeout, setTimeout: setTimeout$1 } = globalThis;
 const random = Math.random.bind(Math);
 function createBirpc(functions, options) {
   const {
@@ -2865,10 +3298,13 @@ function createBirpc(functions, options) {
         return functions;
       if (method === "$close")
         return close;
+      if (method === "$rejectPendingCalls") {
+        return rejectPendingCalls;
+      }
       if (method === "$closed")
         return closed;
       if (method === "then" && !eventNames.includes("then") && !("then" in functions))
-        return undefined;
+        return void 0;
       const sendEvent = (...args) => {
         post(serialize({ m: method, a: args, t: TYPE_REQUEST }));
       };
@@ -2883,14 +3319,14 @@ function createBirpc(functions, options) {
           try {
             await _promise;
           } finally {
-            _promise = undefined;
+            _promise = void 0;
           }
         }
         return new Promise((resolve, reject) => {
           const id = nanoid();
           let timeoutId;
           if (timeout >= 0) {
-            timeoutId = setTimeout(() => {
+            timeoutId = setTimeout$1(() => {
               try {
                 const handleResult = options.onTimeoutError?.(method, args);
                 if (handleResult !== true)
@@ -2911,14 +3347,30 @@ function createBirpc(functions, options) {
       return sendCall;
     }
   });
-  function close(error) {
+  function close(customError) {
     closed = true;
     rpcPromiseMap.forEach(({ reject, method }) => {
-      reject(error || new Error(`[birpc] rpc is closed, cannot call "${method}"`));
+      const error = new Error(`[birpc] rpc is closed, cannot call "${method}"`);
+      if (customError) {
+        customError.cause ??= error;
+        return reject(customError);
+      }
+      reject(error);
     });
     rpcPromiseMap.clear();
     off(onMessage);
   }
+  function rejectPendingCalls(handler) {
+    const entries = Array.from(rpcPromiseMap.values());
+    const handlerResults = entries.map(({ method, reject }) => {
+      if (!handler) {
+        return reject(new Error(`[birpc]: rejected pending call "${method}".`));
+      }
+      return handler({ method, reject });
+    });
+    rpcPromiseMap.clear();
+    return handlerResults;
+  }
   async function onMessage(data, ...extra) {
     let msg;
     try {
@@ -3018,12 +3470,13 @@ function setupBrowserRpc(globalServer, defaultMockerRegistry) {
 		if (!sessionId || !rpcId || projectName == null) {
 			return error(new Error(`[vitest] Invalid URL ${request.url}. "projectName", "sessionId" and "rpcId" queries are required.`));
 		}
-		if (!vitest._browserSessions.sessionIds.has(sessionId)) {
-			const ids = [...vitest._browserSessions.sessionIds].join(", ");
+		const sessions = vitest._browserSessions;
+		if (!sessions.sessionIds.has(sessionId)) {
+			const ids = [...sessions.sessionIds].join(", ");
 			return error(new Error(`[vitest] Unknown session id "${sessionId}". Expected one of ${ids}.`));
 		}
 		if (type === "orchestrator") {
-			const session = vitest._browserSessions.getSession(sessionId);
+			const session = sessions.getSession(sessionId);
 			// it's possible the session was already resolved by the preview provider
 			session?.connected();
 		}
@@ -3043,7 +3496,7 @@ function setupBrowserRpc(globalServer, defaultMockerRegistry) {
 				clients.delete(rpcId);
 				globalServer.removeCDPHandler(rpcId);
 				if (type === "orchestrator") {
-					vitest._browserSessions.destroySession(sessionId);
+					sessions.destroySession(sessionId);
 				}
 				// this will reject any hanging methods if there are any
 				rpc.$close(new Error(`[vitest] Browser connection was closed while running tests. Was the page closed unexpectedly?`));
@@ -3061,7 +3514,7 @@ function setupBrowserRpc(globalServer, defaultMockerRegistry) {
 		}
 	}
 	function setupClient(project, rpcId, ws) {
-		const mockResolver = new ServerMockResolver(globalServer.vite, { moduleDirectories: project.config.server?.deps?.moduleDirectories });
+		const mockResolver = new ServerMockResolver(globalServer.vite, { moduleDirectories: project.config?.deps?.moduleDirectories });
 		const mocker = project.browser?.provider.mocker;
 		const rpc = createBirpc({
 			async onUnhandledError(error, type) {
@@ -3252,11 +3705,8 @@ function setupBrowserRpc(globalServer, defaultMockerRegistry) {
 			on: (fn) => ws.on("message", fn),
 			eventNames: ["onCancel", "cdpEvent"],
 			serialize: (data) => stringify(data, stringifyReplace),
-			timeout: -1,
 			deserialize: parse,
-			onTimeoutError(functionName) {
-				throw new Error(`[vitest-api]: Timeout calling "${functionName}"`);
-			}
+			timeout: -1
 		});
 		vitest.onCancel((reason) => rpc.onCancel(reason));
 		return rpc;
@@ -3349,14 +3799,15 @@ function createBrowserPool(vitest) {
 		}
 		const parallelPools = [];
 		const nonParallelPools = [];
-		for (const result of initialisedPools) {
-			if (!result) {
+		for (const pool of initialisedPools) {
+			if (!pool) {
+				// this means it was cancelled
 				return;
 			}
-			if (result.provider.mocker && result.provider.supportsParallelism) {
-				parallelPools.push(result.runTests);
+			if (pool.provider.mocker && pool.provider.supportsParallelism) {
+				parallelPools.push(pool.runTests);
 			} else {
-				nonParallelPools.push(result.runTests);
+				nonParallelPools.push(pool.runTests);
 			}
 		}
 		await Promise.all(parallelPools.map((runTests) => runTests()));
@@ -3515,7 +3966,7 @@ class BrowserPool {
 				debug?.("[%s] test %s finished running", sessionId, file);
 				this.runNextTest(method, sessionId);
 			}).catch((error) => {
-				// if user cancells the test run manually, ignore the error and exit gracefully
+				// if user cancels the test run manually, ignore the error and exit gracefully
 				if (this.project.vitest.isCancelling && error instanceof Error && error.message.startsWith("Browser connection was closed while running tests")) {
 					this.cancel();
 					this._promise?.resolve();