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

package/dist/providers/webdriverio.js

@@ -0,0 +1,171 @@
+import { createDebugger } from 'vitest/node';
+
+const debug = createDebugger("vitest:browser:wdio");
+const webdriverBrowsers = [
+	"firefox",
+	"chrome",
+	"edge",
+	"safari"
+];
+function webdriverio(options = {}) {
+	return {
+		name: "webdriverio",
+		supportedBrowser: webdriverBrowsers,
+		factory(project) {
+			return new WebdriverBrowserProvider(project, options);
+		},
+		_cli: true
+	};
+}
+class WebdriverBrowserProvider {
+	name = "webdriverio";
+	supportsParallelism = false;
+	browser = null;
+	browserName;
+	project;
+	options;
+	closing = false;
+	iframeSwitched = false;
+	topLevelContext;
+	getSupportedBrowsers() {
+		return webdriverBrowsers;
+	}
+	constructor(project, options) {
+		// increase shutdown timeout because WDIO takes some extra time to kill the driver
+		if (!project.vitest.state._data.timeoutIncreased) {
+			project.vitest.state._data.timeoutIncreased = true;
+			project.vitest.config.teardownTimeout += 1e4;
+		}
+		this.closing = false;
+		this.project = project;
+		this.browserName = project.config.browser.name;
+		this.options = options;
+	}
+	isIframeSwitched() {
+		return this.iframeSwitched;
+	}
+	async switchToTestFrame() {
+		const browser = this.browser;
+		// support wdio@9
+		if (browser.switchFrame) {
+			await browser.switchFrame(browser.$("iframe[data-vitest]"));
+		} else {
+			const iframe = await browser.findElement("css selector", "iframe[data-vitest]");
+			await browser.switchToFrame(iframe);
+		}
+		this.iframeSwitched = true;
+	}
+	async switchToMainFrame() {
+		const page = this.browser;
+		if (page.switchFrame) {
+			await page.switchFrame(null);
+		} else {
+			await page.switchToParentFrame();
+		}
+		this.iframeSwitched = false;
+	}
+	async setViewport(options) {
+		if (this.topLevelContext == null || !this.browser) {
+			throw new Error(`The browser has no open pages.`);
+		}
+		await this.browser.send({
+			method: "browsingContext.setViewport",
+			params: {
+				context: this.topLevelContext,
+				devicePixelRatio: 1,
+				viewport: options
+			}
+		});
+	}
+	getCommandsContext() {
+		return { browser: this.browser };
+	}
+	async openBrowser() {
+		await this._throwIfClosing("opening the browser");
+		if (this.browser) {
+			debug?.("[%s] the browser is already opened, reusing it", this.browserName);
+			return this.browser;
+		}
+		const options = this.project.config.browser;
+		if (this.browserName === "safari") {
+			if (options.headless) {
+				throw new Error("You've enabled headless mode for Safari but it doesn't currently support it.");
+			}
+		}
+		const { remote } = await import('webdriverio');
+		const remoteOptions = {
+			logLevel: "silent",
+			...this.options,
+			capabilities: this.buildCapabilities()
+		};
+		debug?.("[%s] opening the browser with options: %O", this.browserName, remoteOptions);
+		// TODO: close everything, if browser is closed from the outside
+		this.browser = await remote(remoteOptions);
+		await this._throwIfClosing();
+		return this.browser;
+	}
+	buildCapabilities() {
+		const capabilities = {
+			...this.options?.capabilities,
+			browserName: this.browserName
+		};
+		const headlessMap = {
+			chrome: ["goog:chromeOptions", ["headless", "disable-gpu"]],
+			firefox: ["moz:firefoxOptions", ["-headless"]],
+			edge: ["ms:edgeOptions", ["--headless"]]
+		};
+		const options = this.project.config.browser;
+		const browser = this.browserName;
+		if (browser !== "safari" && options.headless) {
+			const [key, args] = headlessMap[browser];
+			const currentValues = (this.options?.capabilities)?.[key] || {};
+			const newArgs = [...currentValues.args || [], ...args];
+			capabilities[key] = {
+				...currentValues,
+				args: newArgs
+			};
+		}
+		// start Vitest UI maximized only on supported browsers
+		if (options.ui && (browser === "chrome" || browser === "edge")) {
+			const key = browser === "chrome" ? "goog:chromeOptions" : "ms:edgeOptions";
+			const args = capabilities[key]?.args || [];
+			if (!args.includes("--start-maximized") && !args.includes("--start-fullscreen")) {
+				args.push("--start-maximized");
+			}
+			capabilities[key] ??= {};
+			capabilities[key].args = args;
+		}
+		return capabilities;
+	}
+	async openPage(sessionId, url) {
+		await this._throwIfClosing("creating the browser");
+		debug?.("[%s][%s] creating the browser page for %s", sessionId, this.browserName, url);
+		const browserInstance = await this.openBrowser();
+		debug?.("[%s][%s] browser page is created, opening %s", sessionId, this.browserName, url);
+		await browserInstance.url(url);
+		this.topLevelContext = await browserInstance.getWindowHandle();
+		await this._throwIfClosing("opening the url");
+	}
+	async _throwIfClosing(action) {
+		if (this.closing) {
+			debug?.(`[%s] provider was closed, cannot perform the action${action ? ` ${action}` : ""}`, this.browserName);
+			await (this.browser?.sessionId ? this.browser?.deleteSession?.() : null);
+			throw new Error(`[vitest] The provider was closed.`);
+		}
+	}
+	async close() {
+		debug?.("[%s] closing provider", this.browserName);
+		this.closing = true;
+		const browser = this.browser;
+		const sessionId = browser?.sessionId;
+		if (!browser || !sessionId) {
+			return;
+		}
+		// https://github.com/webdriverio/webdriverio/blob/ab1a2e82b13a9c7d0e275ae87e7357e1b047d8d3/packages/wdio-runner/src/index.ts#L486
+		await browser.deleteSession();
+		browser.sessionId = undefined;
+		this.browser = null;
+	}
+}
+
+export { WebdriverBrowserProvider, webdriverio };

