Vitest Browser Mode

[sheremet-va]

It's been some time since we gave any update on the Browser Mode, and Vitest 2.0 seems like a good time to explain how we feel about it. And we have a lot of plans!

The initial purpose of Vitest was to allow running tests without a complex Jest setup but with the battle-tested Jest API everyone is already familiar with. This also meant faking the browser environment (with jsdom or happy-dom). With time, as the JavaScript ecosystem evolved, we started to hit roadblocks with this approach (like this issue, for example, #4043). Switching to Jest's VM approach allowed us to bypass some of them, but introduced many more along the way (#3203).

Using fake browser environments means that developers introduce an environment that doesn't exist anywhere except tests which can lead to testing something that cannot happen when an actual person uses your Web Application. Fake environments also have their own limitations like not providing common Web APIs (fetch, canvas, PerformanceObserver, HTMLDialogElement, Pointer Lock, and so on) - this means that to test a single component you have to resort to E2E testing which throws a lot of APIs at you and can require a complex setup. There are already several solutions to that by different testing frameworks:

• Playwright Components
• Cypress Component Testing
• Webdriverio Component Testing

Browser Mode is our take on component testing.

Future Plans

Browser mode aims to replace jsdom and happy-dom environment with an easy migration path. Right now you are able to opt-in to using browser mode by creating a separate workspace project:

// vitest.workspace.ts
import { defineWorkspace } from 'vitest/config'

export default defineWorkspace([
  './vitest.config.ts', // the default config for Node.js tests
  {
    test: {
      include: ['**/*.browser.test.ts'],
      browser: {
        enabled: true,
        name: 'chrome',
      },
    },
  },
])

When you switch to the browser mode, all your tests should work as before unless you use Node.js APIs directly. This means that tests will be isolated by file, not by the test function (similar to Web Test Runner or Cypress). Most of the Vitest APIs including vi.mock, vi.dynamicImportSettled should just work. Some of them we are unable to implement due to ESM limitations like resetModules - these will throw an error when running in the browser.

The Vitest team is not interested in exploring the E2E testing (Vitest already provides integration for webdriverio and playwright that you can use alongside Vitest Browser Mode). In E2E tests you are typically testing a site that is deployed and doesn't need any changes. In Vitest Browser Mode you provide what is mounted on the DOM and mock the modules you want. Changing different states of the DOM becomes easier. This also means that we will not provide higher-level APIs like network interception. (On that note, our current recommendation is to use MSW for both browser and Node.js tests - this will be reflected in the browser guide in our documentation).

It's hard to start using the browser mode in CI at the moment because you need to know what provider to choose and how to configure Vitest. To address this, we will improve the documentation and also provide a command to install all necessary packages and update the configuration to use the browser mode.

Additional API

Vitest will provide the context object via @vitest/browser/context import that exposes utilities (like file reading/writing) and allows you to communicate with the Node.js server via the Commands API. The context will expose the page object with interactive APIs that should replace the userEvent from @testing-library/user-event. The current idea is to replace the @testing-library/user-event import with a module that exposes the way to interact with the browser through Chrome DevTools or Webdriver protocols instead of mocking events that might not follow the actual browser specification:

// if imported from `@testing-library/user-event'
// we intercept it to use CDP under the hood instead
import { userEvent } from '@vitest/browser/context'
import { findByText } from '@testing-library/dom'

it('clicks correctly', async () => {
  await userEvent.click(await findByText('Click'))
})

Vitest will also provide a way to hook into CDP directly to make developing libraries easier.

By default, Vitest provides playwright and webdriverio APIs wrapped in a common API out of the box (depending on which one you use) unless you use preview provider (previously named none).

import { page, commands, server } from '@vitest/browser/context'

page.config // ResolvedConfig
page.browser // chrome
server.platform // node
await commands.readFile('./relative-to-test-file.js')

The preview provider (called none in Vitest 1.6) allows running tests in any browser of your choice by simply opening a link. It exposes a subset of APIs available in playwright and webdriverio, and uses the actual userEvent library to simulate events without relying on DevTool or Webdriver protocols. This provider is useful for a quick inspection of your code and tests and it doesn't require installing additional libraries and browsers, it is also the only provider that works in Stackblitz. However, be aware that if you don't use it to run tests in Stackblitz, your browser extensions/cookies/localStorage will affect your tests and possibly the dev environment making it hard to debug potential issues with tests. We recommend installing playwright or webdriverio to run your tests locally.

Retryability is important when testing in the browser. Vitest 2.0 provides new expect.poll API to retry your assertions manually:

import { screen } from '@testing-library/dom'
import '@testing-library/jest-dom'

const input = await screen.findByRole('input', { name: 'Username' })
await expect.poll(() => input).toHaveFocus()

Currently, there are no plans to implement our own built-in retryability+query API, but this can change based on community feedback.

Viewport can be configured globally with the browser.viewport option, but you can also change it during your test by clicking on one of the presets in the UI or by using page.viewport command:

import { page } from '@vitest/browser/context'
import { it } from 'vitest'

it('viewport changes', async () => {
  await page.viewport(300, 500)
})

Providers

Vitest requires playwright or webdriverio provider to run tests without simulating any events. Providers are used to install browsers, connect to CDP, and expose the testing browser environment.

Vitest doesn't use test runners from these providers and doesn't expose any of their APIs directly. Built-in userEvent uses page and $ APIs under the hood depending on the provider. You can write Custom Commands to get access to providers APIs on the server. Beware that you might need to use page.frameLocator or browser.switchToFrame APIs to get access to HTML elements. This is considered an advanced use case, and we do not encourage overusing it.

Test Isolation

Vitest opens a single page during the test run. Tests are isolated using iframes inside of that page. During development, you can see the iframe inside the UI (configurable by test.browser.ui):

Running tresjs example in Vitest Browser Mode

The --no-isolate flag also allows running all browser tests inside the same iframe in cases where you do not depend on the global state and do a proper cleanup. This can make your test run several times faster. Module mocking works even when isolation is disabled.

Debugging

Debugging using the IDE is not supported at the moment, but it's on the roadmap. In the meantime, you can use the debugger statement in your tests to automatically stop execution and open devtools:

import { it } from 'vitest'

it('stops execution', () => {
  debugger;
})

Unfortunately, you might need to rerun the test several times to hit the debugger statement if they are too fast. Better debugging experience is one of the highest priorities for the next feature release.

Node.js Polyfills

Vitest doesn't polyfill any Node.js APIs because it would create a situation where your code will work in tests, but won't work in dev or production. If you rely on some Node.js APIs in your setup files, you can add vite-plugin-node-polyfills to your plugins list if process.env.VITEST is set and manually add them to include option:

import { nodePolyfills } from 'vite-plugin-node-polyfills'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [
    process.env.VITEST ? nodePolyfills({
      include: ['path']
    }) : null,
  ],
})

