@vitest/expect

Vitest 5 is officially out! This release focuses on performance and brings a lot of new features while fixing long-standing bugs. See our blog post for the official announcement.

Breaking Changes

• breaking

  Replace loupe.inspect with pretty-format

• breaking

  Remove quotes from string values in test.for/each title $ variable (take 2)

• breaking

  Default attachmentsDir from .vitest-attachements/ to .vitest/attachments/

• breaking

  Remove sequential test/suite options in favor of concurrent

• breaking

  Represent locator as an object instead of a string

• breaking

  Inline expect package

• breaking

  Remove deprecated entry points

• breaking

  Require Node.js 22 and Vite 6.4

• breaking

  Fail expect.poll when function didn't resolve in time

• breaking

  Throw an error if hoistable methods are outside the top level scope

• breaking

  toHaveTextContent is strict, add toMatchTextContent as alternative

• breaking

  Don't lookup config file from ancestor directories

• breaking

  Inline @vitest/runner package, do not publish it anymore

• breaking

  Allow mutating happy-dom/jsdom window object

• breaking

  Expose concurrencyId/workerId on TestModule's diagnostics, make id 1-based

• breaking

  Add screenshotDirectory config to browser.expect.toMatchScreenshot

• breaking

  Update @sinonjs/fake-timers and support mocking Temporal

• breaking

  Remove webdriverio package

• breaking

  Clear mocks by default before each test

• breaking

  Don't emit localStorage warnings on Node 26, fail gracefully when worker fails to start

• breaking

  Separate config resolution from the server creation

• breaking

  Inline projects extend the root config by default

• breaking

  Enable mocking Temporal without fake timers

• breaking

  Support nested projects

• breaking

  Use > as separator in -t, calculate only once

• breaking

  Fail the test when an asynchronous assertion is not awaited

• breaking

  Share the Vite server between inline projects

• breaking

  Parse files statically in vitest list by default

• breaking

  benchmark: Rewrite the public API

• breaking

  browser: Iframe scale

• breaking

  browser: Enable locators.exact by default

• breaking

  browser: Require sessionId for orchestrator html request

• breaking

  browser: Save failure screenshots in attachmentsDir

• breaking

  coverage: include/exclude globs too eager

• breaking

  coverage: Allow thresholds.perFile to accept an object

• breaking

  expect: Fix toThrow("") behavior by reverting #6710

• breaking

  mocker: Deserialize automock as automock

• breaking

  reporters: blob reporter and --merge-reports default to .vitest/blob/

• breaking

  reporters: Write json and junit reporter output files to .vitest by default

• breaking

  spy: Preserve class mock prototype methods on instances

• breaking

  types: Add better promise support in expects and matchers

• breaking

  ui: Harden UI API access

• breaking

  ui: Change html reporter default output to .vitest

Features

• Add createReport and .vitest report directory convention

• Expose default reporters through configDefaults.reporters

• Support merge reports for non-sharded multi-environment runs (take 2)

• Add logger.formatError

• Support typescript build mode

• Add toggable injectCjsGlobals option

• Promote fsModuleCache to a top-level option

• Support non-ascii characters in for/each title placeholders

• Report the duration breakdown as percentages

• Promote parseSpecifications out of experimental

• Promote clearCache out of experimental

• api: Expose logs recorded during the test

• benchmark: Add pluggable benchmark provider API

• browser: Export aria tree utils

• browser: Support dom snapshot trace view

• browser: Provide project reference in ToMatchScreenshotResolvePath

• browser: Show aria tree on locator element error

• browser: Support custom kind in page.mark

• browser: Live update trace view on watch UI

• browser: Add context.mark for custom command tracing

• browser: Show trace view steps in editor panel

• browser: Display nested mark trace in UI

• cli: Add --repeats CLI option

• cli: Support -p shorthand for --project

• coverage: V8 to track node:child_process and node:worker_threads contexts

• coverage: thresholds.autoUpdate to receive previous threshold as argument

• coverage: Switch to @vitest/istanbuljs packages

• junit-reporter: Add jest-junit-compatible naming options

• reporter: Support html reporter single file output

• reporter: Add custom GitHub Actions summary title

• ui: Highlight editor source locations

• ui: Navigate trace steps with keyboard and remove indirect editor focus

• ui: Persist trace view selection in URL

• ui: Toggle trace target highlight

• ui: Add link to open playwright trace

• vitest: Create vi.when()

• vm: Support require(esm) in vm pools

Bug Fixes

