Registry / testing / vitest-dev-server

vitest-dev-server

library11.0.3jsnpmunverified

Vitest is a blazing-fast unit testing framework powered by Vite, designed to integrate seamlessly with Vite-based projects. It leverages Vite's dev server internally to transform files during testing, ensuring consistent configuration and performance between development and test environments. Vitest is Jest-compatible, offering a familiar API for assertions (like `expect`) and mocking, alongside out-of-the-box support for ESM, TypeScript, and JSX. The current stable version is 4.1.4, with major releases occurring roughly annually (e.g., v3 in Jan 2025, v4 in Oct 2025) and frequent minor/patch updates. Its key differentiators include shared configuration with Vite, Hot Module Replacement (HMR) for tests, multithreading workers, and a comprehensive ecosystem for component testing across various frameworks like Vue, React, and Svelte. It aims to eliminate the configuration overhead often associated with using other test runners in Vite projects.

testing

npm install vitest-dev-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITEST-DEV-SERVER

vitest-dev-server

testingjavascriptv11.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig

✓ import { defineConfig } from 'vitest/config'

✗ import { defineConfig } from 'vite'

While Vitest reads Vite's config, for Vitest-specific options, `defineConfig` should be imported from `vitest/config` or referenced directly if not using a dedicated `vitest.config.*` file.

test, expect, describe, it

✓ import { test, expect, describe, it } from 'vitest'

✗ const { test, expect } = require('vitest')

Vitest is ESM-first. CommonJS `require` is generally not supported for its core APIs.

✓ import { vi } from 'vitest'

The `vi` object provides Jest-compatible mocking utilities like `vi.mock`, `vi.spyOn`, and `vi.fn`.

UserEvent

✓ import userEvent from 'vitest/browser'

For interactive DOM events in browser-based tests (Vitest v4.0+), `userEvent` is imported from `vitest/browser`. Previously, it might have been from `@vitest/browser/context` but that path is deprecated.

This quickstart demonstrates setting up Vitest for a React project with `jsdom` environment, a setup file, and basic unit tests for a utility function. It shows `defineConfig` for Vitest, a simple `sum` function, and its corresponding test file using `test`, `expect`, and `describe`.

import { defineConfig } from 'vitest/config'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], test: { globals: true, environment: 'jsdom', setupFiles: './vitest.setup.ts', }, }); // vitest.setup.ts import '@testing-library/jest-dom'; // src/sum.ts export function sum(a: number, b: number): number { return a + b; } // src/sum.test.ts import { expect, test } from 'vitest'; import { sum } from './sum'; describe('sum function', () => { test('adds 1 + 2 to equal 3', () => { expect(sum(1, 2)).toBe(3); }); test('adds negative numbers correctly', () => { expect(sum(-1, -2)).toBe(-3); }); test('adds zero correctly', () => { expect(sum(0, 5)).toBe(5); }); }); // package.json script // { // "scripts": { // "test": "vitest" // } // }

vitest --version

Debug

Known issues

breakingVitest v4.0 introduced several breaking changes, notably stabilizing Browser Mode which now requires installing separate provider packages (e.g., `@vitest/browser-playwright`). The `context` import location also changed from `@vitest/browser/context` to `vitest/browser`.

fix

Review the official migration guide for Vitest v4.0. Install required browser providers. Update import paths for browser-specific utilities.

affects: >=4.0.0

breakingVitest v3.0 included breaking changes related to V8 code coverage remapping logic, leading to expected changes in coverage reports. The `vitest/execute` entry point was removed, and custom environments no longer use `transformMode` but `viteEnvironment`.

fix

Consult the Vitest v3.0 migration guide for detailed changes and adjust coverage configurations and custom environment setups accordingly.

affects: >=3.0.0

gotchaVitest (via Vite) does not automatically respect `baseUrl` or path aliases defined in `tsconfig.json` by default. This can lead to 'Cannot find module' errors for aliased imports.

fix

