Source from repo
vitest

Vitest 3.x reference skill covering configuration, test/describe APIs, mocking, coverage, snapshots, and concurrency.
antfuGitHub antfuSource repo Original GitHub link Publisher page
Files
Skill
n/a
Size
67.9 KB
Entrypoint
SKILL.md
Format
git-repo
Open file
references/advanced-environments.md

Syntax-highlighted preview of this file as included in the skill package.
Rendered Source
markdown265 linesFree
references/advanced-environments.md
1---
2name: test-environments
3description: Configure environments like jsdom, happy-dom for browser APIs
4---
5 
6# Test Environments
7 
8## Available Environments
9 
10- `node` (default) - Node.js environment
11- `jsdom` - Browser-like with DOM APIs
12- `happy-dom` - Faster alternative to jsdom
13- `edge-runtime` - Vercel Edge Runtime
14 
15## Configuration
16 
17```ts
18// vitest.config.ts
19defineConfig({
20  test: {
21    environment: 'jsdom',
22    
23    // Environment-specific options
24    environmentOptions: {
25      jsdom: {
26        url: 'http://localhost',
27      },
28    },
29  },
30})
31```
32 
33## Installing Environment Packages
34 
35```bash
36# jsdom
37npm i -D jsdom
38 
39# happy-dom (faster, fewer APIs)
40npm i -D happy-dom
41```
42 
43## Per-File Environment
44 
45Use magic comment at top of file:
46 
47```ts
48// @vitest-environment jsdom
49 
50import { expect, test } from 'vitest'
51 
52test('DOM test', () => {
53  const div = document.createElement('div')
54  expect(div).toBeInstanceOf(HTMLDivElement)
55})
56```
57 
58## jsdom Environment
59 
60Full browser environment simulation:
61 
62```ts
63// @vitest-environment jsdom
64 
65test('DOM manipulation', () => {
66  document.body.innerHTML = '<div id="app"></div>'
67  
68  const app = document.getElementById('app')
69  app.textContent = 'Hello'
70  
71  expect(app.textContent).toBe('Hello')
72})
73 
74test('window APIs', () => {
75  expect(window.location.href).toBeDefined()
76  expect(localStorage).toBeDefined()
77})
78```
79 
80### jsdom Options
81 
82```ts
83defineConfig({
84  test: {
85    environmentOptions: {
86      jsdom: {
87        url: 'http://localhost:3000',
88        html: '<!DOCTYPE html><html><body></body></html>',
89        userAgent: 'custom-agent',
90        resources: 'usable',
91      },
92    },
93  },
94})
95```
96 
97## happy-dom Environment
98 
99Faster but fewer APIs:
100 
101```ts
102// @vitest-environment happy-dom
103 
104test('basic DOM', () => {
105  const el = document.createElement('div')
106  el.className = 'test'
107  expect(el.className).toBe('test')
108})
109```
110 
111## Multiple Environments per Project
112 
113Use projects for different environments:
114 
115```ts
116defineConfig({
117  test: {
118    projects: [
119      {
120        test: {
121          name: 'unit',
122          include: ['tests/unit/**/*.test.ts'],
123          environment: 'node',
124        },
125      },
126      {
127        test: {
128          name: 'dom',
129          include: ['tests/dom/**/*.test.ts'],
130          environment: 'jsdom',
131        },
132      },
133    ],
134  },
135})
136```
137 
138## Custom Environment
139 
140Create custom environment package:
141 
142```ts
143// vitest-environment-custom/index.ts
144import type { Environment } from 'vitest/runtime'
145 
146export default <Environment>{
147  name: 'custom',
148  viteEnvironment: 'ssr', // or 'client'
149  
150  setup() {
151    // Setup global state
152    globalThis.myGlobal = 'value'
153    
154    return {
155      teardown() {
156        delete globalThis.myGlobal
157      },
158    }
159  },
160}
161```
162 
163Use with:
164 
165```ts
166defineConfig({
167  test: {
168    environment: 'custom',
169  },
170})
171```
172 
173## Environment with VM
174 
175For full isolation:
176 
177```ts
178export default <Environment>{
179  name: 'isolated',
180  viteEnvironment: 'ssr',
181  
182  async setupVM() {
183    const vm = await import('node:vm')
184    const context = vm.createContext()
185    
186    return {
187      getVmContext() {
188        return context
189      },
190      teardown() {},
191    }
192  },
193  
194  setup() {
195    return { teardown() {} }
196  },
197}
198```
199 
200## Browser Mode (Separate from Environments)
201 
202For real browser testing, use Vitest Browser Mode:
203 
204```ts
205defineConfig({
206  test: {
207    browser: {
208      enabled: true,
209      name: 'chromium', // or 'firefox', 'webkit'
210      provider: 'playwright',
211    },
212  },
213})
214```
215 
216## CSS and Assets
217 
218In jsdom/happy-dom, configure CSS handling:
219 
220```ts
221defineConfig({
222  test: {
223    css: true, // Process CSS
224    
225    // Or with options
226    css: {
227      include: /\.module\.css$/,
228      modules: {
229        classNameStrategy: 'non-scoped',
230      },
231    },
232  },
233})
234```
235 
236## Fixing External Dependencies
237 
238If external deps fail with CSS/asset errors:
239 
240```ts
241defineConfig({
242  test: {
243    server: {
244      deps: {
245        inline: ['problematic-package'],
246      },
247    },
248  },
249})
250```
251 
252## Key Points
253 
254- Default is `node` - no browser APIs
255- Use `jsdom` for full browser simulation
256- Use `happy-dom` for faster tests with basic DOM
257- Per-file environment via `// @vitest-environment` comment
258- Use projects for multiple environment configurations
259- Browser Mode is for real browser testing, not environment
260 
261<!-- 
262Source references:
263- https://vitest.dev/guide/environment.html
264-->
265
Preparing the source view

vitest

references/advanced-environments.md