• Global sequence.concurrent: true with top-level test(..., { concurrent: false }) + depreacte sequential test API and options

• Test tags options should overwrite inherited suite options + inherit suite options in task API

• Udpate optimize deps config

• Shell injection safety via github.ref_name in publish workflow

• Make attachmentsDir root only config

• Apply cjs interop for truthy __esModule

• Preserve vi.defineHelper callsite for async error stack

• Respect disableConsoleIntercept in browser mode

• ForceRerunTriggers uses directory globs against files

• Unify typechecking and ast collection

• Don't print typecheck warning more than once

• Correct collumn when parsing tests

• Fix mixed stdout/stderr log timestamps in onUserConsoleLog

• Fix importOriginal with optimizer and query import

• Correct transform time calculation in merged report

• Fix setImmediate await in detect-async-leak

• Fix per-project sequence config

• Add handshake timeout to iframe communication

• Don't print column in test names when includeTaskLocation is enabled

• Disable server HMR before plugins read it in their config hook

• Close the pool before the Vite servers

• Remove listeners in the typecheck worker's off

• Keep per-file isolation in vm pools when maxWorkers is 1

• Node.js 20 deprecation warning for ci.yml

• Prevent node builtins double prefix

• Set non-zero exit code when teardown throws during close

• Don't race the typechecker spawn grace period on windows

• Coalesce concurrent watch-mode restarts, deflake the pool stderr fixture

• Prevent vitest --typecheck from reporting a false success when the tsc process crashes

• Collect in-source tests when the module is cached

• Swap replace() arguments so timeout error stack shows the real message

• Stale mock metadata breaks automocking with isolate:false

• Don't lose worker output on teardown, deflake timing-sensitive tests

• Revive global concurrency limit for test lifecycle

• Own the post-restart rerun, keep process.exit disabled in workers

• Preserve correct root during resolve config

• Combine multiple --project filters correctly

• Fix recordArtifact location with vi.defineHelper

• Invalidate resolved setup files

• Accept awaited value in vi.when thenResolve

• Ignore computed member calls in static collection

• Don't duplicte oxc.target if user provides a custom array

• Propagate --maxWorkers to projects

• Apply queued mocks from doMock() in queue order

• Add a warning if inline project has duplicate plugins due to unexpected extends: true

• Treat test.describe as a suite during static collection

• browser: Fix trace highlight of shadow dom on webdriverio

• browser: Simplify orchestrator otel carrier

• browser: Remove orphaned Playwright route when same module is mocked via multiple ids

• browser: Skip wrapDynamicImport transform on ssr environment

• browser: Fix stale source map on watch mode

• browser: Escape inline orchestrator scripts

• browser: Disable client cdp API when allowWrite/allowExec: false

• browser: Wait for orchestrator readiness before resolving browser sessions

• browser: Wait for iframe tester readiness before preparing

• browser: Encode iframeId in tester iframe URL

• browser: Always derive a positive locator action timeout

• browser: Resize the browser ui only if it's not headless

• browser: Check fs access in builtin commands

• browser: Preserve pre-transform request defaults

• browser: Fix error stacktrace location off-by-one

• browser: Inlined awaited import should not trigger syntax error after transform

• browser: Mock window.print to avoid hanging

• browser: Ignore channel events in a tester opened as a top-level window

• browser: Resolve connectTimeout from the project config

• browser: Prebundle vite module runner with vitest

• browser: Restore dependency reload warning

• browser: Configure internal optimizer dependencies

• browser: Trigger playwright/chromium gc on lower disk availability

• browser: Disallow filter-only options in getBy* locators - by Arjun in #10295 and #10933

• browser: Fail instead of hanging when the browser stops responding

• browser: Exit gracefully when the browser disconnects during cancellation

• browser: Don't redirect vitest in client environment

• browser: Don't hang when ui: true in projects

• browser: Preserve trace popover state

• browser: Report the action error when a task times out

• cache: Improve fsModuleCache resiliency during external modifications

• cli: Respect FORCE_COLOR over agent detection

• cli: Exit on CTRL+c even when globalSetup runs blocked code

• coverage: exclude to not inherit negation globs from test.include

• coverage: Avoid matching sibling project roots

• coverage: Non-awaited module imports cause wrong offsets

• coverage: Fail fast when coverage.reportsDirectory conflicts between concurrent runs

• coverage: V8 to ignore Vite SSR's generated import bindings

• coverage: Prevent crash on /@fs/ prepended virtual files

• deps: Update ivya to fix empty aria tree snapshot

