@vitest/browser 4.0.0-beta.3 → 4.0.0-beta.5

package/dist/locators/index.js

@@ -1 +1 @@
-import"@vitest/browser/context";import"../public-utils-Kx5DUGWa.js";export{L as Locator,s as selectorEngine}from"../index-W1MM53zC.js";import"vitest/internal/browser";
+import"@vitest/browser/context";import"../public-utils-Kx5DUGWa.js";export{L as Locator,s as selectorEngine}from"../index-D_g_FMM5.js";import"vitest/internal/browser";

package/dist/locators/playwright.js

@@ -1 +1 @@
-import{page,server}from"@vitest/browser/context";import{g as getByTitleSelector,a as getByTextSelector,b as getByPlaceholderSelector,c as getByAltTextSelector,d as getByTestIdSelector,e as getByRoleSelector,f as getByLabelSelector}from"../public-utils-Kx5DUGWa.js";import{s as selectorEngine,L as Locator,p as processTimeoutOptions,g as getIframeScale}from"../index-W1MM53zC.js";import"vitest/internal/browser";page.extend({getByLabelText(e,_){return new PlaywrightLocator(getByLabelSelector(e,_))},getByRole(e,_){return new PlaywrightLocator(getByRoleSelector(e,_))},getByTestId(e){return new PlaywrightLocator(getByTestIdSelector(server.config.browser.locators.testIdAttribute,e))},getByAltText(e,_){return new PlaywrightLocator(getByAltTextSelector(e,_))},getByPlaceholder(e,_){return new PlaywrightLocator(getByPlaceholderSelector(e,_))},getByText(e,_){return new PlaywrightLocator(getByTextSelector(e,_))},getByTitle(e,_){return new PlaywrightLocator(getByTitleSelector(e,_))},_createLocator(e){return new PlaywrightLocator(e)},elementLocator(e){return new PlaywrightLocator(selectorEngine.generateSelectorSimple(e),e)}});class PlaywrightLocator extends Locator{constructor(e,_){super(),this.selector=e,this._container=_}click(e){return super.click(processTimeoutOptions(processClickOptions(e)))}dblClick(e){return super.dblClick(processTimeoutOptions(processClickOptions(e)))}tripleClick(e){return super.tripleClick(processTimeoutOptions(processClickOptions(e)))}selectOptions(e,_){return super.selectOptions(e,processTimeoutOptions(_))}clear(e){return super.clear(processTimeoutOptions(e))}hover(e){return super.hover(processTimeoutOptions(processHoverOptions(e)))}upload(e,_){return super.upload(e,processTimeoutOptions(_))}fill(e,_){return super.fill(e,processTimeoutOptions(_))}dropTo(e,_){return super.dropTo(e,processTimeoutOptions(processDragAndDropOptions(_)))}locator(e){return new PlaywrightLocator(`${this.selector} >> ${e}`,this._container)}elementLocator(e){return new PlaywrightLocator(selectorEngine.generateSelectorSimple(e),e)}}function processDragAndDropOptions(e){if(!e)return e;let _=e;return _.sourcePosition&&=processPlaywrightPosition(_.sourcePosition),_.targetPosition&&=processPlaywrightPosition(_.targetPosition),e}function processHoverOptions(e){if(!e)return e;let _=e;return _.position&&=processPlaywrightPosition(_.position),e}function processClickOptions(e){if(!e)return e;let _=e;return _.position&&=processPlaywrightPosition(_.position),_}function processPlaywrightPosition(e){let _=getIframeScale();return e.x!=null&&(e.x*=_),e.y!=null&&(e.y*=_),e}
+import{page,server}from"@vitest/browser/context";import{g as getByTitleSelector,a as getByTextSelector,b as getByPlaceholderSelector,c as getByAltTextSelector,d as getByTestIdSelector,e as getByRoleSelector,f as getByLabelSelector}from"../public-utils-Kx5DUGWa.js";import{s as selectorEngine,L as Locator,p as processTimeoutOptions,g as getIframeScale}from"../index-D_g_FMM5.js";import"vitest/internal/browser";page.extend({getByLabelText(e,_){return new PlaywrightLocator(getByLabelSelector(e,_))},getByRole(e,_){return new PlaywrightLocator(getByRoleSelector(e,_))},getByTestId(e){return new PlaywrightLocator(getByTestIdSelector(server.config.browser.locators.testIdAttribute,e))},getByAltText(e,_){return new PlaywrightLocator(getByAltTextSelector(e,_))},getByPlaceholder(e,_){return new PlaywrightLocator(getByPlaceholderSelector(e,_))},getByText(e,_){return new PlaywrightLocator(getByTextSelector(e,_))},getByTitle(e,_){return new PlaywrightLocator(getByTitleSelector(e,_))},_createLocator(e){return new PlaywrightLocator(e)},elementLocator(e){return new PlaywrightLocator(selectorEngine.generateSelectorSimple(e),e)}});class PlaywrightLocator extends Locator{constructor(e,_){super(),this.selector=e,this._container=_}click(e){return super.click(processTimeoutOptions(processClickOptions(e)))}dblClick(e){return super.dblClick(processTimeoutOptions(processClickOptions(e)))}tripleClick(e){return super.tripleClick(processTimeoutOptions(processClickOptions(e)))}selectOptions(e,_){return super.selectOptions(e,processTimeoutOptions(_))}clear(e){return super.clear(processTimeoutOptions(e))}hover(e){return super.hover(processTimeoutOptions(processHoverOptions(e)))}upload(e,_){return super.upload(e,processTimeoutOptions(_))}fill(e,_){return super.fill(e,processTimeoutOptions(_))}dropTo(e,_){return super.dropTo(e,processTimeoutOptions(processDragAndDropOptions(_)))}locator(e){return new PlaywrightLocator(`${this.selector} >> ${e}`,this._container)}elementLocator(e){return new PlaywrightLocator(selectorEngine.generateSelectorSimple(e),e)}}function processDragAndDropOptions(e){if(!e)return e;let _=e;return _.sourcePosition&&=processPlaywrightPosition(_.sourcePosition),_.targetPosition&&=processPlaywrightPosition(_.targetPosition),e}function processHoverOptions(e){if(!e)return e;let _=e;return _.position&&=processPlaywrightPosition(_.position),e}function processClickOptions(e){if(!e)return e;let _=e;return _.position&&=processPlaywrightPosition(_.position),_}function processPlaywrightPosition(e){let _=getIframeScale();return e.x!=null&&(e.x*=_),e.y!=null&&(e.y*=_),e}

