Recursos

• Configuração, transformadores, resolvedores e plugins do Vite
• Utilize a mesma configuração do seu aplicativo para executar os testes!
• Modo de observação (watch mode) inteligente e instantâneo, como HMR para testes!
• Testes de componentes para Vue, React, Svelte, Lit, Marko e muito mais
• Suporte nativo a TypeScript e JSX
• ESM por padrão, top level await
• Multi-threading de workers via Tinypool
• Suporte a benchmarking com Tinybench
• Filtragem, timeouts e concorrência para suítes e testes
• Suporte a Projetos
• Snapshot compatível com Jest
• Chai integrado para realizar asserções + APIs compatíveis com Jest expect
• Tinyspy integrado para simulação (mocking)
• happy-dom ou jsdom para simulação de DOM
• Modo Navegador para executar testes de componentes no navegador
• Cobertura de código através de v8 ou istanbul
• Testes in-source no estilo Rust
• Teste de Tipos através de expect-type
• Suporte a Sharding
• Relatório de Erros Não Tratados

Aprenda a escrever seu primeiro teste em vídeo

Configuração Compartilhada entre Teste, Desenvolvimento e Build

Configuração, transformadores, resolvedores e plugins do Vite. Utilize a mesma configuração do seu aplicativo para executar os testes.

Saiba mais em Configurando Vitest.

Modo de Observação (Watch Mode)

$ vitest

Quando você modifica seu código-fonte ou os arquivos de teste, o Vitest busca de forma inteligente no grafo de módulos e executa novamente apenas os testes relacionados, assim como o HMR funciona no Vite!

vitest inicia no watch mode por padrão no ambiente de desenvolvimento e no run mode no ambiente de CI (quando process.env.CI está presente) de forma inteligente. Você pode usar vitest watch ou vitest run para especificar explicitamente o modo desejado.

Inicie o Vitest com a flag --standalone para mantê-lo em execução em segundo plano. Ele não executará nenhum teste até que os arquivos de teste sejam alterados. O Vitest não executará testes se o código-fonte for alterado até que o teste que importa a fonte tenha sido executado.

Recursos Web Comuns Prontos para Uso

Suporte nativo a Módulos ES / TypeScript / JSX / PostCSS

Threads

Por padrão, o Vitest executa arquivos de teste em múltiplos processos usando node:child_process via Tinypool (um fork leve de Piscina), permitindo que os testes sejam executados simultaneamente. Se você quiser acelerar ainda mais sua suíte de testes, considere habilitar --pool=threads para executar testes usando node:worker_threads (cuidado que alguns pacotes podem não funcionar com esta configuração).

Para executar testes em um único thread ou processo, consulte poolOptions.

O Vitest também isola o ambiente de cada arquivo para que alterações de ambiente em um arquivo não afetem outros. O isolamento pode ser desabilitado passando --no-isolate para a CLI (priorizando o desempenho de execução em detrimento da correção).

Filtragem de Testes

O Vitest oferece muitas maneiras de restringir os testes a serem executados para acelerar os testes, para que você possa se concentrar no desenvolvimento.

Saiba mais sobre Filtragem de Testes.

Executando Testes em Paralelo

Use .concurrent em testes para iniciá-los em paralelo.

import { describe, it } from 'vitest';

// Os dois testes marcados com concurrent serão iniciados em paralelo
describe('suite', () => {
  it('serial test', async () => {
    /* ... */
  });
  it.concurrent('concurrent test 1', async ({ expect }) => {
    /* ... */
  });
  it.concurrent('concurrent test 2', async ({ expect }) => {
    /* ... */
  });
});

Se você usar .concurrent em uma suíte, todos os testes nela serão iniciados em paralelo.

import { describe, it } from 'vitest';

// Todos os testes dentro desta suíte serão iniciados em paralelo
describe.concurrent('suite', () => {
  it('concurrent test 1', async ({ expect }) => {
    /* ... */
  });
  it('concurrent test 2', async ({ expect }) => {
    /* ... */
  });
  it.concurrent('concurrent test 3', async ({ expect }) => {
    /* ... */
  });
});

Você também pode usar .skip, .only e .todo com suítes e testes concorrentes. Leia mais na Referência da API.

WARNING

Ao executar testes concorrentes, Snapshots e Asserções devem usar expect do Contexto de Teste local para garantir a correta associação ao teste.

Snapshot

Suporte a snapshots compatível com Jest.

import { expect, it } from 'vitest';

it('renders correctly', () => {
  const result = render();
  expect(result).toMatchSnapshot();
});

Saiba mais em Snapshot.

Compatibilidade com Chai e Jest expect

Chai é integrado para asserções com APIs compatíveis com Jest expect.

Observe que, se você estiver usando bibliotecas de terceiros que adicionam matchers, definir test.globals como true melhorará a compatibilidade.

Mocking

Tinyspy é integrado para simulação (mocking) com APIs compatíveis com jest no objeto vi.

import { expect, vi } from 'vitest';

const fn = vi.fn();

fn('hello', 1);

expect(vi.isMockFunction(fn)).toBe(true);
expect(fn.mock.calls[0]).toEqual(['hello', 1]);

