Vitest 3.2 is out!
June 2, 2025
Vitest 3.2 focuses on improvements to Browser Mode and TypeScript support. This release also includes some new useful methods, config options and deprecates the workspace
config in favour of projects
.
workspace
is Deprecated
In an effort to simplify the configuration, the team decided to deprecate the separate vitest.workspace
file and recommend using only the projects
option in the root config. This also simplifies how the global options are configured (because you don't need to guess how to add reporters when you have no root config).
We also decided to deprecate the workspace
name because it clashes with other tools like PNPM that provide monorepo support via this option. Vitest doesn't run these projects with separate CWD
and treats them more like sub-Vitests. It also gives us more space to come up with a better solution for monorepos without breaking others.
This option will be removed completely in a future major, replaced by projects
. Until then, Vitest will print a warning if workspace feature is used.
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
// "test.workspace" is now "test.projects"
workspace: [
projects: [
{ test: { name: "Unit" } },
{ test: { name: "Integration" } },
],
},
});
Annotation API
The new annotation API allows you to annotate any test with a custom message and attachment. These annotations are visible in the UI, HTML, junit, tap and GitHub Actions reporters. Vitest will also print related annotation in the CLI if the test fails.

Scoped Fixtures
The test.extend
fixtures can now specify the scope
option: either file
or worker
.
const test = baseTest.extend({
db: [
async ({}, use) => {
// ...setup
await use(db)
await db.close()
},
{ scope: 'worker' },
],
})
The file fixture is similar to using beforeAll
and afterAll
at the top level of the file, but it won't be called if the fixture is not used in any test.
The worker
fixture is initiated once per worker, but note that by default Vitest creates one worker for every test, so you need to disable isolation to benefit from it.
Custom Project Name Colors
You can now set a custom color when using projects
:
Config Example
export default defineConfig({
test: {
projects: [
{
test: {
name: {
label: 'unit',
color: 'red',
},
},
},
{
test: {
name: {
label: 'browser',
color: 'green',
},
browser: {
enabled: true,
provider: 'playwright',
instances: [{ browser: 'chromium' }],
},
},
},
],
},
})

Custom Browser Locators API
Built-in locators might not be enough to express your application’s needs. Instead of falling back to CSS and losing the retry-ability protection that Vitest provides through its locator API, we now recommend extending locators using the new locators.extend
API.
import { locators } from '@vitest/browser/context'
locators.extend({
getByCommentsCount(count: number) {
return `.comments :text("${count} comments")`
},
})
Return a Playwright locator string to construct a new locator. Note that string returned from this method will be scoped to the parent locator, if there is one.
Now you can call getByCommentsCount
on the page
or any other locator directly:
await expect.element(page.getByCommentsCount(1)).toBeVisible()
await expect.element(
page.getByRole('article', { name: 'Hello World' })
.getByCommentsCount(1)
).toBeVisible()
If this method returns a string, then the return value will be converted into a locator, so you can keep chaining it:
page.getByRole('article', { name: 'Hello World' })
.getByCommentsCount(1)
.getByText('comments')
This method has access to the current locator context, if there is one (if method is called on the page
, then context will refer to page
), so you can chain all locator methods inside:
import { locators } from '@vitest/browser/context'
import type { Locator } from '@vitest/browser/context'
locators.extend({
getByCommentsCount(this: Locator, count: number) {
return this.getByRole('comment')
.and(this.getByText(`${count} comments`))
},
})
Having access to context also allows you to call regular methods of the locator to define a custom user event:
import { locators, page } from '@vitest/browser/context'
import type { Locator } from '@vitest/browser/context'
locators.extend({
clickAndFill(this: Locator, text: string) {
await this.click()
await this.fill(text)
},
})
await page.getByRole('textbox').clickAndFill('Hello World')
Please, refer to the locators.extend
API for more information.
Explicit Resource Management in vi.spyOn
and vi.fn
In environments that support Explicit Resource Management, you can use using
instead of const
to automatically call mockRestore
on any mocked function when the containing block is exited. This is especially useful for spied methods:
it('calls console.log', () => {
using spy = vi.spyOn(console, 'log').mockImplementation(() => {})
debug('message')
expect(spy).toHaveBeenCalled()
})
// console.log is restored here
Test signal
API
Vitest now provides an AbortSignal
object to the test body. You can use it to stop any resource that supports this Web API.
The signal is aborted when test times out, another test fails and --bail
flag is set to a non-zero value, or the user presses Ctrl+C in the terminal.
For example, you can stop a fetch
request when tests are interrupted:
it('stop request when test times out', async ({ signal }) => {
await fetch('/heavy-resource', { signal })
}, 2000)
Coverage V8 AST-aware remapping
Vitest now uses ast-v8-to-istanbul
package developed by one of the Vitest maintainers, AriPerkkio. This brings v8 coverage report in line with istanbul, but has a better performance! Enable this feature by setting coverage.experimentalAstAwareRemapping
to true
.
We are planning to make this the default remapping mode in the next major. The old v8-to-istanbul
will be removed completely. Feel free to join discussion at https://github.com/vitest-dev/vitest/issues/7928.
watchTriggerPatterns
Option
When you edit a file, Vitest is smart enough to rerun only tests that import this file. Unfortunately, Vitest static analysis respects only static and dynamic import
statement. If you are reading a file or starting a separate process, Vitest will ignore changes to related files.
With watchTriggerPatterns
option you can configure which tests to rerun depending on the file that was changed. For example, to always rerun mailers
tests when a template is changed, add a trigger pattern:
export default defineConfig({
test: {
watchTriggerPatterns: [
{
pattern: /^src\/templates\/(.*)\.(ts|html|txt)$/,
testsToRun: (file, match) => {
return `api/tests/mailers/${match[2]}.test.ts`
},
},
],
},
})
The New Multi-Purpose Matchers
Type
Vitest now has a Matchers
type that you can extend to add type support for all your custom matchers in one place. This type affects all these use cases:
expect().to*
expect.to*
expect.extend({ to* })
For example, to have a type-safe toBeFoo
matcher, you can write something like this:
import { expect } from 'vitest'
interface CustomMatchers<R = unknown> {
toBeFoo: (arg: string) => R
}
declare module 'vitest' {
interface Matchers<T = any> extends CustomMatchers<T> {}
}
expect.extend({
toBeFoo(actual, arg) {
// ... implementation
return {
pass: true,
message: () => '',
}
}
})
expect('foo').toBeFoo('foo')
expect.toBeFoo('foo')
sequence.groupOrder
The new sequence.groupOrder
option controls the order in which the project runs its tests when using multiple projects.
- Projects with the same group order number will run together, and groups are run from lowest to highest.
- If you don’t set this option, all projects run in parallel.
- If several projects use the same group order, they will run at the same time.
Example
Consider this example:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
projects: [
{
test: {
name: 'slow',
sequence: {
groupOrder: 0,
},
},
},
{
test: {
name: 'fast',
sequence: {
groupOrder: 0,
},
},
},
{
test: {
name: 'flaky',
sequence: {
groupOrder: 1,
},
},
},
],
},
})
Tests in these projects will run in this order:
0. slow |
|> running together
0. fast |
1. flaky |> runs after slow and fast alone
The complete list of changes is at the Vitest 3.2 Changelog.