package/dist/locators/preview.js

@@ -1 +1 @@
-import{page,server,userEvent}from"@vitest/browser/context";import{g as getByTitleSelector,a as getByTextSelector,b as getByPlaceholderSelector,c as getByAltTextSelector,d as getByTestIdSelector,e as getByRoleSelector,f as getByLabelSelector,h as getElementError}from"../public-utils-Kx5DUGWa.js";import{s as selectorEngine,L as Locator,c as convertElementToCssSelector}from"../index-W1MM53zC.js";import"vitest/internal/browser";page.extend({getByLabelText(e,m){return new PreviewLocator(getByLabelSelector(e,m))},getByRole(e,m){return new PreviewLocator(getByRoleSelector(e,m))},getByTestId(e){return new PreviewLocator(getByTestIdSelector(server.config.browser.locators.testIdAttribute,e))},getByAltText(e,m){return new PreviewLocator(getByAltTextSelector(e,m))},getByPlaceholder(e,m){return new PreviewLocator(getByPlaceholderSelector(e,m))},getByText(e,m){return new PreviewLocator(getByTextSelector(e,m))},getByTitle(e,m){return new PreviewLocator(getByTitleSelector(e,m))},_createLocator(e){return new PreviewLocator(e)},elementLocator(e){return new PreviewLocator(selectorEngine.generateSelectorSimple(e),e)}});class PreviewLocator extends Locator{constructor(e,m){super(),this._pwSelector=e,this._container=m}get selector(){let e=this.elements().map(e=>convertElementToCssSelector(e));if(!e.length)throw getElementError(this._pwSelector,this._container||document.body);return e.join(`, `)}click(){return userEvent.click(this.element())}dblClick(){return userEvent.dblClick(this.element())}tripleClick(){return userEvent.tripleClick(this.element())}hover(){return userEvent.hover(this.element())}unhover(){return userEvent.unhover(this.element())}async fill(e){return userEvent.fill(this.element(),e)}async upload(e){return userEvent.upload(this.element(),e)}selectOptions(e){return userEvent.selectOptions(this.element(),e)}clear(){return userEvent.clear(this.element())}locator(e){return new PreviewLocator(`${this._pwSelector} >> ${e}`,this._container)}elementLocator(e){return new PreviewLocator(selectorEngine.generateSelectorSimple(e),e)}}
+import{page,server,userEvent}from"@vitest/browser/context";import{g as getByTitleSelector,a as getByTextSelector,b as getByPlaceholderSelector,c as getByAltTextSelector,d as getByTestIdSelector,e as getByRoleSelector,f as getByLabelSelector,h as getElementError}from"../public-utils-Kx5DUGWa.js";import{s as selectorEngine,L as Locator,c as convertElementToCssSelector}from"../index-D_g_FMM5.js";import"vitest/internal/browser";page.extend({getByLabelText(e,m){return new PreviewLocator(getByLabelSelector(e,m))},getByRole(e,m){return new PreviewLocator(getByRoleSelector(e,m))},getByTestId(e){return new PreviewLocator(getByTestIdSelector(server.config.browser.locators.testIdAttribute,e))},getByAltText(e,m){return new PreviewLocator(getByAltTextSelector(e,m))},getByPlaceholder(e,m){return new PreviewLocator(getByPlaceholderSelector(e,m))},getByText(e,m){return new PreviewLocator(getByTextSelector(e,m))},getByTitle(e,m){return new PreviewLocator(getByTitleSelector(e,m))},_createLocator(e){return new PreviewLocator(e)},elementLocator(e){return new PreviewLocator(selectorEngine.generateSelectorSimple(e),e)}});class PreviewLocator extends Locator{constructor(e,m){super(),this._pwSelector=e,this._container=m}get selector(){let e=this.elements().map(e=>convertElementToCssSelector(e));if(!e.length)throw getElementError(this._pwSelector,this._container||document.body);return e.join(`, `)}click(){return userEvent.click(this.element())}dblClick(){return userEvent.dblClick(this.element())}tripleClick(){return userEvent.tripleClick(this.element())}hover(){return userEvent.hover(this.element())}unhover(){return userEvent.unhover(this.element())}async fill(e){return userEvent.fill(this.element(),e)}async upload(e){return userEvent.upload(this.element(),e)}selectOptions(e){return userEvent.selectOptions(this.element(),e)}clear(){return userEvent.clear(this.element())}locator(e){return new PreviewLocator(`${this._pwSelector} >> ${e}`,this._container)}elementLocator(e){return new PreviewLocator(selectorEngine.generateSelectorSimple(e),e)}}

