1---
2name: concurrency-parallelism
3description: Concurrent tests, parallel execution, and sharding
4---
5 
6# Concurrency & Parallelism
7 
8## File Parallelism
9 
10By default, Vitest runs test files in parallel across workers:
11 
12```ts
13defineConfig({
14  test: {
15    // Run files in parallel (default: true)
16    fileParallelism: true,
17    
18    // Number of worker threads
19    maxWorkers: 4,
20    minWorkers: 1,
21    
22    // Pool type: 'threads', 'forks', 'vmThreads'
23    pool: 'threads',
24  },
25})
26```
27 
28## Concurrent Tests
29 
30Run tests within a file in parallel:
31 
32```ts
33// Individual concurrent tests
34test.concurrent('test 1', async ({ expect }) => {
35  expect(await fetch1()).toBe('result')
36})
37 
38test.concurrent('test 2', async ({ expect }) => {
39  expect(await fetch2()).toBe('result')
40})
41 
42// All tests in suite concurrent
43describe.concurrent('parallel suite', () => {
44  test('test 1', async ({ expect }) => {})
45  test('test 2', async ({ expect }) => {})
46})
47```
48 
49**Important:** Use `{ expect }` from context for concurrent tests.
50 
51## Sequential in Concurrent Context
52 
53Force sequential execution:
54 
55```ts
56describe.concurrent('mostly parallel', () => {
57  test('parallel 1', async () => {})
58  test('parallel 2', async () => {})
59  
60  test.sequential('must run alone 1', async () => {})
61  test.sequential('must run alone 2', async () => {})
62})
63 
64// Or entire suite
65describe.sequential('sequential suite', () => {
66  test('first', () => {})
67  test('second', () => {})
68})
69```
70 
71## Max Concurrency
72 
73Limit concurrent tests:
74 
75```ts
76defineConfig({
77  test: {
78    maxConcurrency: 5, // Max concurrent tests per file
79  },
80})
81```
82 
83## Isolation
84 
85Each file runs in isolated environment by default:
86 
87```ts
88defineConfig({
89  test: {
90    // Disable isolation for faster runs (less safe)
91    isolate: false,
92  },
93})
94```
95 
96## Sharding
97 
98Split tests across machines:
99 
100```bash
101# Machine 1
102vitest run --shard=1/3
103 
104# Machine 2
105vitest run --shard=2/3
106 
107# Machine 3
108vitest run --shard=3/3
109```
110 
111### CI Example (GitHub Actions)
112 
113```yaml
114jobs:
115  test:
116    strategy:
117      matrix:
118        shard: [1, 2, 3]
119    steps:
120      - run: vitest run --shard=${{ matrix.shard }}/3 --reporter=blob
121      
122  merge:
123    needs: test
124    steps:
125      - run: vitest --merge-reports --reporter=junit
126```
127 
128### Merge Reports
129 
130```bash
131# Each shard outputs blob
132vitest run --shard=1/3 --reporter=blob --coverage
133vitest run --shard=2/3 --reporter=blob --coverage
134 
135# Merge all blobs
136vitest --merge-reports --reporter=json --coverage
137```
138 
139## Test Sequence
140 
141Control test order:
142 
143```ts
144defineConfig({
145  test: {
146    sequence: {
147      // Run tests in random order
148      shuffle: true,
149      
150      // Seed for reproducible shuffle
151      seed: 12345,
152      
153      // Hook execution order
154      hooks: 'stack', // 'stack', 'list', 'parallel'
155      
156      // All tests concurrent by default
157      concurrent: true,
158    },
159  },
160})
161```
162 
163## Shuffle Tests
164 
165Randomize to catch hidden dependencies:
166 
167```ts
168// Via CLI
169vitest --sequence.shuffle
170 
171// Per suite
172describe.shuffle('random order', () => {
173  test('test 1', () => {})
174  test('test 2', () => {})
175  test('test 3', () => {})
176})
177```
178 
179## Pool Options
180 
181### Threads (Default)
182 
183```ts
184defineConfig({
185  test: {
186    pool: 'threads',
187    poolOptions: {
188      threads: {
189        maxThreads: 8,
190        minThreads: 2,
191        isolate: true,
192      },
193    },
194  },
195})
196```
197 
198### Forks
199 
200Better isolation, slower:
201 
202```ts
203defineConfig({
204  test: {
205    pool: 'forks',
206    poolOptions: {
207      forks: {
208        maxForks: 4,
209        isolate: true,
210      },
211    },
212  },
213})
214```
215 
216### VM Threads
217 
218Full VM isolation per file:
219 
220```ts
221defineConfig({
222  test: {
223    pool: 'vmThreads',
224  },
225})
226```
227 
228## Bail on Failure
229 
230Stop after first failure:
231 
232```bash
233vitest --bail 1    # Stop after 1 failure
234vitest --bail      # Stop on first failure (same as --bail 1)
235```
236 
237## Key Points
238 
239- Files run in parallel by default
240- Use `.concurrent` for parallel tests within file
241- Always use context's `expect` in concurrent tests
242- Sharding splits tests across CI machines
243- Use `--merge-reports` to combine sharded results
244- Shuffle tests to find hidden dependencies
245 
246<!-- 
247Source references:
248- https://vitest.dev/guide/features.html#running-tests-concurrently
249- https://vitest.dev/guide/improving-performance.html
250-->
251