{"id":15019,"library":"vitest-dev-server","title":"Vitest: Next-Generation Testing Framework","description":"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.","status":"active","version":"11.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/carbonate-dev/vitest-puppeteer","tags":["javascript","vitest","server","typescript"],"install":[{"cmd":"npm install vitest-dev-server","lang":"bash","label":"npm"},{"cmd":"yarn add vitest-dev-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add vitest-dev-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Vitest is powered by Vite and shares its configuration and transformation pipeline. Requires Vite >=v6.0.0.","package":"vite","optional":false},{"reason":"Optional UI for viewing and interacting with tests in a browser.","package":"@vitest/ui","optional":true},{"reason":"Required provider for running tests in a real browser environment using Playwright, especially for browser mode.","package":"@vitest/browser-playwright","optional":true},{"reason":"Needed if you rely on 'baseUrl' in your tsconfig.json, as Vite (and thus Vitest) does not respect it by default.","package":"vite-tsconfig-paths","optional":true}],"imports":[{"note":"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.","wrong":"import { defineConfig } from 'vite'","symbol":"defineConfig","correct":"import { defineConfig } from 'vitest/config'"},{"note":"Vitest is ESM-first. CommonJS `require` is generally not supported for its core APIs.","wrong":"const { test, expect } = require('vitest')","symbol":"test, expect, describe, it","correct":"import { test, expect, describe, it } from 'vitest'"},{"note":"The `vi` object provides Jest-compatible mocking utilities like `vi.mock`, `vi.spyOn`, and `vi.fn`.","symbol":"vi","correct":"import { vi } from 'vitest'"},{"note":"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.","symbol":"UserEvent","correct":"import userEvent from 'vitest/browser'"}],"quickstart":{"code":"import { defineConfig } from 'vitest/config';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n  plugins: [react()],\n  test: {\n    globals: true,\n    environment: 'jsdom',\n    setupFiles: './vitest.setup.ts',\n  },\n});\n\n// vitest.setup.ts\nimport '@testing-library/jest-dom';\n\n// src/sum.ts\nexport function sum(a: number, b: number): number {\n  return a + b;\n}\n\n// src/sum.test.ts\nimport { expect, test } from 'vitest';\nimport { sum } from './sum';\n\ndescribe('sum function', () => {\n  test('adds 1 + 2 to equal 3', () => {\n    expect(sum(1, 2)).toBe(3);\n  });\n\n  test('adds negative numbers correctly', () => {\n    expect(sum(-1, -2)).toBe(-3);\n  });\n\n  test('adds zero correctly', () => {\n    expect(sum(0, 5)).toBe(5);\n  });\n});\n\n// package.json script\n// {\n//   \"scripts\": {\n//     \"test\": \"vitest\"\n//   }\n// }","lang":"typescript","description":"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`."},"warnings":[{"fix":"Review the official migration guide for Vitest v4.0. Install required browser providers. Update import paths for browser-specific utilities.","message":"Vitest 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`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Consult the Vitest v3.0 migration guide for detailed changes and adjust coverage configurations and custom environment setups accordingly.","message":"Vitest 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`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Vitest (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.","severity":"gotcha","affected_versions":">=0.x"},{"fix":"Switch Vitest's `pool` configuration to `'forks'` or `'vmForks'` in `vitest.config.ts` to avoid this issue, e.g., `test: { pool: 'forks' }`.","message":"Using Node.js's `fetch` with `pool: 'threads'` can cause 'Failed to terminate worker' errors due to an ongoing issue.","severity":"gotcha","affected_versions":">=0.x"},{"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`.","message":"The `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.","severity":"deprecated","affected_versions":">=3.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify the import path. If using `baseUrl` in `tsconfig.json`, install `vite-tsconfig-paths` and add `tsconfigPaths()` to your Vite/Vitest plugins.","cause":"Incorrect file path or unresolved module alias from `tsconfig.json`.","error":"Cannot find module './relative-path' or 'my-aliased-module'"},{"fix":"Configure Vitest to use `pool: 'forks'` or `pool: 'vmForks'` in your `vitest.config.ts` file.","cause":"Occurs when Node.js's `fetch` is used with Vitest's `pool: 'threads'` due to an underlying issue.","error":"Failed to terminate worker"},{"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.","cause":"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.","error":"Cannot mock \"./mocked-file.js\" because it is already loaded."},{"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`.","cause":"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.","error":"SyntaxError: Named export 'X' not found. The requested module 'Y' is a CommonJS module, which may not support all module.exports as named exports."},{"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.","cause":"Attempting to use `require()` within a test file or configuration that is treated as an ES module.","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm"}