mirror of
https://github.com/vitest-dev/vitest.git
synced 2025-12-08 18:26:03 +00:00
101 lines
3.0 KiB
Markdown
101 lines
3.0 KiB
Markdown
---
|
|
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`](https://github.com/jsdom/jsdom)
|
|
or [`happy-dom`](https://github.com/capricorn86/happy-dom) instead.
|
|
If you are building edge functions, you can use [`edge-runtime`](https://edge-runtime.vercel.app/packages/vm) environment
|
|
|
|
::: tip
|
|
You can also use [Browser Mode](/guide/browser/) to run integration or unit tests in the browser without mocking the environment.
|
|
:::
|
|
|
|
To define custom options for your environment, use [`environmentOptions`](/config/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:
|
|
|
|
```js
|
|
/**
|
|
* @vitest-environment jsdom
|
|
*/
|
|
|
|
test('use jsdom in this test file', () => {
|
|
const element = document.createElement('div')
|
|
expect(element).not.toBeNull()
|
|
})
|
|
```
|
|
|
|
Comment style:
|
|
|
|
```js
|
|
// @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`:
|
|
|
|
```js
|
|
/**
|
|
* @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`:
|
|
|
|
```ts [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](https://vite.dev/guide/api-environment#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](/guide/environment).
|
|
|
|
::: tip
|
|
jsdom environment exposes `jsdom` global variable equal to the current [JSDOM](https://github.com/jsdom/jsdom) instance. If you want TypeScript to recognize it, you can add `vitest/jsdom` to your `tsconfig.json` when you use this environment:
|
|
|
|
```json [tsconfig.json]
|
|
{
|
|
"compilerOptions": {
|
|
"types": ["vitest/jsdom"]
|
|
}
|
|
}
|
|
```
|
|
:::
|