package/dist/shared/screenshotMatcher/types.d.ts

@@ -0,0 +1,16 @@
+import type { ScreenshotComparatorRegistry, ScreenshotMatcherOptions } from "../../../context.js";
+export type ScreenshotMatcherArguments<ComparatorName extends keyof ScreenshotComparatorRegistry = keyof ScreenshotComparatorRegistry> = [name: string, testName: string, options: ScreenshotMatcherOptions<ComparatorName> & {
+	element: string;
+	screenshotOptions?: ScreenshotMatcherOptions<ComparatorName>["screenshotOptions"] & {
+		mask?: readonly string[];
+	};
+}];
+export type ScreenshotMatcherOutput = Promise<{
+	pass: false;
+	reference: string | null;
+	actual: string | null;
+	diff: string | null;
+	message: string;
+} | {
+	pass: true;
+}>;

package/dist/state.js

@@ -12,7 +12,6 @@
   const state = {
   	ctx: {
   		pool: "browser",
-  		worker: "./browser.js",
   		workerId: 1,
   		config,
   		projectName: config.name || "",
@@ -28,14 +27,16 @@
   	config,
   	environment: {
   		name: "browser",
-  		transformMode: "web",
+  		viteEnvironment: "client",
   		setup() {
   			throw new Error("Not called in the browser");
   		}
   	},
   	onCleanup: (fn) => getBrowserState().cleanups.push(fn),
-  	moduleCache: getBrowserState().moduleCache,
+  	evaluatedModules: getBrowserState().evaluatedModules,
+  	resolvingModules: getBrowserState().resolvingModules,
   	moduleExecutionInfo: new Map(),
+  	metaEnv: null,
   	rpc: null,
   	durations: {
   		environment: 0,

package/dist/types.d.ts

@@ -22,24 +22,22 @@ export interface WebSocketBrowserHandlers {
 	resolveId: (id: string, importer?: string) => Promise<ServerIdResolution | null>;
 	triggerCommand: <T>(sessionId: string, command: string, testPath: string | undefined, payload: unknown[]) => Promise<T>;
 	resolveMock: (id: string, importer: string, options: {
-		mock: "spy" | "factory" | "auto"
+		mock: "spy" | "factory" | "auto";
 	}) => Promise<ServerMockResolution>;
 	invalidate: (ids: string[]) => void;
 	getBrowserFileSourceMap: (id: string) => SourceMap | null | {
-		mappings: ""
+		mappings: "";
 	} | undefined;
 	wdioSwitchContext: (direction: "iframe" | "parent") => void;
 	registerMock: (sessionId: string, mock: MockedModuleSerialized) => void;
 	unregisterMock: (sessionId: string, id: string) => void;
 	clearMocks: (sessionId: string) => void;
-	// cdp
 	sendCdpEvent: (sessionId: string, event: string, payload?: Record<string, unknown>) => unknown;
 	trackCdpEvent: (sessionId: string, type: "on" | "once" | "off", event: string, listenerId: string) => void;
 }
 export type Awaitable<T> = T | PromiseLike<T>;
 export interface WebSocketEvents {
 	onCollected?: (files: RunnerTestFile[]) => Awaitable<void>;
-	onFinished?: (files: File[], errors: unknown[], coverage?: unknown) => Awaitable<void>;
 	onTaskUpdate?: (packs: TaskResultPack[]) => Awaitable<void>;
 	onUserConsoleLog?: (log: UserConsoleLog) => Awaitable<void>;
 	onPathsCollected?: (paths?: string[]) => Awaitable<void>;
@@ -52,9 +50,9 @@ export interface WebSocketBrowserEvents {
 	cleanupTesters: () => Promise<void>;
 	cdpEvent: (event: string, payload: unknown) => void;
 	resolveManualMock: (url: string) => Promise<{
-		url: string
-		keys: string[]
-		responseId: string
+		url: string;
+		keys: string[];
+		responseId: string;
 	}>;
 }
 export type WebSocketBrowserRPC = BirpcReturn<WebSocketBrowserEvents, WebSocketBrowserHandlers>;

package/jest-dom.d.ts

@@ -1,6 +1,7 @@
 // Disable automatic exports.
 
 import { ARIARole } from './aria-role.ts'
+import { ScreenshotComparatorRegistry, ScreenshotMatcherOptions } from './context.js'
 
 export interface TestingLibraryMatchers<E, R> {
   /**
@@ -14,6 +15,52 @@ export interface TestingLibraryMatchers<E, R> {
    * @see https://vitest.dev/guide/browser/assertion-api#tobeinthedocument
    */
   toBeInTheDocument(): R
+  /**
+   * @description
+   * Assert whether an element is within the viewport or not.
+   *
+   * An element is considered to be in the viewport if any part of it intersects with the current viewport bounds.
+   * This matcher calculates the intersection ratio between the element and the viewport, similar to the
+   * IntersectionObserver API.
+   *
+   * The element must be in the document and have visible dimensions. Elements with display: none or 
+   * visibility: hidden are considered not in viewport.
+   * @example
+   * <div
+   *   data-testid="visible-element"
+   *   style="position: absolute; top: 10px; left: 10px; width: 50px; height: 50px;"
+   * >
+   *   Visible Element
+   * </div>
+   *
+   * <div
+   *   data-testid="hidden-element" 
+   *   style="position: fixed; top: -100px; left: 10px; width: 50px; height: 50px;"
+   * >
+   *   Hidden Element
+   * </div>
+   *
+   * <div
+   *   data-testid="large-element"
+   *   style="height: 400vh;"
+   * >
+   *   Large Element
+   * </div>
+   *
+   * // Check if any part of element is in viewport
+   * await expect.element(page.getByTestId('visible-element')).toBeInViewport()
+   * 
+   * // Check if element is outside viewport
+   * await expect.element(page.getByTestId('hidden-element')).not.toBeInViewport()
+   * 
+   * // Check if at least 50% of element is visible
+   * await expect.element(page.getByTestId('large-element')).toBeInViewport({ ratio: 0.5 })
+   * 
+   * // Check if element is completely visible
+   * await expect.element(page.getByTestId('visible-element')).toBeInViewport({ ratio: 1 })
+   * @see https://vitest.dev/guide/browser/assertion-api#tobeinviewport
+   */
+  toBeInViewport(options?: { ratio?: number }): R
   /**
    * @description
    * This allows you to check if an element is currently visible to the user.
@@ -580,7 +627,7 @@ export interface TestingLibraryMatchers<E, R> {
    * other element that contains text, such as a paragraph, span, div etc.
    *
    * NOTE: the expected selection is a string, it does not allow to check for
-   * selection range indeces.
+   * selection range indices.
    *
    * @example
    * <div>
@@ -627,4 +674,51 @@ export interface TestingLibraryMatchers<E, R> {
    * @see https://vitest.dev/guide/browser/assertion-api#tohaveselection
    */
   toHaveSelection(selection?: string): R
+
+  /**
+   * @description
+   * This assertion allows you to perform visual regression testing by comparing
+   * screenshots of elements or pages against stored reference images.
+   *
+   * When differences are detected beyond the configured threshold, the test fails.
+   * To help identify the changes, the assertion generates:
+   *
+   * - The actual screenshot captured during the test
+   * - The expected reference screenshot
+   * - A diff image highlighting the differences (when possible)
+   *
+   * @example
+   * <button data-testid="button">Fancy Button</button>
+   *
+   * // basic usage, auto-generates screenshot name
+   * await expect.element(getByTestId('button')).toMatchScreenshot()
+   *
+   * // with custom name
+   * await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button')
+   *
+   * // with options
+   * await expect.element(getByTestId('button')).toMatchScreenshot({
+   *   comparatorName: 'pixelmatch',
+   *   comparatorOptions: {
+   *     allowedMismatchedPixelRatio: 0.01,
+   *   },
+   * })
+   *
+   * // with both name and options
+   * await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button', {
+   *   comparatorName: 'pixelmatch',
+   *   comparatorOptions: {
+   *     allowedMismatchedPixelRatio: 0.01,
+   *   },
+   * })
+   *
+   * @see https://vitest.dev/guide/browser/assertion-api#tomatchscreenshot
+   */
+  toMatchScreenshot<ComparatorName extends keyof ScreenshotComparatorRegistry>(
+    options?: ScreenshotMatcherOptions<ComparatorName>,
+  ): Promise<R>
+  toMatchScreenshot<ComparatorName extends keyof ScreenshotComparatorRegistry>(
+    name?: string,
+    options?: ScreenshotMatcherOptions<ComparatorName>,
+  ): Promise<R>
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vitest/browser",
   "type": "module",
-  "version": "4.0.0-beta.1",
+  "version": "4.0.0-beta.11",
   "description": "Browser running for Vitest",
   "license": "MIT",
   "funding": "https://opencollective.com/vitest",
@@ -20,9 +20,9 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./providers": {
-      "types": "./providers.d.ts",
-      "default": "./dist/providers.js"
+    "./providers/*": {
+      "types": "./dist/providers/*.d.ts",
+      "default": "./dist/providers/*.js"
     },
     "./context": {
       "types": "./context.d.ts",
@@ -35,14 +35,6 @@
       "types": "./matchers.d.ts",
       "default": "./dummy.js"
     },
-    "./providers/webdriverio": {
-      "types": "./providers/webdriverio.d.ts",
-      "default": "./dummy.js"
-    },
-    "./providers/playwright": {
-      "types": "./providers/playwright.d.ts",
-      "default": "./dummy.js"
-    },
     "./locator": {
       "types": "./dist/locators/index.d.ts",
       "default": "./dist/locators/index.js"
@@ -66,7 +58,7 @@
   "peerDependencies": {
     "playwright": "*",
     "webdriverio": "^7.0.0 || ^8.0.0 || ^9.0.0",
-    "vitest": "4.0.0-beta.1"
+    "vitest": "4.0.0-beta.11"
   },
   "peerDependenciesMeta": {
     "playwright": {
@@ -80,33 +72,31 @@
     }
   },
   "dependencies": {
-    "@testing-library/dom": "^10.4.0",
+    "@testing-library/dom": "^10.4.1",
     "@testing-library/user-event": "^14.6.1",
-    "magic-string": "^0.30.17",
-    "sirv": "^3.0.1",
-    "tinyrainbow": "^2.0.0",
-    "ws": "^8.18.2",
-    "@vitest/mocker": "4.0.0-beta.1",
-    "@vitest/utils": "4.0.0-beta.1"
+    "magic-string": "^0.30.19",
+    "pixelmatch": "7.1.0",
+    "pngjs": "^7.0.0",
+    "sirv": "^3.0.2",
+    "tinyrainbow": "^3.0.3",
+    "ws": "^8.18.3",
+    "@vitest/mocker": "4.0.0-beta.11",
+    "@vitest/utils": "4.0.0-beta.11"
   },
   "devDependencies": {
+    "@types/pngjs": "^6.0.5",
     "@types/ws": "^8.18.1",
-    "@wdio/protocols": "^9.15.0",
-    "@wdio/types": "^9.15.0",
-    "birpc": "2.4.0",
+    "@wdio/types": "^9.19.2",
+    "birpc": "^2.5.0",
     "flatted": "^3.3.3",
     "ivya": "^1.7.0",
     "mime": "^4.0.7",
     "pathe": "^2.0.3",
-    "periscopic": "^4.0.2",
-    "playwright": "^1.53.0",
-    "playwright-core": "^1.53.0",
-    "safaridriver": "^1.0.0",
-    "webdriverio": "^9.15.0",
-    "@vitest/ui": "4.0.0-beta.1",
-    "@vitest/runner": "4.0.0-beta.1",
-    "vitest": "4.0.0-beta.1",
-    "@vitest/ws-client": "4.0.0-beta.1"
+    "playwright": "^1.55.0",
+    "playwright-core": "^1.55.0",
+    "webdriverio": "^9.19.2",
+    "@vitest/runner": "4.0.0-beta.11",
+    "vitest": "4.0.0-beta.11"
   },
   "scripts": {
     "typecheck": "tsc -p ./src/client/tsconfig.json --noEmit",

package/utils.d.ts

@@ -1,5 +1,5 @@
 // should be in sync with tester/public-utils.ts
-// we cannot bundle it because vitest depend on the @vitest/browser and vise versa
+// we cannot bundle it because vitest depend on the @vitest/browser and vice versa
 // fortunately, the file is quite small
 
 import { LocatorSelectors, Locator } from '@vitest/browser/context'