Vitest for TypeScript: The Complete Guide

Vitest is a modern, fast, and powerful unit testing framework built specifically for the TypeScript and JavaScript ecosystem. It's designed as a direct alternative to Jest, but with a focus on execution speed and native Vite support. If you use Vite to build your project, Vitest is the perfect choice because it leverages the same plugins and configuration as your main build tool.

Why choose Vitest? First, it's incredibly fast thanks to esbuild for transpilation and native ESM (ECMAScript Modules) support. Second, it offers a rich API compatible with Jest, making migration a breeze. Third, Vitest provides built-in support for TypeScript, JSX, mocking, coverage, and snapshot testing—no extra packages required. This makes it ideal for everything from small projects to large enterprise applications.

On this educational site, PythonLib, we'll show you how to use Vitest for testing TypeScript code. You'll learn how to install the library, write your first tests, master the core methods, and avoid common pitfalls. By the end of this article, you'll be confident using Vitest in your own projects.

Installation

Installing Vitest is done via npm or yarn. For a TypeScript project, you'll also need to install TypeScript itself and the Node.js type definitions (if you're testing server-side code).

npm install -D vitest typescript @types/node

If you're using yarn:

yarn add -D vitest typescript @types/node

After installation, add a script to your package.json:

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run"
  }
}

The vitest command runs tests in watch mode (automatically re-runs on changes), while vitest run runs them once.

Quick Start

Create a file called sum.ts with a simple function:

// sum.ts
export function sum(a: number, b: number): number {
  return a + b;
}

Now create a test file sum.test.ts:

// sum.test.ts
import { describe, it, expect } from 'vitest';
import { sum } from './sum';

describe('sum function', () => {
  it('should add two numbers correctly', () => {
    expect(sum(2, 3)).toBe(5);
  });

  it('should handle negative numbers', () => {
    expect(sum(-1, -2)).toBe(-3);
  });
});

Run the tests:

npm run test

You'll see a green output indicating all tests passed. Congratulations, you've written your first Vitest test!

Core Methods and Functions

Vitest provides a rich API for writing tests. Below are 8 key methods with descriptions and examples.

1. describe

Signature: describe(name: string, fn: () => void): void

Description: Groups related tests into a block. Improves readability and allows you to apply hooks (beforeEach, afterEach) to the group.

import { describe, it, expect } from 'vitest';

describe('Math operations', () => {
  it('should add', () => {
    expect(1 + 1).toBe(2);
  });

  it('should subtract', () => {
    expect(5 - 3).toBe(2);
  });
});

2. it / test

Signature: it(name: string, fn: () => void | Promise<void>, timeout?: number): void

Description: Defines an individual test case. You can use either it or test—they are synonyms.

import { it, expect } from 'vitest';

it('should return true