[READ-ONLY] Mirror of https://github.com/vitest-dev/vitest. Next generation testing framework powered by Vite.
vitest.dev
test
testing-tools
vite
docs: clarify workspace docs (#7849)
+106
-103
+1
-1
docs/config/index.md
+1
-1
docs/config/index.md
···
106
106
107
107
Since Vitest uses Vite config, you can also use any configuration option from [Vite](https://vitejs.dev/config/). For example, `define` to define global variables, or `resolve.alias` to define aliases - these options should be defined on the top level, _not_ within a `test` property.
108
108
109
-
Configuration options that are not supported inside a [workspace](/guide/workspace) project config have <NonProjectOption /> sign next to them.
109
+
Configuration options that are not supported inside a [workspace](/guide/workspace) project config have <NonProjectOption /> sign next to them. This means they can only be set in the root Vitest config.
110
110
:::
111
111
112
112
### include
+31
-27
docs/guide/index.md
+31
-27
docs/guide/index.md
···
177
177
178
178
## Workspaces Support
179
179
180
-
Run different project configurations inside the same project with [Vitest Workspaces](/guide/workspace). You can define a list of files and folders that define your workspace in `vitest.workspace` file. The file supports `js`/`ts`/`json` extensions. This feature works great with monorepo setups.
180
+
Run different project configurations inside the same project with [Vitest Workspaces](/guide/workspace). You can define a list of files and folders that define your workspace in `vitest.config` file.
181
181
182
-
```ts [vitest.workspace.ts]
183
-
import { defineWorkspace } from 'vitest/config'
182
+
```ts [vitest.config.ts]
183
+
import { defineConfig } from 'vitest/config'
184
184
185
-
export default defineWorkspace([
186
-
// you can use a list of glob patterns to define your workspaces
187
-
// Vitest expects a list of config files
188
-
// or directories where there is a config file
189
-
'packages/*',
190
-
'tests/*/vitest.config.{e2e,unit}.ts',
191
-
// you can even run the same tests,
192
-
// but with different configs in the same "vitest" process
193
-
{
194
-
test: {
195
-
name: 'happy-dom',
196
-
root: './shared_tests',
197
-
environment: 'happy-dom',
198
-
setupFiles: ['./setup.happy-dom.ts'],
199
-
},
185
+
export default defineConfig({
186
+
test: {
187
+
workspace: [
188
+
// you can use a list of glob patterns to define your workspaces
189
+
// Vitest expects a list of config files
190
+
// or directories where there is a config file
191
+
'packages/*',
192
+
'tests/*/vitest.config.{e2e,unit}.ts',
193
+
// you can even run the same tests,
194
+
// but with different configs in the same "vitest" process
195
+
{
196
+
test: {
197
+
name: 'happy-dom',
198
+
root: './shared_tests',
199
+
environment: 'happy-dom',
200
+
setupFiles: ['./setup.happy-dom.ts'],
201
+
},
202
+
},
203
+
{
204
+
test: {
205
+
name: 'node',
206
+
root: './shared_tests',
207
+
environment: 'node',
208
+
setupFiles: ['./setup.node.ts'],
209
+
},
210
+
},
211
+
],
200
212
},
201
-
{
202
-
test: {
203
-
name: 'node',
204
-
root: './shared_tests',
205
-
environment: 'node',
206
-
setupFiles: ['./setup.node.ts'],
207
-
},
208
-
},
209
-
])
213
+
})
210
214
```
211
215
212
216
## Command Line Interface
+74
-75
docs/guide/workspace.md
+74
-75
docs/guide/workspace.md
···
14
14
15
15
## Defining a Workspace
16
16
17
-
A workspace must include a `vitest.workspace` or `vitest.projects` file in its root directory (located in the same folder as your root configuration file or working directory if it doesn't exist). Note that `projects` is just an alias and does not change the behavior or semantics of this feature. Vitest supports `ts`, `js`, and `json` extensions for this file.
17
+
Since Vitest 3, you can define a workspace in your root [config](/config/). In this case, Vitest will ignore the `vitest.workspace` file in the root, if one exists.
18
18
19
-
Since Vitest 3, you can also define a workspace in the root config. In this case, Vitest will ignore the `vitest.workspace` file in the root, if one exists.
19
+
```ts [vitest.config.ts]
20
+
import { defineConfig } from 'vitest/config'
21
+
22
+
export default defineConfig({
23
+
test: {
24
+
workspace: ['packages/*'],
25
+
},
26
+
})
27
+
```
28
+
29
+
If you are using an older version, a workspace must include `vitest.workspace` or `vitest.projects` file in its root directory (located in the same folder as your root configuration file or working directory if it doesn't exist). Note that `projects` is just an alias and does not change the behavior or semantics of this feature. Vitest supports `ts`, `js`, and `json` extensions for this file.
20
30
21
31
::: tip NAMING
22
32
Please note that this feature is named `workspace`, not `workspaces` (without an "s" at the end).
···
25
35
A workspace is a list of inlined configs, files, or glob patterns referencing your projects. For example, if you have a folder named `packages` that contains your projects, you can either create a workspace file or define an array in the root config:
26
36
27
37
:::code-group
28
-
```ts [vitest.workspace.ts]
29
-
export default [
30
-
'packages/*'
31
-
]
32
-
```
33
38
```ts [vitest.config.ts <Version>3.0.0</Version>]
34
39
import { defineConfig } from 'vitest/config'
35
40
···
38
43
workspace: ['packages/*'],
39
44
},
40
45
})
46
+
```
47
+
```ts [vitest.workspace.ts]
48
+
export default [
49
+
'packages/*'
50
+
]
41
51
```
42
52
:::
43
53
···
50
60
You can also reference projects with their config files:
51
61
52
62
:::code-group
53
-
```ts [vitest.workspace.ts]
54
-
export default [
55
-
'packages/*/vitest.config.{e2e,unit}.ts'
56
-
]
57
-
```
58
63
```ts [vitest.config.ts <Version>3.0.0</Version>]
59
64
import { defineConfig } from 'vitest/config'
60
65
···
64
69
},
65
70
})
66
71
```
72
+
```ts [vitest.workspace.ts]
73
+
export default [
74
+
'packages/*/vitest.config.{e2e,unit}.ts'
75
+
]
76
+
```
67
77
:::
68
78
69
79
This pattern will only include projects with a `vitest.config` file that contains `e2e` or `unit` before the extension.
70
80
71
-
You can also define projects using inline configuration. The workspace file supports both syntaxes simultaneously.
81
+
You can also define projects using inline configuration. The workspace configuration supports both syntaxes simultaneously.
72
82
73
83
:::code-group
74
-
```ts [vitest.workspace.ts]
75
-
import { defineWorkspace } from 'vitest/config'
76
-
77
-
// defineWorkspace provides a nice type hinting DX
78
-
export default defineWorkspace([
79
-
// matches every folder and file inside the `packages` folder
80
-
'packages/*',
81
-
{
82
-
// add "extends" to merge two configs together
83
-
extends: './vite.config.js',
84
-
test: {
85
-
include: ['tests/**/*.{browser}.test.{ts,js}'],
86
-
// it is recommended to define a name when using inline configs
87
-
name: 'happy-dom',
88
-
environment: 'happy-dom',
89
-
}
90
-
},
91
-
{
92
-
test: {
93
-
include: ['tests/**/*.{node}.test.{ts,js}'],
94
-
name: 'node',
95
-
environment: 'node',
96
-
}
97
-
}
98
-
])
99
-
```
100
84
```ts [vitest.config.ts <Version>3.0.0</Version>]
101
85
import { defineConfig } from 'vitest/config'
102
86
···
126
110
}
127
111
})
128
112
```
113
+
```ts [vitest.workspace.ts]
114
+
import { defineWorkspace } from 'vitest/config'
115
+
116
+
// defineWorkspace provides a nice type hinting DX
117
+
export default defineWorkspace([
118
+
// matches every folder and file inside the `packages` folder
119
+
'packages/*',
120
+
{
121
+
// add "extends" to merge two configs together
122
+
extends: './vite.config.js',
123
+
test: {
124
+
include: ['tests/**/*.{browser}.test.{ts,js}'],
125
+
// it is recommended to define a name when using inline configs
126
+
name: 'happy-dom',
127
+
environment: 'happy-dom',
128
+
}
129
+
},
130
+
{
131
+
test: {
132
+
include: ['tests/**/*.{node}.test.{ts,js}'],
133
+
name: 'node',
134
+
environment: 'node',
135
+
}
136
+
}
137
+
])
138
+
```
129
139
:::
130
140
131
141
::: warning
···
134
144
135
145
If you do not use inline configurations, you can create a small JSON file in your root directory or just specify it in the root config:
136
146
137
-
:::code-group
138
147
```json [vitest.workspace.json]
139
148
[
140
149
"packages/*"
141
150
]
142
151
```
143
-
```ts [vitest.config.ts <Version>3.0.0</Version>]
144
-
import { defineConfig } from 'vitest/config'
145
-
146
-
export default defineConfig({
147
-
test: {
148
-
workspace: ['packages/*'],
149
-
},
150
-
})
151
-
```
152
-
:::
153
152
154
153
Workspace projects do not support all configuration properties. For better type safety, use the `defineProject` method instead of `defineConfig` within project configuration files:
155
154
···
192
191
pnpm run test
193
192
```
194
193
```bash [bun]
195
-
bun test
194
+
bun run test
196
195
```
197
196
:::
198
197
···
209
208
pnpm run test --project e2e
210
209
```
211
210
```bash [bun]
212
-
bun test --project e2e
211
+
bun run test --project e2e
213
212
```
214
213
:::
215
214
···
227
226
pnpm run test --project e2e --project unit
228
227
```
229
228
```bash [bun]
230
-
bun test --project e2e --project unit
229
+
bun run test --project e2e --project unit
231
230
```
232
231
:::
233
232
···
252
251
Additionally, at the `defineWorkspace` level, you can use the `extends` option to inherit from your root-level configuration. All options will be merged.
253
252
254
253
::: code-group
255
-
```ts [vitest.workspace.ts]
256
-
import { defineWorkspace } from 'vitest/config'
257
-
258
-
export default defineWorkspace([
259
-
{
260
-
extends: './vitest.config.ts',
261
-
test: {
262
-
name: 'unit',
263
-
include: ['**/*.unit.test.ts'],
264
-
},
265
-
},
266
-
{
267
-
extends: './vitest.config.ts',
268
-
test: {
269
-
name: 'integration',
270
-
include: ['**/*.integration.test.ts'],
271
-
},
272
-
},
273
-
])
274
-
```
275
254
```ts [vitest.config.ts <Version>3.0.0</Version>]
276
255
import { defineConfig } from 'vitest/config'
277
256
import react from '@vitejs/plugin-react'
···
302
281
},
303
282
})
304
283
```
284
+
```ts [vitest.workspace.ts]
285
+
import { defineWorkspace } from 'vitest/config'
286
+
287
+
export default defineWorkspace([
288
+
{
289
+
extends: './vitest.config.ts',
290
+
test: {
291
+
name: 'unit',
292
+
include: ['**/*.unit.test.ts'],
293
+
},
294
+
},
295
+
{
296
+
extends: './vitest.config.ts',
297
+
test: {
298
+
name: 'integration',
299
+
include: ['**/*.integration.test.ts'],
300
+
},
301
+
},
302
+
])
303
+
```
305
304
:::
306
305
306
+
::: danger Unsupported Options
307
307
Some of the configuration options are not allowed in a project config. Most notably:
308
308
309
309
- `coverage`: coverage is done for the whole workspace
···
311
311
- `resolveSnapshotPath`: only root-level resolver is respected
312
312
- all other options that don't affect test runners
313
313
314
-
::: tip
315
-
All configuration options that are not supported inside a project configuration are marked with a <NonProjectOption /> sign in the ["Config"](/config/) guide.
314
+
All configuration options that are not supported inside a project configuration are marked with a <NonProjectOption /> sign in the ["Config"](/config/) guide. They have to be defined once in the root config file.
316
315
:::