Vitest · Config reference · all subjects

api and configuration

6 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

New API methods in Vitest 4

Vitest 4 adds new advanced public API methods: experimental_parseSpecifications (parse test files without running), watcher (expose methods for custom watchers), enableCoverage and disableCoverage (dynamically control coverage), getSeed (returns seed value if tests run at random), getGlobalTestNamePattern (returns current test name pattern), and waitForTestRunEnd (returns promise when tests finish).

vi.defineHelper wraps functions to fix stack traces in assertion helpers

vi.defineHelper wraps a function so Vitest strips its internals from the stack trace and points the error back at the call site instead of the line inside the helper. This solves the problem where assertion failures inside a helper would point at the line inside the helper rather than the test that called it.

vi.defineHelper available since version 4.1.0

The vi.defineHelper function was introduced in Vitest version 4.1.0.

vi.defineHelper example with single assertion

import { expect, test, vi } from 'vitest' const assertPair = vi.defineHelper((a: unknown, b: unknown) => { expect(a).toEqual(b) // ❌ failure does NOT point here }) test('example', () => { assertPair('left', 'right') // ✅ failure points here }) This example shows that when assertPair fails, the diff and stack frame point to the test line that called it, matching the behaviour of built-in matchers.

vi.defineHelper example with multiple assertions

import { expect, test, vi } from 'vitest' const expectValidUser = vi.defineHelper((user: unknown) => { expect(user).toHaveProperty('id') expect(user).toHaveProperty('email') expect(user.email).toMatch(/@/) }) test('returns a valid user', async () => { const user = await fetchUser('alice') expectValidUser(user) }) This example shows vi.defineHelper working with helpers that bundle several assertions. A failure in any of the inner expect calls is reported against the expectValidUser(user) line in the test.

Use vi.defineHelper for reusable checks with multiple expect calls

Use vi.defineHelper whenever a reusable check calls expect more than once, whether that is a domain-specific helper like expectValidJWT or any block of expect calls that would otherwise be inlined into every test.

Give your agent this brain