What is Vitest, and why does a project already built with Vite usually choose it as its test runner?
answer
- same pipeline as the app
- config read from vite.config
- TypeScript and ESM with no transformer
- Jest-shaped API, imported explicitly
- watch mode follows the module graph
basics
~20 sVitest is a Vite-powered test runner: it reuses the app's vite.config and plugins, runs ESM and TypeScript without a separate transformer, offers a Jest-compatible API through vi and expect, and re-runs only affected tests in watch mode.
solid answer
~40 sVitest is a test runner built on Vite. It reads the project's `vite.config` (or a `vitest.config.ts`, which takes priority), so tests get the same plugins, `resolve.alias` entries and `define` values as the app, and there is no second transform pipeline to keep in sync. ESM, TypeScript and JSX run as written because Vite strips the types on the way in, which also means a type error does not fail a normal run. The API mirrors Jest's: `describe`, `test` and `expect`, with `vi.fn`, `vi.spyOn` and `vi.mock` in place of the `jest` object. But `globals` is off by default, so you import them from `vitest`. Plain `vitest` starts watch mode in an interactive terminal and re-runs only the tests whose module graph includes the changed file; `vitest run` does one pass for CI.
code
typescript · 13 lines/// <reference types="vitest/config" />
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
export default defineConfig({
resolve: {
alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
},
test: {
environment: 'node',
include: ['src/**/*.test.ts'],
},
})go deeper
Recall what Vitest borrows from Vite: the config, the plugins and the transform. Name the jest-to-vi renames and remember that test APIs are imported from vitest unless globals is on.
Explain the config lookup order, why a vitest.config.ts replaces rather than extends vite.config.ts, and how watch mode uses the module graph to choose which tests to re-run.
Show what the shared pipeline does not give you: no type checking in a normal run, DOM environments installed separately, and vitest run needed in CI scripts and commit hooks so they exit.
Frame the fit: a shared transform pipeline removes a whole class of config drift for a Vite app, while a project that does not build with Vite gains less and still pays for the API differences.
## What Vitest is **Vitest** is a JavaScript and TypeScript test runner that uses **Vite** to load, resolve and transform the files it tests. Vite is the build tool and dev server many front-end and full-stack projects already use, and Vitest plugs into the same machinery instead of bringing its own. The practical result is that a test sees the code the way the app's dev server does. Vitest is also meant to work for projects that do not build with Vite, but the strongest case for it is a project that already does. ## One pipeline instead of two A test runner has to turn source files into something it can execute: resolve import paths, apply aliases, compile TypeScript or JSX, and handle CSS and asset imports. A runner with its own pipeline needs all of that configured a second time, and the two configurations drift apart as the build changes. Vitest avoids the duplication: - It reads `vite.config.*` and applies its `plugins`, `resolve.alias` and `define` settings to tests too. - Runner options live in a `test` block in that same file. Add `/// <reference types="vitest/config" />` at the top so TypeScript knows the block. - A separate `vitest.config.*` is optional. When one exists, Vitest looks for it **first**, and it **overrides** `vite.config.*` entirely: options in the Vite file are ignored, not merged. `mergeConfig` from `vitest/config` combines the two when you want both. - Vitest sets the config `mode` to `test` and exposes `process.env.VITEST`, so a single config file can branch for tests. ## ESM and TypeScript without a transform step Test files go through Vite's transform, so native ES modules, TypeScript and JSX run as written, with no separate compiler to install or keep in step. Two consequences matter in practice: 1. TypeScript types are **removed, not checked**. A test file with a type error still runs and can pass. Type checking stays a separate step: the compiler in CI, or Vitest's opt-in `typecheck` mode, which runs the TypeScript compiler over type-test files such as `*.test-d.ts`. 2. Module mocking with `vi.mock` applies to `import` statements. A module loaded with `require()` cannot be replaced this way. ## A Jest-shaped API, imported explicitly Vitest reimplements most of Jest's surface, so a test looks familiar. The helpers that Jest hangs on its `jest` object live on `vi`: | Jest | Vitest | |---|---| | `jest.fn()` | `vi.fn()` | | `jest.spyOn()` | `vi.spyOn()` | | `jest.mock()` | `vi.mock()` | | `jest.requireActual()` | `await vi.importActual()` | | `jest.setTimeout(5000)` | `vi.setConfig({ testTimeout: 5000 })` | The most visible difference is that **`globals` defaults to `false`**: `describe`, `test`, `expect` and `vi` are imported from `vitest` in every file. Setting `test.globals: true`, plus `vitest/globals` in the tsconfig `types` list, brings back Jest-style globals. Similar names do not guarantee identical behaviour: module-mock factories, `mockReset` and the default mock cleanup all differ, which is why a port takes more than a find-and-replace. ## Watch mode and run mode Running plain `vitest` picks a mode for you: 1. In an interactive terminal outside CI it starts **watch mode**. When a source or test file changes, Vitest searches the module graph and re-runs only the tests that import it, much as Vite's hot module replacement updates only what changed. 2. In CI, or when stdin is not a terminal, it falls back to a single run, the same as `vitest run`. 3. A change to a file matched by `forceRerunTriggers` (by default any `package.json` and the Vitest and Vite config files) re-runs the whole suite, because the module graph cannot say what such a file affects. Scripts called from a pre-commit hook should use `vitest run`, or `vitest related --run` for the staged files, so the command exits instead of waiting for changes. Watch mode is where the shared pipeline pays off day to day: a saved file re-runs a handful of tests rather than the whole suite, so feedback stays fast as the suite grows. ## What it does not decide for you - The default `environment` is `node`. Code that touches `document` or `window` needs `jsdom` or `happy-dom`, and each of those is a separate dev dependency. - Vitest is the runner. What a good test asserts, and how much to mock, are separate subjects that apply under any runner.
- What happens to your vite.config settings when you add a separate vitest.config.ts?Vitest looks for `vitest.config.*` first and `vite.config.*` second, and a `vitest.config.ts` wins outright: the options in the Vite file are ignored, not merged. Aliases and plugins defined only there vanish from the tests, so imports that relied on them stop resolving. Wrap both with `mergeConfig(viteConfig, defineConfig({ test: { ... } }))` from `vitest/config` to keep one source of truth.
- Why can a Vitest test pass even though its file contains a TypeScript type error?A normal run transforms TypeScript by removing the types; it never runs the type checker, so a wrong type is invisible unless the code misbehaves at runtime. Type checking stays a separate step: the compiler in CI, or Vitest's `typecheck` mode, which runs the TypeScript compiler over type-test files such as `*.test-d.ts` that hold `expectTypeOf` or `assertType` checks.
- Why does 'describe is not defined' appear after copying a Jest test file into a Vitest project?Vitest's `globals` option defaults to `false`, so `describe`, `test`, `expect` and `vi` exist only when imported from `vitest`. Add the import to each file, or set `test.globals: true` and list `vitest/globals` in `compilerOptions.types`. Some DOM helper libraries rely on global hooks for automatic cleanup, which is one reason teams switch globals on during a migration.
- Vitest needs its own transformer configured before it can run TypeScript tests.
- Vitest exposes describe, test and expect as globals by default, just like Jest.
- A vitest.config.ts is merged with vite.config.ts automatically.
- Vitest only works for projects whose app is built with Vite.
- Watch mode re-runs the whole suite every time any file is saved.
- A Vitest run fails whenever a test file has a TypeScript type error.