Vitest

English

简体中文

English

简体中文

Appearance

Browser Config Reference ​

You can change the browser configuration by updating the test.browser field in your config file. An example of a simple config file:

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

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [
        {
          browser: 'chromium',
          setupFile: './chromium-setup.js',
        },
      ],
    },
  },
})

Please, refer to the "Config Reference" article for different config examples.

WARNING

All listed options on this page are located within a test property inside the configuration:

vitest.config.js
ts
export default defineConfig({
  test: {
    browser: {},
  },
})

browser.enabled ​

  • Type: boolean
  • Default: false
  • CLI: --browser, --browser.enabled=false

Run all tests inside a browser by default. Note that --browser only works if you have at least one browser.instances item.

browser.instances ​

  • Type: BrowserConfig
  • Default: [{ browser: name }]

Defines multiple browser setups. Every config has to have at least a browser field. The config supports your providers configurations:

TIP

To have a better type safety when using built-in providers, you should reference one of these types (for provider that you are using) in your config file:

ts
/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

In addition to that, you can also specify most of the project options (not marked with a * icon) and some of the browser options like browser.testerHtmlPath.

WARNING

Every browser config inherits options from the root config:

vitest.config.ts
ts
export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // will have both setup files: "root" and "browser"
          setupFile: ['./browser-setup-file.js'],
          // implicitly has "testerHtmlPath" from the root config
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

During development, Vitest supports only one non-headless configuration. You can limit the headed project yourself by specifying headless: false in the config, or by providing the --browser.headless=false flag, or by filtering projects with --project=chromium flag.

For more examples, refer to the "Multiple Setups" guide.

List of available browser options:

By default, Vitest creates an array with a single element which uses the browser.name field as a browser. Note that this behaviour will be removed with Vitest 4.

Under the hood, Vitest transforms these instances into separate test projects sharing a single Vite server for better caching performance.

browser.name deprecated ​

  • Type: string
  • CLI: --browser=safari

DEPRECATED

This API is deprecated an will be removed in Vitest 4. Please, use browser.instances option instead.

Run all tests in a specific browser. Possible options in different providers:

  • webdriverio: firefox, chrome, edge, safari
  • playwright: firefox, webkit, chromium
  • custom: any string that will be passed to the provider

browser.headless ​

  • Type: boolean
  • Default: process.env.CI
  • CLI: --browser.headless, --browser.headless=false

Run the browser in a headless mode. If you are running Vitest in CI, it will be enabled by default.

browser.isolate ​

  • Type: boolean
  • Default: true
  • CLI: --browser.isolate, --browser.isolate=false

Run every test in a separate iframe.

browser.testerHtmlPath ​

  • Type: string

A path to the HTML entry point. Can be relative to the root of the project. This file will be processed with transformIndexHtml hook.

browser.api ​

  • Type: number | { port?, strictPort?, host? }
  • Default: 63315
  • CLI: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

Configure options for Vite server that serves code in the browser. Does not affect test.api option. By default, Vitest assigns port 63315 to avoid conflicts with the development server, allowing you to run both in parallel.

browser.provider ​

  • Type: 'webdriverio' | 'playwright' | 'preview' | string
  • Default: 'preview'
  • CLI: --browser.provider=playwright

Path to a provider that will be used when running browser tests. Vitest provides three providers which are preview (default), webdriverio and playwright. Custom providers should be exported using default export and have this shape:

ts
export interface BrowserProvider {
  name: string
  supportsParallelism: boolean
  getSupportedBrowsers: () => readonly string[]
  beforeCommand?: (command: string, args: unknown[]) => Awaitable<void>
  afterCommand?: (command: string, args: unknown[]) => Awaitable<void>
  getCommandsContext: (sessionId: string) => Record<string, unknown>
  openPage: (sessionId: string, url: string, beforeNavigate?: () => Promise<void>) => Promise<void>
  getCDPSession?: (sessionId: string) => Promise<CDPSession>
  close: () => Awaitable<void>
  initialize(
    ctx: TestProject,
    options: BrowserProviderInitializationOptions
  ): Awaitable<void>
}

ADVANCED API

The custom provider API is highly experimental and can change between patches. If you just need to run tests in a browser, use the browser.instances option instead.

browser.providerOptions deprecated ​

  • Type: BrowserProviderOptions

DEPRECATED

This API is deprecated an will be removed in Vitest 4. Please, use browser.instances option instead.

Options that will be passed down to provider when calling provider.initialize.

ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
      },
    },
  },
})

TIP

To have a better type safety when using built-in providers, you should reference one of these types (for provider that you are using) in your config file:

ts
/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

browser.ui ​

  • Type: boolean
  • Default: !isCI
  • CLI: --browser.ui=false

Should Vitest UI be injected into the page. By default, injects UI iframe during development.

browser.viewport ​

  • Type: { width, height }
  • Default: 414x896

Default iframe's viewport.

browser.locators ​

Options for built-in browser locators.

browser.locators.testIdAttribute ​

  • Type: string
  • Default: data-testid

Attribute used to find elements with getByTestId locator.

browser.screenshotDirectory ​

  • Type: string
  • Default: __screenshots__ in the test file directory

Path to the screenshots directory relative to the root.

browser.screenshotFailures ​

  • Type: boolean
  • Default: !browser.ui

Should Vitest take screenshots if the test fails.

browser.orchestratorScripts ​

  • Type: BrowserScript[]
  • Default: []

