chore: add blog post for Vitest 4.1 (#9775) · vitest.dev/vitest@d505c73

+483

docs/blog/vitest-4-1.md

··· 1 + --- 2 + title: Vitest 4.1 is out! 3 + author: 4 + name: The Vitest Team 5 + date: 2026-03-12 6 + sidebar: false 7 + head: 8 + - - meta 9 + - property: og:type 10 + content: website 11 + - - meta 12 + - property: og:title 13 + content: Announcing Vitest 4.1 14 + - - meta 15 + - property: og:image 16 + content: https://vitest.dev/og-vitest-4-1.jpg 17 + - - meta 18 + - property: og:url 19 + content: https://vitest.dev/blog/vitest-4-1 20 + - - meta 21 + - property: og:description 22 + content: Vitest 4.1 Release Announcement 23 + - - meta 24 + - name: twitter:card 25 + content: summary_large_image 26 + --- 27 + 28 + # Vitest 4.1 is out! 29 + 30 + _March 12, 2026_ 31 + 32 + ![Vitest 4.1 Announcement Cover Image](/og-vitest-4-1.jpg) 33 + 34 + ## The next Vitest minor is here 35 + 36 + Today, we are thrilled to announce Vitest 4.1 packed with new exciting features! 37 + 38 + Quick links: 39 + 40 + - [Docs](/) 41 + - Translations: [简体中文](https://cn.vitest.dev/) 42 + - [GitHub Changelog](https://github.com/vitest-dev/vitest/releases/tag/v4.1.0) 43 + 44 + If you've not used Vitest before, we suggest reading the [Getting Started](/guide/) and [Features](/guide/features) guides first. 45 + 46 + We extend our gratitude to the over [713 contributors to Vitest Core](https://github.com/vitest-dev/vitest/graphs/contributors) and to the maintainers and contributors of Vitest integrations, tools, and translations who have helped us develop this new release. We encourage you to get involved and help us improve Vitest for the entire ecosystem. Learn more at our [Contributing Guide](https://github.com/vitest-dev/vitest/blob/main/CONTRIBUTING.md). 47 + 48 + To get started, we suggest helping [triage issues](https://github.com/vitest-dev/vitest/issues), [review PRs](https://github.com/vitest-dev/vitest/pulls), send failing tests PRs based on open issues, and support others in [Discussions](https://github.com/vitest-dev/vitest/discussions) and Vitest Land's [help forum](https://discord.com/channels/917386801235247114/1057959614160851024). If you'd like to talk to us, join our [Discord community](http://chat.vitest.dev/) and say hi on the [#contributing channel](https://discord.com/channels/917386801235247114/1057959614160851024). 49 + 50 + For the latest news about the Vitest ecosystem and Vitest core, follow us on [Bluesky](https://bsky.app/profile/vitest.dev) or [Mastodon](https://webtoo.ls/@vitest). 51 + 52 + To stay updated, keep an eye on the [VoidZero blog](https://voidzero.dev/blog) and subscribe to the [newsletter](https://voidzero.dev/newsletter). 53 + 54 + ## Vite 8 Support 55 + 56 + This release adds support for the new Vite 8 version. Additionally, Vitest now uses the installed `vite` version instead of downloading a separate dependency, if possible. This makes issues like type inconsistencies in your config file obsolete. 57 + 58 + ## Test Tags 59 + 60 + [Tags](/guide/test-tags) let you label tests to organize them into groups. Once tagged, you can filter tests by tag or apply shared options - like a longer timeout or automatic retries - to every test with a given tag. 61 + 62 + To use tags, define them in your configuration file. Each tag requires a `name` and can optionally include test options that apply to every test marked with that tag. For the full list of available options, see [`tags`](/config/tags). 63 + 64 + ```ts [vitest.config.js] 65 + import { defineConfig } from 'vitest/config' 66 + 67 + export default defineConfig({ 68 + test: { 69 + tags: [ 70 + { 71 + name: 'db', 72 + description: 'Tests for database queries.', 73 + timeout: 60_000, 74 + }, 75 + { 76 + name: 'flaky', 77 + description: 'Flaky CI tests.', 78 + retry: process.env.CI ? 3 : 0, 79 + }, 80 + ], 81 + }, 82 + }) 83 + ``` 84 + 85 + With this configuration, you can apply `flaky` and `db` tags to your tests: 86 + 87 + ```ts 88 + test('flaky database test', { tags: ['flaky', 'db'] }, () => { 89 + // ... 90 + }) 91 + ``` 92 + 93 + The test has a timeout of 60 seconds and will be retried 3 times on CI because these options were specified in the configuration file for `db` and `flaky` tags. 94 + 95 + Inspired by [pytest](https://docs.pytest.org/en/stable/reference/reference.html#cmdoption-m), Vitest supports a custom syntax for filtering tags: 96 + 97 + - `and` or `&&` to include both expressions 98 + - `or` or `||` to include at least one expression 99 + - `not` or `!` to exclude the expression 100 + - `*` to match any number of characters (0 or more) 101 + - `()` to group expressions and override precedence 102 + 103 + Here are some common filtering patterns: 104 + 105 + ```shell 106 + # Run only unit tests 107 + vitest --tags-filter="unit" 108 + 109 + # Run tests that are both frontend AND fast 110 + vitest --tags-filter="frontend and fast" 111 + 112 + # Run frontend tests that are not flaky 113 + vitest --tags-filter="frontend && !flaky" 114 + 115 + # Run tests matching a wildcard pattern 116 + vitest --tags-filter="api/*" 117 + ``` 118 + 119 + ## Experimental `viteModuleRunner: false` 120 + 121 + By default, Vitest runs all code inside Vite's [module runner](https://vite.dev/guide/api-environment-runtimes#modulerunner) — a permissive sandbox that provides `import.meta.env`, `require`, `__dirname`, `__filename`, and applies Vite plugins and aliases. While this makes getting started easy, it can hide real issues: your tests may pass in the sandbox but fail in production because the runtime behavior differs from native Node.js. 122 + 123 + Vitest 4.1 introduces [`experimental.viteModuleRunner`](/config/experimental#experimental-vitemodulerunner), which lets you disable the module runner entirely and run tests with native `import` instead: 124 + 125 + ```ts [vitest.config.ts] 126 + import { defineConfig } from 'vitest/config' 127 + 128 + export default defineConfig({ 129 + test: { 130 + experimental: { 131 + viteModuleRunner: false, 132 + }, 133 + }, 134 + }) 135 + ``` 136 + 137 + With this flag, **no file transforms are applied** — your test files, source code, and setup files are executed by Node.js directly. This means faster startup, closer-to-production behavior, and issues like incorrect `__dirname` injection or silently passing imports of nonexistent exports are caught early. 138 + 139 + If you are using Node.js 22.18+ or 23.6+, TypeScript is [stripped natively](https://nodejs.org/en/learn/typescript/run-natively) — no extra configuration needed. 140 + 141 + Mocking with `vi.mock` and `vi.hoisted` is supported via the Node.js [Module Loader API](https://nodejs.org/api/module.html#customization-hooks) (requires Node.js 22.15+). Note that `import.meta.env`, Vite plugins, aliases, and the `istanbul` coverage provider are not available in this mode. 142 + 143 + Consider this option if you run server-side or script-like tests that don't need Vite transforms. For `jsdom`/`happy-dom` tests, we still recommend the default module runner or [browser mode](/guide/browser/). 144 + 145 + Read more in the [`experimental.viteModuleRunner` docs](/config/experimental#experimental-vitemodulerunner). 146 + 147 + ## Configure UI Browser Window 148 + 149 + Vitest 4.1 introduces [`browser.detailsPanelPosition`](/config/browser/detailspanelposition), letting you choose where the details panel appears in Browser UI. 150 + 151 + <center> 152 + <img alt="Vitest UI with details at the bottom" img-light src="/ui/light-ui-details-bottom.png"> 153 + <img alt="Vitest UI with details at the bottom" img-dark src="/ui/dark-ui-details-bottom.png"> 154 + 155 + An example of UI with the details panel at the bottom. 156 + </center> 157 + 158 + This is especially useful on smaller screens, where switching to a bottom panel leaves more horizontal space for your app: 159 + 160 + ```ts [vitest.config.ts] 161 + import { defineConfig } from 'vitest/config' 162 + 163 + export default defineConfig({ 164 + test: { 165 + browser: { 166 + enabled: true, 167 + detailsPanelPosition: 'bottom', // or 'right' 168 + }, 169 + }, 170 + }) 171 + ``` 172 + 173 + You can also switch this directly from the UI via the new layout toggle button. 174 + 175 + ## Enhanced Browser Trace View 176 + 177 + Vitest 4.1 brings major improvements to the [Playwright Trace Viewer](/guide/browser/trace-view) integration in browser mode. Browser interactions like `click`, `fill`, and `expect.element` are now automatically grouped in the trace timeline and linked back to the exact line in your test file. 178 + 179 + <center> 180 + <img alt="Trace Viewer showing the trace timeline and rendered component" img-light src="/trace-viewer-light.png"> 181 + <img alt="Trace Viewer showing the trace timeline and rendered component" img-dark src="/trace-viewer-dark.png"> 182 + 183 + An example of trace view with `expect.element` assertion failure highlighted. 184 + </center> 185 + 186 + Framework libraries are also integrating with the trace. For example, [`vitest-browser-react`](https://github.com/vitest-community/vitest-browser-react)'s `render()` utility now automatically appears in the trace with rendered element highlighted. 187 + 188 + For custom annotations, the new [`page.mark`](/api/browser/context#mark) and [`locator.mark`](/api/browser/locators#mark) APIs let you add your own markers to the trace: 189 + 190 + ```ts 191 + import { page } from 'vitest/browser' 192 + 193 + await page.mark('before sign in') 194 + await page.getByRole('button', { name: 'Sign in' }).click() 195 + await page.mark('after sign in') 196 + ``` 197 + 198 + You can also group a whole flow under one named entry: 199 + 200 + ```ts 201 + await page.mark('sign in flow', async () => { 202 + await page.getByRole('textbox', { name: 'Email' }).fill('john@example.com') 203 + await page.getByRole('textbox', { name: 'Password' }).fill('secret') 204 + await page.getByRole('button', { name: 'Sign in' }).click() 205 + }) 206 + ``` 207 + 208 + Read more in the [Trace View guide](/guide/browser/trace-view). 209 + 210 + ## Type-Inference in `test.extend` - New Builder Pattern 211 + 212 + Vitest 4.1 introduces a new [`test.extend`](/guide/test-context) pattern that supports type inference. You can return a value from the factory instead of calling the `use` function - TypeScript infers the type of each fixture from its return value, so you don't need to declare types manually. 213 + 214 + ```ts 215 + import { test as baseTest } from 'vitest' 216 + 217 + export const test = baseTest 218 + // Simple value - type is inferred as { port: number; host: string } 219 + .extend('config', { port: 3000, host: 'localhost' }) 220 + // Function fixture - type is inferred from return value 221 + .extend('server', async ({ config }) => { 222 + // TypeScript knows config is { port: number; host: string } 223 + return `http://${config.host}:${config.port}` 224 + }) 225 + ``` 226 + 227 + For fixtures that need setup or cleanup logic, use a function. The `onCleanup` callback registers teardown logic that runs after the fixture's scope ends: 228 + 229 + ```ts 230 + import { test as baseTest } from 'vitest' 231 + 232 + export const test = baseTest 233 + .extend('tempFile', async ({}, { onCleanup }) => { 234 + const filePath = `/tmp/test-${Date.now()}.txt` 235 + await fs.writeFile(filePath, 'test data') 236 + 237 + // Register cleanup - runs after test completes 238 + onCleanup(() => fs.unlink(filePath)) 239 + 240 + return filePath 241 + }) 242 + ``` 243 + 244 + In addition to this, Vitest now passes down `file` and `worker` contexts to `beforeAll`, `afterAll` and `aroundAll` hooks: 245 + 246 + ```ts 247 + import { test as baseTest } from 'vitest' 248 + 249 + const test = baseTest 250 + .extend('config', { scope: 'file' }, () => loadConfig()) 251 + .extend('db', { scope: 'file' }, ({ config }) => createDatabase(config.port)) 252 + 253 + test.beforeAll(async ({ db }) => { 254 + await db.migrateUsers() 255 + }) 256 + 257 + test.afterAll(async ({ db }) => { 258 + await db.deleteUsers() 259 + }) 260 + ``` 261 + 262 + ::: warning 263 + This change could be considered breaking - previously Vitest passed down undocumented `Suite` as the first argument. The team decided that the usage was small enough to not disrupt the ecosystem. 264 + ::: 265 + 266 + ## New `aroundAll` and `aroundEach` Hooks 267 + 268 + The new `aroundEach` hook registers a callback function that wraps around each test within the current suite. The callback receives a `runTest` function that **must** be called to run the test. The `aroundAll` hook works similarly, but is called for every suite, not every test. 269 + 270 + You should use `aroundEach` when your test needs to run **inside a context** that wraps around it, such as: 271 + - Wrapping tests in [AsyncLocalStorage](https://nodejs.org/api/async_context.html#class-asynclocalstorage) context 272 + - Wrapping tests with tracing spans 273 + - Database transactions 274 + 275 + ```ts 276 + import { test as baseTest } from 'vitest' 277 + 278 + const test = baseTest 279 + .extend('db', async ({}, { onCleanup }) => { 280 + // db is created before `aroundEach` hook 281 + const db = await createTestDatabase() 282 + onCleanup(() => db.close()) 283 + return db 284 + }) 285 + 286 + test.aroundEach(async (runTest, { db }) => { 287 + await db.transaction(runTest) 288 + }) 289 + 290 + test('insert user', async ({ db }) => { 291 + // called inside a transaction 292 + await db.insert({ name: 'Alice' }) 293 + }) 294 + ``` 295 + 296 + ## Helper for Better Stack Traces 297 + 298 + When a test fails inside a shared utility function, the stack trace usually points to the line inside that helper - not where it was called. This makes it harder to find which test actually failed, especially when the same helper is used across many tests. 299 + 300 + [`vi.defineHelper`](/api/vi#vi-definehelper) wraps a function so that Vitest removes its internals from the stack trace and points the error back to the call site instead: 301 + 302 + ```ts 303 + import { expect, test, vi } from 'vitest' 304 + 305 + const assertPair = vi.defineHelper((a, b) => { 306 + expect(a).toEqual(b) // 🙅‍♂️ error code block will NOT point to here 307 + }) 308 + 309 + test('example', () => { 310 + assertPair('left', 'right') // 🙆 but point to here 311 + }) 312 + ``` 313 + 314 + This is especially useful for custom assertion libraries and reusable test utilities where the call site is more meaningful than the implementation. 315 + 316 + ## `--detect-async-leaks` to Catch Leaks 317 + 318 + Leaked timers, handles, and unresolved async resources can make test suites flaky and hard to debug. Vitest 4.1 adds [`detectAsyncLeaks`](/config/detectasyncleaks) to help track these issues. 319 + 320 + You can enable it via CLI: 321 + 322 + ```sh 323 + vitest --detect-async-leaks 324 + ``` 325 + 326 + Or in config: 327 + 328 + ```ts [vitest.config.ts] 329 + import { defineConfig } from 'vitest/config' 330 + 331 + export default defineConfig({ 332 + test: { 333 + detectAsyncLeaks: true, 334 + }, 335 + }) 336 + ``` 337 + 338 + When enabled, Vitest uses `node:async_hooks` to report leaked async resources with source locations. Since this adds runtime overhead, it is best used while debugging. 339 + 340 + ## `vscode` Improvements 341 + 342 + The official [vscode extension](https://vitest.dev/vscode) received a large number of fixes and new features: 343 + 344 + - The extension no longer keeps a running process in the background unless you explicitly enable continuous run manually or via a new config option `watchOnStartup`. This reduces memory usage and eliminates the `maximumConfigs` config option. 345 + - The new "Run Related Tests" command runs tests that import the currently open file. 346 + - The new "Toggle Continuous Run" action is now available when clicking on the gutter icon. 347 + - The extension now supports [Deno runtime](https://deno.com/). 348 + - The extension cancels the test run sooner after clicking "Stop", when possible. 349 + - The extension displays the module load time inline next to each import statement, if you are using Vitest 4.1. 350 + 351 + <center> 352 + <img src="/vscode-import-breakdown.png" alt="An example of import breakdown in vscode"> 353 + An example of import breakdown in vscode. 354 + </center> 355 + 356 + ## GitHub Actions Job Summary 357 + 358 + The built-in [`github-actions` reporter](/guide/reporters#github-actions-reporter) now automatically generates a [Job Summary](https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/) with an overview of your test results. The summary includes test file and test case statistics, and highlights flaky tests that required retries — with permalink URLs linking test names directly to the relevant source lines on GitHub. 359 + 360 + <center> 361 + <img alt="GitHub Actions Job Summary" img-dark src="/github-actions-job-summary-dark.png"> 362 + <img alt="GitHub Actions Job Summary" img-light src="/github-actions-job-summary-light.png"> 363 + 364 + An example of the job summary with flaky test details. 365 + </center> 366 + 367 + The summary is enabled by default when running in GitHub Actions and writes to the path specified by `$GITHUB_STEP_SUMMARY`. No configuration is needed in most cases. To disable it or customize the output path: 368 + 369 + ```ts [vitest.config.ts] 370 + import { defineConfig } from 'vitest/config' 371 + 372 + export default defineConfig({ 373 + test: { 374 + reporters: [ 375 + ['github-actions', { 376 + jobSummary: { 377 + enabled: false, // or set `outputPath` to customize where the summary is written 378 + }, 379 + }], 380 + ], 381 + }, 382 + }) 383 + ``` 384 + 385 + ## New `agent` Reporter to Reduce Token Usage 386 + 387 + As AI coding agents become a common way to run tests, Vitest 4.1 introduces the [`agent` reporter](/guide/reporters#agent-reporter) — a minimal output mode designed to reduce token usage. It only displays failed tests and their errors, suppressing passed test output and console logs from passing tests. 388 + 389 + Vitest automatically enables this reporter when it detects it's running inside an AI coding agent. The detection is powered by [`std-env`](https://github.com/unjs/std-env), which recognizes popular agent environments out of the box. You can also set the `AI_AGENT=copilot` (or any name) environment variable explicitly. No configuration needed — just run Vitest as usual: 390 + 391 + ```sh 392 + AI_AGENT=copilot vitest 393 + ``` 394 + 395 + If you configure custom reporters, the automatic detection is skipped, so add `'agent'` to the list manually if you want both. 396 + 397 + ## New `mockThrow` API 398 + 399 + Previously, making a mock throw required wrapping the error in a function: `mockImplementation(() => { throw new Error(...) })`. The new [`mockThrow`](/api/mock#mockthrow) and [`mockThrowOnce`](/api/mock#mockthrowonce) methods make this more concise and readable: 400 + 401 + ```ts 402 + const myMockFn = vi.fn() 403 + myMockFn.mockThrow(new Error('error message')) 404 + myMockFn() // throws Error<'error message'> 405 + ``` 406 + 407 + ## Strict Mode in WebdriverIO and Preview 408 + 409 + Locating elements is now strict by default in `webdriverio` and `preview`, matching Playwright behavior. 410 + 411 + If a locator resolves to multiple elements, Vitest throws a "strict mode violation" instead of silently picking one. This helps catch ambiguous queries early: 412 + 413 + ```ts 414 + const button = page.getByRole('button') 415 + 416 + await button.click() // throws if multiple buttons match 417 + await button.click({ strict: false }) // opt out and return first match 418 + ``` 419 + 420 + ## Chai-style Mocking Assertions 421 + 422 + Vitest already supports chai-style assertions like `eql`, `throw`, and `be`. This release extends that support to mock assertions, making it easier to migrate from Sinon-based test suites without rewriting every expectation: 423 + 424 + ```ts 425 + import { expect, vi } from 'vitest' 426 + 427 + const fn = vi.fn() 428 + 429 + fn('example') 430 + 431 + expect(fn).to.have.been.called // expect(fn).toHaveBeenCalled() 432 + expect(fn).to.have.been.calledWith('example') // expect(fn).toHaveBeenCalledWith('example') 433 + expect(fn).to.have.returned // expect(fn).toHaveReturned() 434 + expect(fn).to.have.callCount(1) // expect(fn).toHaveBeenCalledTimes(1) 435 + ``` 436 + 437 + ## Coverage `ignore start/stop` Ignore Hints 438 + 439 + You can now completely ignore specific lines from code coverage using `ignore start/stop` comments. 440 + In Vitest v3, this was supported by the `v8` provider, but not in v4.0 due to underlying dependency changes. 441 + 442 + Due to the community's request, we've now implemented it back ourselves and extended the support to both `v8` and `istanbul` providers. 443 + 444 + ```ts 445 + /* istanbul ignore start -- @preserve */ 446 + if (parameter) { // [!code error] 447 + console.log('Ignored') // [!code error] 448 + } // [!code error] 449 + else { // [!code error] 450 + console.log('Ignored') // [!code error] 451 + } // [!code error] 452 + /* istanbul ignore stop -- @preserve */ 453 + 454 + console.log('Included') 455 + 456 + /* v8 ignore start -- @preserve */ 457 + if (parameter) { // [!code error] 458 + console.log('Ignored') // [!code error] 459 + } // [!code error] 460 + else { // [!code error] 461 + console.log('Ignored') // [!code error] 462 + } // [!code error] 463 + /* v8 ignore stop -- @preserve */ 464 + 465 + console.log('Included') 466 + ``` 467 + 468 + See [Coverage | Ignoring Code](/guide/coverage.html#ignoring-code) for more examples. 469 + 470 + ## Coverage For Changed Files Only 471 + 472 + If you want to get code coverage only for the modified files, you can use [`coverage.changed`](/config/coverage.html#coverage-changed) to limit the file inclusion. 473 + 474 + Compared to the regular [`--changed`](/guide/cli.html#changed) flag, `--coverage.changed` allows you to still run all test files, but limit the coverage reporting only to the changed files. 475 + This allows you to exclude unchanged files from coverage that `--changed` would otherwise include. 476 + 477 + ## Coverage in HTML Reporter and Subpath Deployments 478 + 479 + Coverage HTML viewing now works reliably across UI mode, HTML reporter, and browser mode — including when deployed under a subpath. For custom coverage reporters, the new [`coverage.htmlDir`](/config/coverage#coverage-htmldir) option can be used to integrate their HTML output. 480 + 481 + ## Acknowledgments 482 + 483 + Vitest 4.1 is the result of countless hours by the [Vitest team](/team) and our contributors. We appreciate the individuals and companies sponsoring Vitest development. [Vladimir](https://github.com/sheremet-va) and [Hiroshi](https://github.com/hi-ogawa) are part of the [VoidZero](https://voidzero.dev) Team and are able to work on Vite and Vitest full-time, and [Ari](https://github.com/ariperkkio) can invest more time in Vitest thanks to support from [Chromatic](https://www.chromatic.com/). A big shout-out to [Zammad](https://zammad.com), and sponsors on [Vitest's GitHub Sponsors](https://github.com/sponsors/vitest-dev) and [Vitest's Open Collective](https://opencollective.com/vitest).

+1 -1

docs/config/detectasyncleaks.md

··· 19 19 For example if your code has `setTimeout` calls that execute the callback after tests have finished, you will see following error: 20 20 21 21 ```sh 22 - ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯ Async Leaks 1 ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯ 22 + ⎯⎯⎯⎯⎯⎯⎯⎯ Async Leaks 1 ⎯⎯⎯⎯⎯⎯⎯⎯ 23 23 24 24 Timeout leaking in test/checkout-screen.test.tsx 25 25 26|

docs/public/og-vitest-4-1.jpg