package/dist/locators/webdriverio.js

@@ -1 +1 @@
-import{page,server}from"@vitest/browser/context";import{g as getByTitleSelector,a as getByTextSelector,b as getByPlaceholderSelector,c as getByAltTextSelector,d as getByTestIdSelector,e as getByRoleSelector,f as getByLabelSelector,h as getElementError}from"../public-utils-Kx5DUGWa.js";import{s as selectorEngine,L as Locator,c as convertElementToCssSelector,a as getBrowserState,g as getIframeScale}from"../index-W1MM53zC.js";import"vitest/internal/browser";page.extend({getByLabelText(e,g){return new WebdriverIOLocator(getByLabelSelector(e,g))},getByRole(e,g){return new WebdriverIOLocator(getByRoleSelector(e,g))},getByTestId(e){return new WebdriverIOLocator(getByTestIdSelector(server.config.browser.locators.testIdAttribute,e))},getByAltText(e,g){return new WebdriverIOLocator(getByAltTextSelector(e,g))},getByPlaceholder(e,g){return new WebdriverIOLocator(getByPlaceholderSelector(e,g))},getByText(e,g){return new WebdriverIOLocator(getByTextSelector(e,g))},getByTitle(e,g){return new WebdriverIOLocator(getByTitleSelector(e,g))},_createLocator(e){return new WebdriverIOLocator(e)},elementLocator(e){return new WebdriverIOLocator(selectorEngine.generateSelectorSimple(e))}});class WebdriverIOLocator extends Locator{constructor(e,g){super(),this._pwSelector=e,this._container=g}get selector(){let e=this.elements().map(e=>convertElementToCssSelector(e));if(!e.length)throw getElementError(this._pwSelector,this._container||document.body);return e.join(`, `)}click(e){return super.click(processClickOptions(e))}dblClick(e){return super.dblClick(processClickOptions(e))}tripleClick(e){return super.tripleClick(processClickOptions(e))}selectOptions(e,g){let _=getWebdriverioSelectOptions(this.element(),e);return this.triggerCommand(`__vitest_selectOptions`,this.selector,_,g)}hover(e){return super.hover(processHoverOptions(e))}dropTo(e,g){return super.dropTo(e,processDragAndDropOptions(g))}locator(e){return new WebdriverIOLocator(`${this._pwSelector} >> ${e}`,this._container)}elementLocator(e){return new WebdriverIOLocator(selectorEngine.generateSelectorSimple(e),e)}}function getWebdriverioSelectOptions(e,g){let _=[...e.querySelectorAll(`option`)],v=Array.isArray(g)?g:[g];if(!v.length)return[];if(v.length>1)throw Error(`Provider "webdriverio" doesn't support selecting multiple values at once`);let y=v[0];if(typeof y!=`string`){let e=`element`in y?y.element():y,g=_.indexOf(e);if(g===-1)throw Error(`The element ${selectorEngine.previewNode(e)} was not found in the "select" options.`);return[{index:g}]}let b=_.findIndex(e=>e.value===y);if(b!==-1)return[{index:b}];let x=_.findIndex(e=>e.textContent?.trim()===y||e.ariaLabel===y);if(x===-1)throw Error(`The option "${y}" was not found in the "select" options.`);return[{index:x}]}function processClickOptions(e){if(!e||!getBrowserState().config.browser.ui)return e;let g=e;if(g.x!=null||g.y!=null){let e={};g.x!=null&&(g.x=scaleCoordinate(g.x,e)),g.y!=null&&(g.y=scaleCoordinate(g.y,e))}return e}function processHoverOptions(e){if(!e||!getBrowserState().config.browser.ui)return e;let g=e,_={};return g.xOffset!=null&&(g.xOffset=scaleCoordinate(g.xOffset,_)),g.yOffset!=null&&(g.yOffset=scaleCoordinate(g.yOffset,_)),e}function processDragAndDropOptions(e){if(!e||!getBrowserState().config.browser.ui)return e;let g={},_=e;return _.sourceX!=null&&(_.sourceX=scaleCoordinate(_.sourceX,g)),_.sourceY!=null&&(_.sourceY=scaleCoordinate(_.sourceY,g)),_.targetX!=null&&(_.targetX=scaleCoordinate(_.targetX,g)),_.targetY!=null&&(_.targetY=scaleCoordinate(_.targetY,g)),e}function scaleCoordinate(e,g){return Math.round(e*getCachedScale(g))}function getCachedScale(e){return e.scale??=getIframeScale()}
+import{page,server}from"@vitest/browser/context";import{g as getByTitleSelector,a as getByTextSelector,b as getByPlaceholderSelector,c as getByAltTextSelector,d as getByTestIdSelector,e as getByRoleSelector,f as getByLabelSelector,h as getElementError}from"../public-utils-Kx5DUGWa.js";import{s as selectorEngine,L as Locator,c as convertElementToCssSelector,a as getBrowserState,g as getIframeScale}from"../index-D_g_FMM5.js";import"vitest/internal/browser";page.extend({getByLabelText(e,g){return new WebdriverIOLocator(getByLabelSelector(e,g))},getByRole(e,g){return new WebdriverIOLocator(getByRoleSelector(e,g))},getByTestId(e){return new WebdriverIOLocator(getByTestIdSelector(server.config.browser.locators.testIdAttribute,e))},getByAltText(e,g){return new WebdriverIOLocator(getByAltTextSelector(e,g))},getByPlaceholder(e,g){return new WebdriverIOLocator(getByPlaceholderSelector(e,g))},getByText(e,g){return new WebdriverIOLocator(getByTextSelector(e,g))},getByTitle(e,g){return new WebdriverIOLocator(getByTitleSelector(e,g))},_createLocator(e){return new WebdriverIOLocator(e)},elementLocator(e){return new WebdriverIOLocator(selectorEngine.generateSelectorSimple(e))}});class WebdriverIOLocator extends Locator{constructor(e,g){super(),this._pwSelector=e,this._container=g}get selector(){let e=this.elements().map(e=>convertElementToCssSelector(e));if(!e.length)throw getElementError(this._pwSelector,this._container||document.body);let g=!1,_=e.map(e=>e.startsWith(`>>>`)?(g=!0,e.slice(3)):e);return(g?`>>>`:``)+_.join(`, `)}click(e){return super.click(processClickOptions(e))}dblClick(e){return super.dblClick(processClickOptions(e))}tripleClick(e){return super.tripleClick(processClickOptions(e))}selectOptions(e,g){let _=getWebdriverioSelectOptions(this.element(),e);return this.triggerCommand(`__vitest_selectOptions`,this.selector,_,g)}hover(e){return super.hover(processHoverOptions(e))}dropTo(e,g){return super.dropTo(e,processDragAndDropOptions(g))}locator(e){return new WebdriverIOLocator(`${this._pwSelector} >> ${e}`,this._container)}elementLocator(e){return new WebdriverIOLocator(selectorEngine.generateSelectorSimple(e),e)}}function getWebdriverioSelectOptions(e,g){let _=[...e.querySelectorAll(`option`)],v=Array.isArray(g)?g:[g];if(!v.length)return[];if(v.length>1)throw Error(`Provider "webdriverio" doesn't support selecting multiple values at once`);let y=v[0];if(typeof y!=`string`){let e=`element`in y?y.element():y,g=_.indexOf(e);if(g===-1)throw Error(`The element ${selectorEngine.previewNode(e)} was not found in the "select" options.`);return[{index:g}]}let b=_.findIndex(e=>e.value===y);if(b!==-1)return[{index:b}];let x=_.findIndex(e=>e.textContent?.trim()===y||e.ariaLabel===y);if(x===-1)throw Error(`The option "${y}" was not found in the "select" options.`);return[{index:x}]}function processClickOptions(e){if(!e||!getBrowserState().config.browser.ui)return e;let g=e;if(g.x!=null||g.y!=null){let e={};g.x!=null&&(g.x=scaleCoordinate(g.x,e)),g.y!=null&&(g.y=scaleCoordinate(g.y,e))}return e}function processHoverOptions(e){if(!e||!getBrowserState().config.browser.ui)return e;let g=e,_={};return g.xOffset!=null&&(g.xOffset=scaleCoordinate(g.xOffset,_)),g.yOffset!=null&&(g.yOffset=scaleCoordinate(g.yOffset,_)),e}function processDragAndDropOptions(e){if(!e||!getBrowserState().config.browser.ui)return e;let g={},_=e;return _.sourceX!=null&&(_.sourceX=scaleCoordinate(_.sourceX,g)),_.sourceY!=null&&(_.sourceY=scaleCoordinate(_.sourceY,g)),_.targetX!=null&&(_.targetX=scaleCoordinate(_.targetX,g)),_.targetY!=null&&(_.targetY=scaleCoordinate(_.targetY,g)),e}function scaleCoordinate(e,g){return Math.round(e*getCachedScale(g))}function getCachedScale(e){return e.scale??=getIframeScale()}

