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
+99
Original file line number
Diff line number
Diff line change
@@ -72,3 +72,102 @@ 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
+
```yaml
98
+
# Inspired from https://playwright.dev/docs/test-sharding
99
+
name: Tests
100
+
on:
101
+
push:
102
+
branches:
103
+
- main
104
+
jobs:
105
+
tests:
106
+
runs-on: ubuntu-latest
107
+
strategy:
108
+
matrix:
109
+
shardIndex: [1, 2, 3, 4]
110
+
shardTotal: [4]
111
+
steps:
112
+
- uses: actions/checkout@v4
113
+
- uses: actions/setup-node@v4
114
+
- name: Install dependencies
115
+
run: pnpm i
116
+
117
+
- name: Run tests
118
+
run: pnpm run test --reporter=blob --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
119
+
120
+
- name: Upload blob report to GitHub Actions Artifacts
121
+
if: ${{ !cancelled() }}
122
+
uses: actions/upload-artifact@v4
123
+
with:
124
+
name: blob-report-${{ matrix.shardIndex }}
125
+
path: blob-report
126
+
retention-days: 1
127
+
128
+
merge-reports:
129
+
if: ${{ !cancelled() }}
130
+
needs: [tests]
131
+
132
+
runs-on: ubuntu-latest
133
+
steps:
134
+
- uses: actions/checkout@v4
135
+
- uses: actions/setup-node@v4
136
+
- name: Install dependencies
137
+
run: pnpm i
138
+
139
+
- name: Download blob reports from GitHub Actions Artifacts
140
+
uses: actions/download-artifact@v4
141
+
with:
142
+
path: all-blob-reports
143
+
pattern: blob-report-*
144
+
merge-multiple: true
145
+
146
+
- name: Merge reports
147
+
run: npx vitest --merge-reports
148
+
```
149
+
150
+
</details>
151
+
152
+
:::tip
153
+
Test sharding can also become useful on high CPU-count machines.
154
+
155
+
Vitest will run only a single Vite server in its main thread. Rest of the threads are used to run test files.
156
+
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.
157
+
158
+
To reduce the load from main thread's Vite server you can use test sharding. The load can be balanced on multiple Vite server.
159
+
160
+
```sh
161
+
# Example for splitting tests on 32 CPU to 4 shards.
162
+
# As each process needs 1 main thread, there's 7 threads for test runners (1+7)*4 = 32
163
+
# Use VITEST_MAX_THREADS or VITEST_MAX_FORKS depending on the pool:
164
+
VITEST_MAX_THREADS=7 vitest run --reporter=blob --shard=1/4 & \
165
+
VITEST_MAX_THREADS=7 vitest run --reporter=blob --shard=2/4 & \
166
+
VITEST_MAX_THREADS=7 vitest run --reporter=blob --shard=3/4 & \
167
+
VITEST_MAX_THREADS=7 vitest run --reporter=blob --shard=4/4 & \
0 commit comments