Custom scripts that should be injected into the orchestrator HTML before test iframes are initiated. This HTML document only sets up iframes and doesn't actually import your code.

The script src and content will be processed by Vite plugins. Script should be provided in the following shape:

ts
export interface BrowserScript {
  /**
   * If "content" is provided and type is "module", this will be its identifier.
   *
   * If you are using TypeScript, you can add `.ts` extension here for example.
   * @default `injected-${index}.js`
   */
  id?: string
  /**
   * JavaScript content to be injected. This string is processed by Vite plugins if type is "module".
   *
   * You can use `id` to give Vite a hint about the file extension.
   */
  content?: string
  /**
   * Path to the script. This value is resolved by Vite so it can be a node module or a file path.
   */
  src?: string
  /**
   * If the script should be loaded asynchronously.
   */
  async?: boolean
  /**
   * Script type.
   * @default 'module'
   */
  type?: string
}

browser.testerScripts ​

  • Type: BrowserScript[]
  • Default: []

DEPRECATED

This API is deprecated an will be removed in Vitest 4. Please, use browser.testerHtmlPath field instead.

Custom scripts that should be injected into the tester HTML before the tests environment is initiated. This is useful to inject polyfills required for Vitest browser implementation. It is recommended to use setupFiles in almost all cases instead of this.

The script src and content will be processed by Vite plugins.

browser.commands ​

  • Type: Record<string, BrowserCommand>
  • Default: { readFile, writeFile, ... }

Custom commands that can be imported during browser tests from @vitest/browser/commands.

browser.connectTimeout ​

  • Type: number
  • Default: 60_000

The timeout in milliseconds. If connection to the browser takes longer, the test suite will fail.

INFO

This is the time it should take for the browser to establish the WebSocket connection with the Vitest server. In normal circumstances, this timeout should never be reached.

browser.expect ​

  • Type: ExpectOptions

browser.expect.toMatchScreenshot ​

Default options for the toMatchScreenshot assertion. These options will be applied to all screenshot assertions.

TIP

Setting global defaults for screenshot assertions helps maintain consistency across your test suite and reduces repetition in individual tests. You can still override these defaults at the assertion level when needed for specific test cases.

ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      expect: {
        toMatchScreenshot: {
          comparatorName: 'pixelmatch',
          comparatorOptions: {
            threshold: 0.2,
            allowedMismatchedPixels: 100,
          },
          resolveScreenshotPath: ({ arg, browserName, ext, testFileName }) =>
            `custom-screenshots/${testFileName}/${arg}-${browserName}${ext}`,
        },
      },
    },
  },
})

All options available in the toMatchScreenshot assertion can be configured here. Additionally, two path resolution functions are available: resolveScreenshotPath and resolveDiffPath.

browser.expect.toMatchScreenshot.resolveScreenshotPath ​

  • Type: (data: PathResolveData) => string
  • Default output: `${root}/${testFileDirectory}/${screenshotDirectory}/${testFileName}/${arg}-${browserName}-${platform}${ext}`

A function to customize where reference screenshots are stored. The function receives an object with the following properties:

  • arg: string

    Path without extension, sanitized and relative to the test file.

    This comes from the arguments passed to toMatchScreenshot; if called without arguments this will be the auto-generated name.

    ts
    test('calls `onClick`', () => {
  expect(locator).toMatchScreenshot()
  // arg = "calls-onclick-1"
})

expect(locator).toMatchScreenshot('foo/bar/baz.png')
// arg = "foo/bar/baz"

expect(locator).toMatchScreenshot('../foo/bar/baz.png')
// arg = "foo/bar/baz"

  • ext: string

    Screenshot extension, with leading dot.

    This can be set through the arguments passed to toMatchScreenshot, but the value will fall back to '.png' if an unsupported extension is used.

  • browserName: string

    The instance's browser name.

  • platform: NodeJS.Platform

    The value of process.platform.

  • screenshotDirectory: string

    The value provided to browser.screenshotDirectory, if none is provided, its default value.

  • root: string

    Absolute path to the project's root.

  • testFileDirectory: string

    Path to the test file, relative to the project's root.

  • testFileName: string

    The test's filename.

  • testName: string

    The test's name, including parent describe, sanitized.

  • attachmentsDir: string

    The value provided to attachmentsDir, if none is provided, its default value.

For example, to group screenshots by browser:

ts
resolveScreenshotPath: ({ arg, browserName, ext, root, testFileName }) =>
  `${root}/screenshots/${browserName}/${testFileName}/${arg}${ext}`

browser.expect.toMatchScreenshot.resolveDiffPath ​

  • Type: (data: PathResolveData) => string
  • Default output: `${root}/${attachmentsDir}/${testFileDirectory}/${testFileName}/${arg}-${browserName}-${platform}${ext}`

A function to customize where diff images are stored when screenshot comparisons fail. Receives the same data object as resolveScreenshotPath.

For example, to store diffs in a subdirectory of attachments:

ts
resolveDiffPath: ({ arg, attachmentsDir, browserName, ext, root, testFileName }) =>
  `${root}/${attachmentsDir}/screenshot-diffs/${testFileName}/${arg}-${browserName}${ext}`

TIP

To have a better type safety when using built-in providers, you should reference one of these types (for provider that you are using) in your config file:

ts
/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

Released under the MIT License.

Copyright © 2021-PRESENT Anthony Fu, Matías Capeletto and Vitest contributors