repository·main·Indexed 12 days ago
https://github.com/vitest-dev/vitestA Vite-native testing framework providing a fast, modern experience for unit, component, and browser testing with a Jest-compatible API. Version 5.0.0-rc.1 includes support for Hot Module Replacement (HMR), OpenTelemetry tracing, and specialized packages for browser providers (Playwright, WebdriverIO, Preview), snapshot testing, and Web Worker simulation.
Component testing focuses on verifying individual UI components in isolation. It sits between unit tests and end-to-end tests, providing faster feedback and easier debugging than E2E tests while offering more accurate environments than DOM simulations when used with Browser Mode.
Vitest supports multiple frameworks including Vue, React, Svelte, Lit, Preact, Qwik, Solid, Marko, and more.
When planning your test suite, prioritize coverage in this order:
Vitest includes a wide range of built-in features for modern web development:
expect compatibility.v8 or istanbul.JSDOM and happy-dom.expect-type for type-level testing.The @vitest/browser package is specifically designed for developers who want to create their own custom browser provider.
If your goal is simply to run your existing tests in a real browser environment, you should use one of the following pre-built packages instead:
@vitest/browser-playwright: Use this to run tests using Playwright.@vitest/browser-webdriverio: Use this to run tests using WebdriverIO.@vitest/browser-preview: Use this to visualize how your tests appear in a real browser.When using Vitest projects, configuration is resolved through a hierarchy of inputs.
The root configuration is resolved in this order (highest priority last):
viteOverrides (merged on top of the config file)options, applied on top of everything else)viteOverrides are merged, and then the project's own options are merged.extends: false: The inline project resolves only its own options.extends: './path': The referenced file is re-executed instead of the root config, and viteOverrides are not merged.The following options from viteOverrides are never inherited by projects:
plugins: Plugin instances in viteOverrides belong to the root server and cannot be shared.test.browser: Describes instances of a single project.test.tagsFilter: Applies to the whole run.name and projects.globalSetup (as it runs once per test run).Regardless of inheritance, these groups reach every project:
--testTimeout, --retry, --pool, etc.coverage, attachmentsDir, and mergeReportsLabel from the root's resolved config.The preview provider is designed for visual inspection of tests in a real browser, but it lacks the automation depth of providers like Playwright or WebdriverIO.
Key limitations include:
instances array must use a different browser type.userEvent API is a re-export from @testing-library/user-event and does not feature special integration with the browser instance.When using test.extend to add custom context, you can now reference lifecycle hooks like beforeEach and afterEach directly on the returned test object. These hooks are aware of the extended context provided by the extension.
import { test as baseTest } from 'vitest'
const test = baseTest.extend<{
todos: number[]
}>({
todos: async ({}, use) => {
await use([])
},
})
// These hooks are aware of the extended context
test.beforeEach(({ todos }) => {
todos.push(1)
})
test.afterEach(({ todos }) => {
console.log(todos)
})When using nested describe blocks, Vitest follows a hierarchical pattern where parent hooks wrap child hooks.
The pattern follows:
aroundAll wraps the entire suite (including children).aroundEach wraps child aroundEach hooks.beforeEach wraps child beforeEach hooks.afterEach hooks execute.afterAll and aroundAll cleanup occur.describe('outer', () => {
aroundAll(async (runSuite) => {
console.log('outer aroundAll before')
await runSuite()
console.log('outer aroundAll after')
})
beforeAll(() => console.log('outer beforeAll'))
aroundEach(async (runTest) => {
console.log('outer aroundEach before')
await runTest()
console.log('outer aroundEach after')
})
beforeEach(() => console.log('outer beforeEach'))
test('outer test', () => console.log('outer test'))
describe('inner', () => {
aroundAll(async (runSuite) => {
console.log('inner aroundAll before')
await runSuite()
console.log('inner aroundAll after')
})
beforeAll(() => console.log('inner beforeAll'))
aroundEach(async (runTest) => {
console.log('inner aroundEach before')
await runTest()
console.log('inner aroundEach after')
})
beforeEach(() => console.log('inner beforeEach'))
test('inner test', () => console.log('inner test'))
afterEach(() => console.log('inner afterEach'))
afterAll(() => console.log('inner afterAll'))
})
afterEach(() => console.log('outer afterEach'))
afterAll(() => console.log('outer afterAll'))
})Vitest runs tests within a 'pool'. A pool manages the execution environment and isolation for your tests. Vitest provides several built-in pool runners:
threads: Uses node:worker_threads for isolation via a new worker context.forks: Uses node:child_process for isolation via a new child_process.fork process.vmThreads: Uses node:worker_threads but provides isolation using the vm module instead of a new worker context.browser: Runs tests using browser providers.typescript: Runs typechecking on tests.Custom pools are an advanced, experimental, and low-level API primarily intended for library authors who need to control the lifecycle and communication of test workers.
Vitest imports the provider module on its first use and caches the default export for the entire lifetime of the worker.
Because there are no explicit setup or teardown hooks in the BenchmarkProvider API, any state that needs to persist across multiple benchmark runs should be stored directly on the provider object itself (worker-scoped state).
Both watchTriggerPatterns and forceRerunTriggers allow you to rerun tests when files outside the import graph change, but they behave differently:
watchTriggerPatterns: Reruns only the specific tests you map for a given pattern. This is more efficient and keeps the watch loop fast.forceRerunTriggers: Reruns every test in your project whenever any file matching the pattern changes.Use watchTriggerPatterns when you can precisely identify which tests depend on which files, and use forceRerunTriggers for broader, less specific dependencies.