environment

Type: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string
Default: 'node'
CLI: --environment=<env>

The environment that will be used for testing. The default environment in Vitest is a Node.js environment. If you are building a web application, you can use browser-like environment through either jsdom or happy-dom instead. If you are building edge functions, you can use edge-runtime environment

TIP

You can also use Browser Mode to run integration or unit tests in the browser without mocking the environment.

To define custom options for your environment, use environmentOptions.

By adding a @vitest-environment docblock or comment at the top of the file, you can specify another environment to be used for all tests in that file:

Docblock style:

/**
 * @vitest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div')
  expect(element).not.toBeNull()
})

Comment style:

// @vitest-environment happy-dom

test('use happy-dom in this test file', () => {
  const element = document.createElement('div')
  expect(element).not.toBeNull()
})

For compatibility with Jest, there is also a @jest-environment:

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div')
  expect(element).not.toBeNull()
})

You can also define a custom environment. When non-builtin environment is used, Vitest will try to load the file if it's relative or absolute, or a package vitest-environment-${name}, if the name is a bare specifier.

The custom environment file should export an object with the shape of Environment:

environment.js

import type { Environment } from 'vitest'

export default <Environment>{
  name: 'custom',
  viteEnvironment: 'ssr',
  setup() {
    // custom setup
    return {
      teardown() {
        // called after all tests with this env have been run
      }
    }
  }
}

TIP

The viteEnvironment field corresponde to the environment defined by the Vite Environment API. By default, Vite exposes client (for the browser) and ssr (for the server) environments.

Vitest also exposes builtinEnvironments through vitest/environments entry, in case you just want to extend it. You can read more about extending environments in our guide.

TIP

jsdom environment exposes jsdom global variable equal to the current JSDOM instance. If you want TypeScript to recognize it, you can add vitest/jsdom to your tsconfig.json when you use this environment:

tsconfig.json

json

{
  "compilerOptions": {
    "types": ["vitest/jsdom"]
  }
}

environment ​

environment