fn.mockImplementation((arg: string) => arg);

fn('world', 2);

expect(fn.mock.results[1].value).toBe('world');

O Vitest suporta tanto happy-dom quanto jsdom para simulação (mocking) de DOM e APIs de navegador. Eles não vêm com o Vitest, você precisará instalá-los separadamente:

happy-dom

$ npm i -D happy-dom

jsdom

$ npm i -D jsdom

Depois disso, altere a opção environment no seu arquivo de configuração:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'happy-dom', // ou 'jsdom', 'node'
  },
});

Saiba mais em Mocking.

Cobertura

O Vitest suporta cobertura de código nativa via v8 e cobertura de código instrumentada via istanbul.

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

Saiba mais em Cobertura.

Teste In-Source

O Vitest também oferece uma maneira de executar testes dentro do seu código-fonte junto com a implementação, semelhante aos testes de módulo do Rust.

Isso permite que os testes compartilhem o mesmo escopo (closure) que as implementações e sejam capazes de testar estados privados sem a necessidade de exportação. Ao mesmo tempo, isso também agiliza o ciclo de feedback durante o desenvolvimento.

// a implementação
export function add(...args: number[]): number {
  return args.reduce((a, b) => a + b, 0);
}

// suítes de teste in-source
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest;
  it('add', () => {
    expect(add()).toBe(0);
    expect(add(1)).toBe(1);
    expect(add(1, 2, 3)).toBe(6);
  });
}

Saiba mais em Teste in-source.

Benchmarking Experimental

Você pode executar testes de desempenho com a função bench via Tinybench para comparar resultados.

import { bench, describe } from 'vitest';

describe('sort', () => {
  bench('normal', () => {
    const x = [1, 5, 4, 2, 3];
    x.sort((a, b) => {
      return a - b;
    });
  });

  bench('reverse', () => {
    const x = [1, 5, 4, 2, 3];
    x.reverse().sort((a, b) => {
      return a - b;
    });
  });
});

Teste de Tipos Experimental

Você pode escrever testes para capturar regressões de tipo. O Vitest vem com o pacote expect-type, que oferece uma API semelhante e fácil de entender.

import { assertType, expectTypeOf, test } from 'vitest';
import { mount } from './mount.js';

test('my types work properly', () => {
  expectTypeOf(mount).toBeFunction();
  expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>();

  // @ts-expect-error name is a string
  assertType(mount({ name: 42 }));
});

Sharding

Execute testes em máquinas diferentes usando as flags --shard e --reporter=blob. Todos os resultados de teste e cobertura podem ser mesclados ao final do seu pipeline de CI usando o comando --merge-reports:

vitest --shard=1/2 --reporter=blob --coverage
vitest --shard=2/2 --reporter=blob --coverage
vitest --merge-reports --reporter=junit --coverage

Consulte Melhorando o Desempenho | Sharding para obter mais informações.

Variáveis de Ambiente

O Vitest carrega exclusivamente variáveis de ambiente prefixadas com VITE_ de arquivos .env. Isso mantém a compatibilidade com testes relacionados ao frontend, seguindo a convenção estabelecida pelo Vite. Para carregar todas as variáveis de ambiente de arquivos .env, você pode usar o método loadEnv importado do vite:

import { loadEnv } from 'vite';
import { defineConfig } from 'vitest/config';

export default defineConfig(({ mode }) => ({
  test: {
    // mode define qual arquivo ".env.{mode}" escolher, se existir
    env: loadEnv(mode, process.cwd(), ''),
  },
}));

Erros Não Tratados

Por padrão, o Vitest captura e relata todas as rejeições de promessas não tratadas, exceções não capturadas (no Node.js) e eventos de erro (no ambiente do navegador).

Você pode desabilitar esse comportamento tratando-os manualmente. O Vitest assume que o callback foi manipulado por você e, portanto, não relatará o erro.

setup.node.js

// no Node.js
process.on('unhandledRejection', () => {
  // seu próprio manipulador
});

process.on('uncaughtException', () => {
  // seu próprio manipulador
});

setup.browser.js

// no navegador
window.addEventListener('error', () => {
  // seu próprio manipulador
});

window.addEventListener('unhandledrejection', () => {
  // seu próprio manipulador
});

Alternativamente, você também pode ignorar os erros reportados usando a opção dangerouslyIgnoreUnhandledErrors. O Vitest ainda os relatará, mas eles não afetarão o resultado do teste (o código de saída permanecerá o mesmo).

Se você precisar testar que um erro não foi capturado, você pode criar um teste semelhante a este:

test('my function throws uncaught error', async ({ onTestFinished }) => {
  onTestFinished(() => {
    // caso o evento nunca tenha sido chamado durante o teste,
    // certifique-se de que ele seja removido antes do início do próximo teste.
    process.removeAllListeners('unhandledrejection');
  });

  return new Promise((resolve, reject) => {
    process.once('unhandledrejection', error => {
      try {
        expect(error.message).toBe('my error');
        resolve();
      } catch (error) {
        reject(error);
      }
    });

    callMyFunctionThatRejectsError();
  });
});