Install and configure `vite-tsconfig-paths` as a Vite plugin in your `vite.config.ts` (or `vitest.config.ts`) to resolve `tsconfig.json` paths.

affects: >=0.x

gotchaUsing Node.js's `fetch` with `pool: 'threads'` can cause 'Failed to terminate worker' errors due to an ongoing issue.

fix

Switch Vitest's `pool` configuration to `'forks'` or `'vmForks'` in `vitest.config.ts` to avoid this issue, e.g., `test: { pool: 'forks' }`.

affects: >=0.x

deprecatedThe `server` configuration option in `vitest.config.ts` was previously used to define the configuration for the `vite-node` server. While still present, it now primarily manages inlining/externalization mechanisms. `vite-node` itself is no longer a direct dependency, having been replaced by Vitest's internal Module Runner.

fix

Review your `server` configuration. For general Vite server options, ensure they are at the top level of your `vite.config.ts` (if sharing config), not nested under `test.server` unless specifically for `deps.inline` or `deps.external`.

affects: >=3.0.0

gotchaWhen importing CommonJS modules that do not explicitly define named exports, Vitest (and Node.js in ESM context) may throw `SyntaxError: Named export 'X' not found`. This happens because dynamic analysis of CommonJS named exports is not always reliable.

fix

Use the default export for such modules (`import pkg from 'some-cjs-pkg'`) or enable `deps.interopDefault: true` in your Vitest config, though this is a heuristic. For better compatibility, ensure dependencies are properly ESM-compatible or use patching if necessary.

affects: >=0.x

Errors

Common errors & fixes

Cannot find module './relative-path' or 'my-aliased-module'

Incorrect file path or unresolved module alias from `tsconfig.json`.

fix

Verify the import path. If using `baseUrl` in `tsconfig.json`, install `vite-tsconfig-paths` and add `tsconfigPaths()` to your Vite/Vitest plugins.

Failed to terminate worker

Occurs when Node.js's `fetch` is used with Vitest's `pool: 'threads'` due to an underlying issue.

fix

Configure Vitest to use `pool: 'forks'` or `pool: 'vmForks'` in your `vitest.config.ts` file.

Cannot mock "./mocked-file.js" because it is already loaded.

Attempting to mock a module that has already been loaded by Vitest, often due to `vi.mock` being hoisted or the module being imported in a setup file before mocking.

fix

Ensure `vi.mock` calls are at the top level of the test file before any imports of the module to be mocked. If the module is loaded in a setup file, consider using `vi.resetModules()` after the initial load or refactor to avoid early loading in the test context.

SyntaxError: Named export 'X' not found. The requested module 'Y' is a CommonJS module, which may not support all module.exports as named exports.

An ESM `import { X } from 'Y'` statement is trying to import a named export `X` from a CommonJS module `Y` that doesn't properly expose it for static analysis.

fix

Try importing the default export (`import Y from 'Y'`) and access `X` as a property (`Y.X`), or configure `deps.interopDefault: true` in `vitest.config.ts`.

ReferenceError: require is not defined in ES module scope

Attempting to use `require()` within a test file or configuration that is treated as an ES module.

fix

Convert `require()` calls to ES module `import` statements or dynamic `import()`. Ensure your `package.json` either has `"type": "module"` or uses `.mjs` / `.mts` file extensions for ESM files.

Upgrade

Version history

11.0.3latest on npm

Audit

Dependencies

viterequiredVitest is powered by Vite and shares its configuration and transformation pipeline. Requires Vite >=v6.0.0.

@vitest/uioptionalOptional UI for viewing and interacting with tests in a browser.

@vitest/browser-playwrightoptionalRequired provider for running tests in a real browser environment using Playwright, especially for browser mode.

vite-tsconfig-pathsoptionalNeeded if you rely on 'baseUrl' in your tsconfig.json, as Vite (and thus Vitest) does not respect it by default.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/carbonate-dev/vitest-puppeteer ↗

packagehttps://www.npmjs.com/package/vitest-dev-server ↗

homepagehttps://vitest.dev ↗