• deps: Update fake-timers to 15.3.2. support toNotFake

• deps: Update all non-major dependencies

• deps: Update all non-major dependencies

• deps: Update all non-major dependencies

• deps: Update all non-major dependencies - in #10966

• deps: Update all non-major dependencies - in #11043

• expect: Allow readonly arrays and sets in toBeOneOf

• expect: Handle nullish toHaveProperty values

• junit: Include unhandled errors in JUnit XML report

• mocker: Skip hoist transform without ast mock calls

• mocker: Hoist vi.mock() for vite-plus/test imports

• mocker: Restrict redirect mocks to the fs allowlist

• pool: Prevent test run hang on worker crash

• pool: Improve error message when worker exits unexpectedly

• pool: Vm pools to respect cgroupsv2 memory limit

• pool: Worker init to handle queued synchronous messages

• pool: Report the worker exit instead of a pipe error that raced it

• reporter: Guard against non-finite slowTestThreshold in summary reporter

• reporter: Fix non-existing import subpath module blob serialization

• reporters: Fix blob file name with label

• reporters: summary to intercept logger's streams even when they are not process.std* streams

• reporters: Fix missing testModules in onTestRunEnd when merging blobs from different root directory test runs

• reporters: Print parent describe suites when the passed-test list is hidden

• reporters: Display test.name in GitHub Actions reporter summary header

• runner: Propagate chainable flags in describe.for

• runner: Limit concurrency per task branch in addition to per leaf callbacks

• runner: Remove AbortSignal listener leak in withCancel

• runner: Don't fail collection when accessing error.stack throws

• snapshot: Fail test when snapshot assertion is used with test.fails

• snapshot: Treat empty string as valid snapshot

• snapshot: Support no-unsafe-eval CSP by evaluating snapshot files on server

• snapshot: Reject when toMatchFileSnapshot uses same snapshot file as toMatchSnapshot

• spy: Support private method spy types

• spy: Point ESM namespace spy error to module mocking docs

• typecheck: Report a checker crash on Windows instead of a spawn failure

• types: Allow changed in configuration options

• ui: Fix duplicate colored error message

• ui: Fix missing source code in html reporter metadata when merging blobs with different root directory test runs

• ui: Fix module graph in browser mode with --ui

• ui: Render ANSI color codes in editor panel inline error widget

• ui: Fix code editor error and annotations gadgets layout shifts

• ui: Synchronize watch-run UI state on file removal

• ui: Require auth for coverage report and all UI subtree requests

• ui: Improve suite interaction and layout in explorer tree

• ui: Reveal explorer virtual scroller on resize

• ui: Persist trace step-iframe split pane sizes

• ui: Add suite level report view

• ui: Hide running count in static reports

• utils: Don't crash on a malformed inline source map

• vitest: Strip non-serializable functions from inline diff config

• removed

  vitest: Remove broken "./src/*" export from package.json

• vitest: Render non-Error causes from env setup so the actual diagnostic is not dropped

• vm: Fix external module resolve error with deps optimizer query for encoded URI

• vm: Stop retaining every finished test file in vm pool workers

• vm: Fall back to compiling from source when a module's code cache is rejected

• vm: Link module graphs one at a time

• webdriverio: Allow gpu in headless chrome

• worker: Bind stdio's early in case overriden

Performance

• Stringify diff objects only once

• Improve performance in hot paths

• Serve warm modules to workers in one round-trip, enable the node compile cache

• Make the Node compile cache opt-in, persist worker caches on teardown

• Reuse compiled code across vm pool contexts and prewarm the module graph

• Bundle vitest's own dependencies

• Lowers peak memory usage when using --changed on a large graph

• Initialize trace view in the orchestrator once per worker

• browser: Reduce matching screenshot overhead

• browser: Open browser sessions adaptively instead of maxWorkers upfront

• browser: Cut per-file round trips

• browser: Stop serving framework sourcemaps in headless runs

• browser: Prewarm the browser while the Vite server starts

• browser: Pre-bundle the vitest runtime in optimizeDeps

• browser: Serve framework assets as immutable

• cache: Hash the environment-invariant part of the fs module cache key once

• coverage: Speed up v8 report generation (bounded-memory merge + precompiled globs)

• coverage: Reduce RPC data and unnecessary serializations

• expect: Avoid redefining matcher state

• expect: Lazily format spy matcher failures

• spy: Avoid scanning cleared mocks

• vm: Don't prewarm modules the worker never requests

• vm: Let environments opt out of the module graph prewarm