Current State

Vitest 1.6 implements browser tests using iframes. During the test run, you will see the Vitest UI, changing the file will reload the browser page.

Vitest 2.0 will ship with Commands API and module mocking supported. You can already test changes using the beta branch.

This release also implements better watch mode support - you can change files directly inside the UI and the tests will be reloaded without a page refresh like it was in Vitest 1.6. Changing the file outside the UI will also not reload the page.

The interactivity API is planned to be released after Vitest 2.0.

Special thanks to wonderful @Aslemammad and @userquin who worked on the initial implementation 🎉

[bahmutov]

Interesting, reading this with excitement

[NoriSte]

Amazing, can't wait for all the next evolutions!!

[shreyT19]

Incredible!

[ishpreet95]

shut up and take my money

[favna]

Maybe mention https://testcafe.io in your list of E2E frameworks?

[sheremet-va]

We don't have the list of E2E frameworks, only the list of component testing solutions. Does testcase support component testing?

[favna]

Ah no my bad, I misread then. Testcafe is purely E2E.

[JessicaSachs]

Pretty stoked to see this work. I really appreciate being consulted about the future Vitest Browser Testing arch (compared to Cypress Component Testing's arch). I'm confident that this architecture will meet my needs for Vite-specific apps and I'll undoubtedly phase out teaching Cypress Component Testing once this lands.

[cqh963852]

Greeting, I am trying to use the 2.0.0-beta.9 version.

rendering a canvas element by "@testing-library/react" 's render.

but the toMatchInlineSnapshot did not work as expected.

Is there anything I need to pay attention to here?

import { Stage } from "@idealjs/pixi-react";
import { render } from "@testing-library/react";
import { StrictMode, Suspense } from "react";
import { describe, expect, it } from "vitest";

import ECSEntity from "../../../../../ecs-react/src/ECSEntity";
import ECSWorld from "../../../../../ecs-react/src/ECSWorld";
import RenderCellComponent from "../../components/RenderCellComponent";
import RenderSystem from ".";

describe("RenderSystem", () => {
  it("RenderCellComponent", async () => {
    const { container } = render(
      <StrictMode>
        <Suspense>
          <Stage>
            <ECSWorld>
              <RenderSystem />
              <ECSEntity>
                <RenderCellComponent ...
                />
              </ECSEntity>
            </ECSWorld>
          </Stage>
        </Suspense>
      </StrictMode>,
    );
    expect(container).toMatchInlineSnapshot();
    console.log(container);
  });
});

[sheremet-va]

toMatchInlineSnapshot is bugged in beta at the moment. You can create an issue with a small reproduction.

[abenhamdine]

Will it be possible to set a custom render function to mount component from another framework than React ?
in other words, is Vitest component testing framework-agnostic ?
We have a app running on a legacy js framework and we would want to do component testing with Vitest.

[sheremet-va]

Vitest doesn't provide any method to mount components. You are encouraged to use @testing-library/* package depending on your framework or render it yourself however you want.

[abenhamdine]

thanks for your answer, indeed @testing-library/dom will be enough for our case.

[cqh963852]

I encountered some problems when customizing commands.

How should I set the provider type so that provider.page can be used without type error?

---

The above question is not important, so I modified it

[sheremet-va]

Yes, page and tester (iframe) will be exposed on the context directly

[sheremet-va]

The beta 10 now implements parallelization (only for playwright for now).

page/tester/body are exposed in commands context for the playwright provider: https://main.vitest.dev/guide/browser.html#custom-playwright-commands

This release also adds page.screenshot command directly to the context object:

import { page } from '@vitest/browser/context'

it('some test', async () => {
  const screenshotPath = await page.screenshot()
  await page.screenshot({ element: document.querySelector('.element') })
})

Playwright provider doesn't have the page on its public provider API anymore because tests are running in parallel and there are several pages.

[tylerbmyers]

First off, thanks for working on all these improvements to Browser Testing - it is extremely exciting to get all of the incredible features of Vitest with real browser testing! Would the only way to use Playwright's locators be in a custom command? The reason I ask is that I work on an application that uses mostly web components from a design system and testing them has always been a pain except in Playwright. Playwright's locators work by default with the Shadow DOM and being able to use these rather than testing-library which does not support the shadow dom and does not seem to have any plans to support would be another massive step forward.

[sheremet-va]

For now, yes. I have some ideas to introduce a way to have Playwright locators built-in, but this is probably for Vitest 2.1 or later.

[oscarmarina]

Hi @sheremet-va, as @tylerbmyers mentioned, thanks for your dedication to improving Browser Testing. It's exciting to see all the advancements being made in this area.

I've been actively exploring Vitest in combination with Lit -Web Components and wanted to share my experience. I've set up a repository where I compare the testing capabilities of Lit using Vitest Browser and Playwright.

• Repo: Lit Vitest Testing Comparison
• StackBlitz: Lit Vitest Testing Comparison

TS - branch

I'm truly impressed with the work being done in Vitest. As you can see in the repo, I've seamlessly integrated utilities from Web Test Runner like AXE and Vitest's new context module, all while leveraging Playwright without any issues.

[rynoV]

Thanks for the detailed update!

Do you have any idea how easy it would be to support electron as an option for browser mode?

I was hoping after seeing the electron config for webdriverio that it wouldn't be too difficult, but I'm not very familiar yet with how webdriverio and browser mode work under the hood, so I'm hoping these are not fundamentally incompatible

[sheremet-va]

I have not tested the electron yet, but I know that playwright has experimental support for it, we can try to integrate it if there is demand (I recommend opening an issue).

[rynoV]

Issue here #5883

[PindaPixel]

Any way to let the browser runner serve static files (in my case MSW's serviceWorker.js)?

[sheremet-va]

Browser Mode is just a Vite server, it serves file from /public folder (or configured publicDir) as static files.

[edwincarlflores]

@PindaPixel I cannot seem to make MSW browser worker work with browser mode. Do you have an example repo where MSW is working? Currently using MSW + React testing library

[ysgk]

In my case, I had to call worker.start() in the test file instead of in the setup file.

[edwincarlflores]

@ysgk Did you just added the mockServiceWorker.js file in the public directory for vitest server to pick it up?

[ysgk]

Yes. Are you unable to access /mockServiceWorker.js when running the vitest browser?
https://mswjs.io/docs/integrations/browser#generating-the-worker-script

[cqh963852]

Hi, I found that in source test, not work with browser mode.

Are there any restrictions ?

[cqh963852]

While using expect(await page.screenshot()).toMatchSnapshot();, vitest will create a snap file has absolute path.

I tried using addSnapshotSerializer in the setup file to handle this path. but I can't access __dirname.

Is there a better way to handle paths?

[sheremet-va]

At the moment, Vitest doesn't provide any way to have visual regression testing out of the box, the screenshot method just makes a screenshot, there is no mechanism to compare it.

[cqh963852]

The file path depends on the test name, not the content of the screenshot, so it will never fail.

Thanks for your reply, I'm curious about this question

If I want to customize SnapshotSerializer to get the ability to compare pictures.

How can I get the new picture data and the old picture data?

---

The old pictures are a little troublesome. I think I can write the pictures to the public folder. In this way, when the test program is running, I can get the corresponding pictures.

Can I get the data of the new picture through addSnapshotSerializer?

[sheremet-va]

You cannot create a custom snapshot serializer to compare images because it needs to be async, and serializers are always sync.

I don't have any advice on how to implement visual testing.

[cqh963852]

I found that playwright's screenshot and webdriver's saveScreenshot both return a Promise<Buffer>

Can vitest's page.screenshot return a Promise<Buffer> instead string path. Or is there any function that can support this ?

So that I can compare It like

expect(await page.bufferScreenshot()).toMatchSnapshot({ path:"xxx" });

[sheremet-va]

Comparing buffers also doesn't make any sense because the same element can produce different buffers depending on the machine, time of day, browser, phase of the moon, the mood of your uncle, American president, or pixel density. To compare images, you need to use external libraries like pixelmatch.

I will add a base64 property because those tools can use it, but I do not recommend comparing base64 strings.

[njzydark]

In browser mode, it seems that the iframe is destroyed every time after executing the test. Can we keep the iframe so that I can inspect the component's UI

[sheremet-va]

The last iframe is not destroyed, so you can always inspect the latest test. What can be destroyed is the DOM if you use testing-library because it automatically cleans up state - in that case I would recommend disabling auto cleanup and do the cleanup yourself in beforeEach hook instead - so the state is kept when you are done

[sheremet-va]

I am going to lock the thread now. If you have any issues, bugs, or suggestions, please open a new issue or start a discussion.

I will keep updating this thread whenever we want to release a significant change, so you can keep it in your subscriptions.

[sheremet-va]

Vitest 2.1 will have some major improvements to the Browser Mode.

We decided to have a built-in querying mechanism based on Playwright's locators - this API is available in all providers (preview and webdriverio also).

await expect.element(
  page.getByRole('heading', { name: 'Sign up' })
).toBeVisible()

await page.getByRole('textbox', { name: 'Login' }).fill('admin')

• Locators support Shadow DOM
• Locators work well with a built-in retry-ability mechanism - you can use await expect.element(locator) to query the DOM until the element is found
• Documentation was updated to reflect the new API. We no longer recommend using testing-library for every framework - instead, we opted-in to create wrappers around rendering mechanism for several popular frameworks (vitest-browser-vue, vitest-browser-svelte and vitest-browser-react). Feel free to expand this list with your own wrappers!
• The documentation in general was rewritten to reduce confusion and provide more information for core functionality

No news on the release date yet, but you can already use these APIs in the beta. Looking forward to your feedback!

[sheremet-va]

Vitest 2.1.4 introduces a new option called testerHtmlPath. It is a path to the custom HTML entry point. It can be relative to the root of the project.

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      testerHtmlPath: './my-custom-document.html',
    },
  },
})

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- custom meta tags -->
  </head>
</html>
<body>
  <!-- prepared HTML structure -->
  <!-- vitest will inject your test file here -->
</body>

Vitest will use the HTML content of this file in the tester iframe. It means that all your tests have access to it. If you want to use several HTML files, you can define a custom workspace with different project configs:

// vitest.workspace.ts
import { defineWorkspace } from 'vitest/config'

export default defineWorkspace([
  {
    test: {
      browser: {
        testerHtmlPath: './my-custom-document.html',
      },
    },
  },
  {
    test: {
      include: ['*.special.test.ts'],
      browser: {
        testerHtmlPath: './my-special-document.html',
      },
    },
  },
])

The HTML content is processed with the plugins' transformIndexHtml hooks. This means that you can also inject HTML tags via the plugin API instead of creating a separate file:

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [
    {
      transformIndexHtml() {
        return [
          {
            tag: 'script',
            children: 'windows.test = true',
          },
        ]
      }
    },
  ],
})