package/dist/providers.js

@@ -1,4 +1,4 @@
-import { W as WebdriverBrowserProvider, P as PlaywrightBrowserProvider } from './webdriver-KA1WiV0q.js';
+import { W as WebdriverBrowserProvider, P as PlaywrightBrowserProvider } from './webdriver-AHRa6U3j.js';
 import '@vitest/mocker/node';
 import 'tinyrainbow';
 import 'vitest/node';

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

@@ -0,0 +1,13 @@
+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;
+}];
+export type ScreenshotMatcherOutput = Promise<{
+	pass: false;
+	reference: string | null;
+	actual: string | null;
+	diff: string | null;
+	message: string;
+} | {
+	pass: true;
+}>;

package/dist/state.js

@@ -28,14 +28,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/{webdriver-KA1WiV0q.js → webdriver-AHRa6U3j.js}

@@ -376,9 +376,14 @@ class WebdriverBrowserProvider {
 	getSupportedBrowsers() {
 		return webdriverBrowsers;
 	}
-	async initialize(ctx, { browser, options }) {
+	async initialize(project, { browser, 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 = ctx;
+		this.project = project;
 		this.browserName = browser;
 		this.options = options;
 	}
@@ -386,13 +391,13 @@ class WebdriverBrowserProvider {
 		return this.iframeSwitched;
 	}
 	async switchToTestFrame() {
-		const page = this.browser;
+		const browser = this.browser;
 		// support wdio@9
-		if (page.switchFrame) {
-			await page.switchFrame(page.$("iframe[data-vitest]"));
+		if (browser.switchFrame) {
+			await browser.switchFrame(browser.$("iframe[data-vitest]"));
 		} else {
-			const iframe = await page.findElement("css selector", "iframe[data-vitest]");
-			await page.switchToFrame(iframe);
+			const iframe = await browser.findElement("css selector", "iframe[data-vitest]");
+			await browser.switchToFrame(iframe);
 		}
 		this.iframeSwitched = true;
 	}
@@ -497,10 +502,15 @@ class WebdriverBrowserProvider {
 	async close() {
 		debug?.("[%s] closing provider", this.browserName);
 		this.closing = true;
-		await Promise.all([this.browser?.sessionId ? this.browser?.deleteSession?.() : null]);
-		// TODO: right now process can only exit with timeout, if we use browser
-		// needs investigating
-		process.exit();
+		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;
 	}
 }
 

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> {
   /**
@@ -626,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>
@@ -673,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.3",
+  "version": "4.0.0-beta.5",
   "description": "Browser running for Vitest",
   "license": "MIT",
   "funding": "https://opencollective.com/vitest",
@@ -66,7 +66,7 @@
   "peerDependencies": {
     "playwright": "*",
     "webdriverio": "^7.0.0 || ^8.0.0 || ^9.0.0",
-    "vitest": "4.0.0-beta.3"
+    "vitest": "4.0.0-beta.5"
   },
   "peerDependenciesMeta": {
     "playwright": {
@@ -83,17 +83,20 @@
     "@testing-library/dom": "^10.4.0",
     "@testing-library/user-event": "^14.6.1",
     "magic-string": "^0.30.17",
+    "pixelmatch": "7.1.0",
+    "pngjs": "^7.0.0",
     "sirv": "^3.0.1",
     "tinyrainbow": "^2.0.0",
     "ws": "^8.18.3",
-    "@vitest/mocker": "4.0.0-beta.3",
-    "@vitest/utils": "4.0.0-beta.3"
+    "@vitest/mocker": "4.0.0-beta.5",
+    "@vitest/utils": "4.0.0-beta.5"
   },
   "devDependencies": {
+    "@types/pngjs": "^6.0.5",
     "@types/ws": "^8.18.1",
     "@wdio/protocols": "^9.16.2",
     "@wdio/types": "^9.16.2",
-    "birpc": "2.4.0",
+    "birpc": "^2.5.0",
     "flatted": "^3.3.3",
     "ivya": "^1.7.0",
     "mime": "^4.0.7",
@@ -102,11 +105,11 @@
     "playwright": "^1.54.1",
     "playwright-core": "^1.54.1",
     "safaridriver": "^1.0.0",
-    "webdriverio": "^9.17.0",
-    "@vitest/ui": "4.0.0-beta.3",
-    "@vitest/runner": "4.0.0-beta.3",
-    "vitest": "4.0.0-beta.3",
-    "@vitest/ws-client": "4.0.0-beta.3"
+    "webdriverio": "^9.18.1",
+    "@vitest/runner": "4.0.0-beta.5",
+    "@vitest/ui": "4.0.0-beta.5",
+    "@vitest/ws-client": "4.0.0-beta.5",
+    "vitest": "4.0.0-beta.5"
   },
   "scripts": {
     "typecheck": "tsc -p ./src/client/tsconfig.json --noEmit",

package/providers/playwright.d.ts

@@ -11,6 +11,10 @@ import type {
 import { Protocol } from 'playwright-core/types/protocol'
 import '../matchers.js'
 import type {} from "vitest/node"
+import type {
+  ScreenshotComparatorRegistry,
+  ScreenshotMatcherOptions,
+} from "@vitest/browser/context"
 
 declare module 'vitest/node' {
   export interface BrowserProviderOptions {
@@ -37,6 +41,15 @@ declare module 'vitest/node' {
     iframe: FrameLocator
     context: BrowserContext
   }
+
+  export interface ToMatchScreenshotOptions
+    extends Omit<
+      ScreenshotMatcherOptions,
+      "comparatorName" | "comparatorOptions"
+    > {}
+
+  export interface ToMatchScreenshotComparators
+    extends ScreenshotComparatorRegistry {}
 }
 
 type PWHoverOptions = NonNullable<Parameters<Page['hover']>[1]>

package/providers/webdriverio.d.ts

@@ -1,6 +1,10 @@
 import type { remote, ClickOptions, DragAndDropOptions } from 'webdriverio'
 import '../matchers.js'
 import type {} from "vitest/node"
+import type {
+  ScreenshotComparatorRegistry,
+  ScreenshotMatcherOptions,
+} from "@vitest/browser/context";
 
 declare module 'vitest/node' {
   export interface BrowserProviderOptions extends Partial<
@@ -19,4 +23,13 @@ declare module 'vitest/node' {
   export interface BrowserCommandContext {
     browser: WebdriverIO.Browser
   }
+
+  export interface ToMatchScreenshotOptions
+    extends Omit<
+      ScreenshotMatcherOptions,
+      "comparatorName" | "comparatorOptions"
+    > {}
+
+  export interface ToMatchScreenshotComparators
+    extends ScreenshotComparatorRegistry {}
 }

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'