environment

13 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Default test environments in Vitest

Vitest provides four default environments: node (the default environment), jsdom (emulates browser environment using the jsdom package), happy-dom (emulates browser environment and is faster than jsdom but lacks some API, uses the happy-dom package), and edge-runtime (emulates Vercel's edge-runtime, uses the @edge-runtime/vm package).

CSS and assets import rules in jsdom and happy-dom environments

When using jsdom or happy-dom environments, Vitest follows the same rules as Vite when importing CSS and assets. If an external dependency import fails with an 'unknown extension .css' error, all packages in the import chain must be added to server.deps.inline. For example, if the error occurs in package-3 in the chain 'source code -> package-1 -> package-2 -> package-3', all three packages must be added to server.deps.inline. The require of CSS and assets inside external dependencies are resolved automatically.

Environment control comments for specific test files

To specify an environment for a specific test file instead of applying it to all files, use a control comment that starts with @vitest-environment followed by the environment name. For example, add // @vitest-environment jsdom at the top of a test file to use the jsdom environment for that file only.

Custom environment package naming convention

Custom Vitest environments can be created by exporting an Environment object from a package named vitest-environment-${name} or by specifying a path to a valid JS/TS file. The custom environment must export an object with the shape of the Environment type.

Environment interface required properties

A custom Vitest environment must export an object with properties: name (string), viteEnvironment (required, must be 'ssr', 'client', or a custom Vite environment name - determines which environment processes the file, defaults to the Vitest environment name), setupVM (optional async function only needed if supporting vmForks or vmThreads pools), and setup (optional function). Both setupVM and setup should return objects with optional teardown functions.

Example custom Vitest environment

import type { Environment } from 'vitest/runtime' export default <Environment>{ name: 'custom', viteEnvironment: 'ssr', async setupVM() { const vm = await import('node:vm') const context = vm.createContext() return { getVmContext() { return context }, teardown() { // called after all tests with this env have been run } } }, setup() { // custom setup return { teardown() { // called after all tests with this env have been run } } } }

Accessing built-in Vitest environments programmatically

The builtinEnvironments object can be imported from 'vitest/runtime' to access default Vitest environments programmatically. It contains references to jsdom, happy-dom, node, and edge-runtime environments.

populateGlobal utility function signature and purpose

The populateGlobal utility function from 'vitest/runtime' moves properties from an object into the global namespace. It accepts parameters: global (the global object), original (the object with properties to copy), and options (with optional bindFunctions boolean to determine if non-class functions should be bound to the global namespace). It returns PopulateResult with keys (a Set of all copied keys) and originals (a Map of property descriptors for potentially overridden keys to restore with Object.defineProperty in teardown).

Browser mode is not an environment in Vitest

Browser mode is not considered an environment in Vitest. To run tests using Browser Mode, create a test project as part of the browser configuration rather than using the environment option.

Environments only exist when running tests in Node.js

The environment option in Vitest only applies when running tests in Node.js. Environments do not exist outside of Node.js execution context.

Environment variables with VITE_ prefix

Vitest exclusively autoloads environment variables prefixed with VITE_ from .env files to maintain compatibility with frontend-related tests, following Vite's convention. Use loadEnv from 'vite' to load all environment variables from .env files.

Loading all environment variables example

import { loadEnv } from 'vite' import { defineConfig } from 'vitest/config' export default defineConfig(({ mode }) => ({ test: { env: loadEnv(mode, process.cwd(), ''), }, }))

Vitest requires Vite >=v6.4.0 and Node >=v22.12.0

Vitest requires Vite version 6.4.0 or greater and Node version 22.12.0 or greater.

Give your agent this brain