vitest/docs/config/environment.md

title
environment | Config

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:

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:

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

:::