Skip to content

Vitest Basics

Set up Vitest, write your first test, run the watcher, and read the results.

What you'll learn

  • How to install and configure Vitest in a Vite project
  • Writing describe, it, and expect blocks
  • Running tests in watch mode and in CI
  • Reading and interpreting the terminal report

Concept

Why Vitest

Vitest is a test framework built on Vite. Because it reuses your project's Vite pipeline, your tests transform TypeScript, JSX, and CSS exactly the way your app does — no separate babel or ts-jest config to drift out of sync. It is also extremely fast: tests run in parallel worker threads and transform via esbuild, so even large suites finish in seconds.

Installation and Config

Add Vitest with pnpm add -D vitest. If your project already has a vite.config.ts, Vitest reads it automatically; you only add a test section for test-specific options like the environment (jsdom for DOM tests) or globals. Add scripts to package.json: "test": "vitest" for watch mode and "test:run": "vitest run" for a single CI pass.

Anatomy of a Test

A test file imports describe, it, and expect from vitest. describe groups related tests, it (or test) defines one case, and expect chains matchers like toBe, toEqual, and toThrow. Vitest's matcher API is Jest-compatible, so existing Jest knowledge transfers directly.

Running and Reading Results

In watch mode, Vitest reruns only the tests affected by your changed files, giving sub-second feedback. The terminal report shows a checkmark or cross per test, the failing assertion's expected vs actual values, and the source location of the failure. In CI, vitest run exits with a non-zero code on failure, which is what your pipeline needs to gate merges.

In Practice

A typical first session: install Vitest, add a math.test.ts next to your math.ts, run npx vitest, and watch the terminal. Edit the source file and the test reruns instantly — this tight loop is addictive and is the core of why developers who try modern test runners never go back. Configure coverage with the v8 provider for fast, accurate reports, and set thresholds so coverage cannot silently drop. For DOM and component tests, switch the environment to jsdom or happy-dom either in the config or with a per-file // @vitest-environment jsdom comment. Use vi.mock for module mocks and vi.fn for function doubles — you will meet these in the test-doubles lessons. Keep the config minimal; Vitest's defaults are good, and fighting the framework's opinions usually signals a design problem in the code under test.

Example

              // vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "node", // use "jsdom" for DOM/component tests
    globals: false,       // prefer explicit imports
  },
});

// src/math.test.ts
import { describe, it, expect } from "vitest";

export function factorial(n: number): number {
  return n <= 1 ? 1 : n * factorial(n - 1);
}

describe("factorial", () => {
  it("computes 5! as 120", () => {
    expect(factorial(5)).toBe(120);
  });
});
            

The config is minimal because Vitest inherits Vite settings. Run `npx vitest` to start watching; edit a file and the relevant test reruns instantly.

Try it

  • Code Diff

    Diff expected vs actual when a Vitest assertion fails.

  • JSON Formatter

    Format the JSON output from `vitest run --reporter=json`.

Common mistakes

The mistake

Forgetting to set the environment for DOM tests

The fix

Component tests need `environment: 'jsdom'` (or 'happy-dom') in the config or a `// @vitest-environment jsdom` comment, or document is undefined.

The mistake

Leaving watch mode running in CI

The fix

Use `vitest run` (single pass) in CI scripts and `vitest` (watch) only locally. Watch mode never exits and hangs pipelines.

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors