vitest para TypeScript: Guia Completo

vitest é um framework de teste unitário moderno, rápido e poderoso, desenvolvido especialmente para o ecossistema TypeScript e JavaScript. Ele foi criado como uma alternativa direta ao Jest, mas com foco em velocidade de execução e suporte nativo ao Vite. Se você usa Vite para construir seus projetos, o vitest é a escolha ideal, pois utiliza o mesmo plugin e configuração da sua ferramenta de build principal.

Por que usar vitest? Primeiro, ele é incrivelmente rápido graças ao uso do esbuild para transpilação e suporte nativo a ESM (ECMAScript Modules). Segundo, oferece uma API rica e compatível com Jest, facilitando a migração. Terceiro, o vitest fornece suporte integrado para TypeScript, JSX, mocking, cobertura de código e testes de snapshot, sem precisar instalar pacotes adicionais. Isso o torna ideal tanto para projetos pequenos quanto para grandes aplicações enterprise.

Neste site educacional PythonLib, vamos mostrar como usar o vitest para testar código TypeScript. Você aprenderá a instalar a biblioteca, escrever seus primeiros testes, dominar os métodos principais e evitar erros comuns. Ao final deste artigo, você será capaz de usar vitest com confiança em seus projetos.

Instalação

A instalação do vitest é feita via npm ou yarn. Para projetos TypeScript, você também precisará instalar o próprio TypeScript e os tipos para Node.js (se estiver testando código server-side).

npm install -D vitest typescript @types/node

Se você usa yarn:

yarn add -D vitest typescript @types/node

Após a instalação, adicione o script no package.json:

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

O comando vitest executa os testes em modo watch (reinicia automaticamente ao detectar alterações), enquanto vitest run faz uma execução única.

Primeiros passos

Crie um arquivo sum.ts com uma função simples:

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

Agora crie o arquivo de teste sum.test.ts:

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

describe('função sum', () => {
  it('deve somar dois números corretamente', () => {
    expect(sum(2, 3)).toBe(5);
  });

  it('deve lidar com números negativos', () => {
    expect(sum(-1, -2)).toBe(-3);
  });
});

Execute os testes:

npm run test

Você verá uma saída verde indicando que os testes passaram com sucesso. Parabéns, você escreveu seu primeiro teste com vitest!

Métodos e funções principais

O vitest oferece uma API rica para escrever testes. Abaixo estão 8 métodos essenciais com descrições e exemplos práticos.

1. describe

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

Descrição: Agrupa testes relacionados em um bloco. Melhora a legibilidade e permite aplicar hooks (beforeEach, afterEach) ao grupo.

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

describe('Operações matemáticas', () => {
  it('deve somar', () => {
    expect(1 + 1).toBe(2);
  });

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

2. it / test

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

Descrição: Define um teste individual. Você pode usar tanto it quanto test — são sinônimos.

import { it, expect } from 'vitest';

it('deve retornar true