Install Vitest with TypeScript

Vitest is a blazing fast unit test framework powered by Vite. It is designed to provide a seamless testing experience, and when combined with TypeScript, it offers strong typing support, making your test code more robust and maintainable. In this blog, we'll guide you through the process of installing Vitest with TypeScript, explain its fundamental concepts, usage methods, common practices, and best practices.

Table of Contents#

  1. Fundamental Concepts
  2. Installation Process
  3. Usage Methods
  4. Common Practices
  5. Best Practices
  6. Conclusion
  7. References

Fundamental Concepts#

Vitest#

Vitest is a testing framework that uses Vite's capabilities to provide a fast and reliable testing environment. It is inspired by Jest and has a similar API, which makes it easy for developers familiar with Jest to switch. Vitest can run tests in parallel, which significantly reduces the overall testing time.

TypeScript#

TypeScript is a superset of JavaScript that adds static typing to the language. By using TypeScript with Vitest, you can catch type-related errors early in the development process, making your test code more robust and easier to understand and maintain.

Installation Process#

Step 1: Initialize a new project#

First, create a new directory for your project and initialize a new npm project:

mkdir vitest-typescript-project
cd vitest-typescript-project
npm init -y

Step 2: Install Dependencies#

Install Vitest, TypeScript, and related packages. You'll need vitest, typescript, @types/node (for TypeScript type definitions related to Node.js), and @vitest/ui for the Vitest UI if you want a graphical interface for running tests.

npm install --save-dev vitest typescript @types/node @vitest/ui

Step 3: Configure TypeScript#

Create a tsconfig.json file in the root of your project if it doesn't exist already. Here is a basic configuration:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "Node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve"
  },
  "include": ["src", "test"]
}

Step 4: Configure Vitest#

Create a vite.config.ts file in the root of your project. Here is a simple configuration:

import { defineConfig } from 'vite';
 
export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
  },
});

Usage Methods#

Writing a Simple Test#

Let's assume we have a simple JavaScript function in a file named math.ts:

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

We can write a test for this function using Vitest. Create a file named math.test.ts in the same directory as math.ts:

import { describe, it, expect } from 'vitest';
import { add } from './math';
 
describe('add function', () => {
  it('should add two numbers correctly', () => {
    const result = add(2, 3);
    expect(result).toBe(5);
  });
});

Running Tests#

You can run the tests in different ways. If you want to run tests in the console, add the following script to your package.json:

{
  "scripts": {
    "test": "vitest"
  }
}

Then run the tests using the following command:

npm test

If you want to use the Vitest UI, you can add another script to your package.json:

{
  "scripts": {
    "test:ui": "vitest --ui"
  }
}

And run it with:

npm run test:ui

Common Practices#

Grouping Tests#

Use the describe function to group related tests. This makes the test suite more organized and easier to understand. For example:

import { describe, it, expect } from 'vitest';
import { add, subtract } from './math';
 
describe('Math functions', () => {
  describe('add function', () => {
    it('should add two numbers correctly', () => {
      const result = add(2, 3);
      expect(result).toBe(5);
    });
  });
 
  describe('subtract function', () => {
    it('should subtract two numbers correctly', () => {
      const result = subtract(5, 3);
      expect(result).toBe(2);
    });
  });
});

Using Hooks#

Vitest provides hooks like beforeEach, afterEach, beforeAll, and afterAll. These can be used to set up and tear down the testing environment.

import { describe, it, expect, beforeEach } from 'vitest';
 
let counter = 0;
 
describe('Counter tests', () => {
  beforeEach(() => {
    counter = 0;
  });
 
  it('should increment counter', () => {
    counter++;
    expect(counter).toBe(1);
  });
 
  it('should still start from zero', () => {
    expect(counter).toBe(0);
  });
});

Best Practices#

Mocking Dependencies#

When testing components or functions that rely on external services or modules, it's a good practice to use mocks. Vitest provides built-in mocking capabilities.

import { describe, it, expect, vi } from 'vitest';
import { someFunctionThatCallsApi } from './apiService';
 
// Mock the API call
const mockApiCall = vi.fn(() => Promise.resolve({ data: 'mocked data' }));
vi.mock('./apiService', () => ({
  someFunctionThatCallsApi: mockApiCall,
}));
 
describe('Mocking API calls', () => {
  it('should use the mocked API call', async () => {
    const result = await someFunctionThatCallsApi();
    expect(mockApiCall).toHaveBeenCalled();
    expect(result).toEqual({ data: 'mocked data' });
  });
});

Keeping Tests Independent#

Each test should be independent of other tests. This ensures that the failure of one test does not affect the execution and result of other tests. Avoid sharing mutable state between tests as much as possible.

Continuous Integration#

Integrate your Vitest tests into your CI/CD pipeline. For example, if you are using GitHub Actions, you can add the following workflow:

name: Vitest Tests
 
on:
  push:
    branches:
      - main
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: 16
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

Conclusion#

Installing and using Vitest with TypeScript is a straightforward process that can bring significant benefits to your testing workflow. Vitest's speed and the strong typing support of TypeScript make for a powerful combination. By following the installation steps, usage methods, common practices, and best practices outlined in this blog, you can write efficient, reliable, and maintainable test suites.

References#

2025-10