You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/guide/improving-performance.md
+113
Original file line number
Diff line number
Diff line change
@@ -72,3 +72,116 @@ export default defineConfig({
72
72
})
73
73
```
74
74
:::
75
+
76
+
## Sharding
77
+
78
+
Test sharding means running a small subset of test cases at a time. It can be useful when you have multiple machines that could be used to run tests simultaneously.
79
+
80
+
To split Vitest tests on multiple different runs, use [`--shard`](/guide/cli#shard) option with [`--reporter=blob`](/guide/reporters#blob-reporter) option:
81
+
82
+
```sh
83
+
vitest run --reporter=blob --shard=1/3 # 1st machine
84
+
vitest run --reporter=blob --shard=2/3 # 2nd machine
85
+
vitest run --reporter=blob --shard=3/3 # 3rd machine
86
+
```
87
+
88
+
Collect the results stored in `.vitest-reports` directory from each machine and merge them with [`--merge-reports`](/guide/cli#merge-reports) option:
89
+
90
+
```sh
91
+
vitest --merge-reports
92
+
```
93
+
94
+
<details>
95
+
<summary>Github action example</summary>
96
+
97
+
This setup is also used at https://github.com/vitest-tests/test-sharding.
98
+
99
+
```yaml
100
+
# Inspired from https://playwright.dev/docs/test-sharding
101
+
name: Tests
102
+
on:
103
+
push:
104
+
branches:
105
+
- main
106
+
jobs:
107
+
tests:
108
+
runs-on: ubuntu-latest
109
+
strategy:
110
+
matrix:
111
+
shardIndex: [1, 2, 3, 4]
112
+
shardTotal: [4]
113
+
steps:
114
+
- uses: actions/checkout@v4
115
+
- uses: actions/setup-node@v4
116
+
with:
117
+
node-version: 20
118
+
119
+
- name: Install pnpm
120
+
uses: pnpm/action-setup@v4
121
+
122
+
- name: Install dependencies
123
+
run: pnpm i
124
+
125
+
- name: Run tests
126
+
run: pnpm run test --reporter=blob --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
127
+
128
+
- name: Upload blob report to GitHub Actions Artifacts
129
+
if: ${{ !cancelled() }}
130
+
uses: actions/upload-artifact@v4
131
+
with:
132
+
name: blob-report-${{ matrix.shardIndex }}
133
+
path: .vitest-reports/*
134
+
retention-days: 1
135
+
136
+
merge-reports:
137
+
if: ${{ !cancelled() }}
138
+
needs: [tests]
139
+
140
+
runs-on: ubuntu-latest
141
+
steps:
142
+
- uses: actions/checkout@v4
143
+
- uses: actions/setup-node@v4
144
+
with:
145
+
node-version: 20
146
+
147
+
- name: Install pnpm
148
+
uses: pnpm/action-setup@v4
149
+
150
+
- name: Install dependencies
151
+
run: pnpm i
152
+
153
+
- name: Download blob reports from GitHub Actions Artifacts
154
+
uses: actions/download-artifact@v4
155
+
with:
156
+
path: .vitest-reports
157
+
pattern: blob-report-*
158
+
merge-multiple: true
159
+
160
+
- name: Merge reports
161
+
run: npx vitest --merge-reports
162
+
```
163
+
164
+
</details>
165
+
166
+
:::tip
167
+
Test sharding can also become useful on high CPU-count machines.
168
+
169
+
Vitest will run only a single Vite server in its main thread. Rest of the threads are used to run test files.
170
+
In a high CPU-count machine the main thread can become a bottleneck as it cannot handle all the requests coming from the threads. For example in 32 CPU machine the main thread is responsible to handle load coming from 31 test threads.
171
+
172
+
To reduce the load from main thread's Vite server you can use test sharding. The load can be balanced on multiple Vite server.
173
+
174
+
```sh
175
+
# Example for splitting tests on 32 CPU to 4 shards.
176
+
# As each process needs 1 main thread, there's 7 threads for test runners (1+7)*4 = 32
177
+
# Use VITEST_MAX_THREADS or VITEST_MAX_FORKS depending on the pool:
178
+
VITEST_MAX_THREADS=7 vitest run --reporter=blob --shard=1/4 & \
179
+
VITEST_MAX_THREADS=7 vitest run --reporter=blob --shard=2/4 & \
180
+
VITEST_MAX_THREADS=7 vitest run --reporter=blob --shard=3/4 & \
181
+
VITEST_MAX_THREADS=7 vitest run --reporter=blob --shard=4/4 & \
0 commit comments