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

[cqh963852]

This problem was solved after putting vitest.config.ts into the include of tsconfig.json

[cqh963852]

I found that current page type of playwright's provider is not fully Page.

So that I can't access the screenshot function.

I have create a PR, PTAL

[cqh963852]

@sheremet-va Thanks for review. I saw the comment in the PR.

Any plans to expose the provider.page ? Or are there plans for support for screenshots?

Canvas related tests usually cannot be performed in jsdom and can only be postponed to the e2e testing stage.
If vitest2.0 browser mode can support taking relevant screenshots in unit tests, it can solve many problems.

[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.

[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