Introdução

Visão Geral

Vitest (pronuncia-se "veetest") é um framework de testes de próxima geração baseado no Vite.

Você pode aprender mais sobre a motivação por trás do projeto na seção Por que Vitest.

Experimentando o Vitest Online

Você pode experimentar o Vitest online no StackBlitz. Ele executa o Vitest diretamente no navegador e é quase idêntico à configuração local, mas não requer nenhuma instalação em sua máquina.

Adicionando o Vitest ao Seu Projeto

Aprenda a instalar via Vídeo

npmyarnpnpmbun

bash

npm install -D vitest

bash

yarn add -D vitest

bash

pnpm add -D vitest

bash

bun add -D vitest

TIP

Vitest requer Vite >=v5.0.0 e Node >=v18.0.0

Recomenda-se instalar o vitest em seu package.json, usando um dos métodos listados acima. No entanto, se você preferir executar o vitest diretamente, pode usar npx vitest (a ferramenta npx vem com npm e Node.js).

A ferramenta npx executa o comando especificado. Por padrão, o npx primeiro verifica se o comando existe nos binários do projeto local. Se não for encontrado, o npx procura no $PATH do sistema e o executa, caso o encontre. Se o comando não for encontrado em nenhum desses locais, o npx o instala em um local temporário antes da execução.

Escrevendo Testes

Como exemplo, escreveremos um teste simples que verifica o retorno de uma função que soma dois números.

// sum.js
export function sum(a, b) {
  return a + b;
}

// sum.test.js
import { expect, test } from 'vitest';
import { sum } from './sum.js';

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

TIP

Por padrão, os nomes dos arquivos de teste devem conter ".test." ou ".spec.".

Em seguida, para executar o teste, adicione a seguinte seção ao seu package.json:

json

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

Finalmente, execute npm run test, yarn test ou pnpm test, dependendo do seu gerenciador de pacotes, e o Vitest exibirá esta mensagem:

txt

✓ sum.test.js (1)
  ✓ adds 1 + 2 to equal 3

Test Files  1 passed (1)
     Tests  1 passed (1)
  Start at  02:15:44
  Duration  311ms

WARNING

Se você estiver usando Bun como seu gerenciador de pacotes, certifique-se de usar o comando bun run test em vez de bun test, caso contrário, o Bun executará seu próprio executor de testes.

Para saber mais sobre o uso do Vitest, consulte a seção API.

Configurando o Vitest

Uma das principais vantagens do Vitest é sua configuração unificada com o Vite. Se presente, o vitest lerá seu vite.config.ts raiz para corresponder aos plugins e à configuração do seu aplicativo Vite. Por exemplo, suas configurações de resolve.alias e plugins do Vite funcionarão prontas para uso. Se você quiser uma configuração diferente durante o teste, você pode:

Criar vitest.config.ts, que terá a maior prioridade.
Utilizar a opção --config na CLI, por exemplo, vitest --config ./path/to/vitest.config.ts.
Usar process.env.VITEST ou a propriedade mode em defineConfig (será definido como test se não for sobrescrito) para aplicar condicionalmente uma configuração diferente em vite.config.ts.

O Vitest suporta as mesmas extensões de arquivo de configuração que o Vite: .js, .mjs, .cjs, .ts, .cts, .mts. O Vitest não suporta a extensão .json.

Se você não estiver usando o Vite como sua ferramenta de build, você pode configurar o Vitest usando a propriedade test em seu arquivo de configuração:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ...
  },
});

TIP

Mesmo que você não use o Vite, o Vitest depende muito dele para seu pipeline de transformação. Por esse motivo, você também pode configurar qualquer propriedade descrita na documentação do Vite.

Se você já estiver usando o Vite, adicione a propriedade test em sua configuração do Vite. Você também precisará adicionar uma referência aos tipos do Vitest usando uma diretiva de barra tripla no início do seu arquivo de configuração.

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ...
  },
});

O <reference types="vitest" /> será descontinuado no Vitest 3, mas você pode começar a migrar para vitest/config no Vitest 2.1:

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... Especifique suas opções aqui.
  },
});

Veja a lista de opções de configuração na Referência de Configuração

WARNING

Se você decidir ter dois arquivos de configuração separados para Vite e Vitest, certifique-se de definir as mesmas opções do Vite em seu arquivo de configuração do Vitest, pois ele substituirá o arquivo do Vite, em vez de estendê-lo. Você também pode usar o método mergeConfig de vite ou vitest/config para mesclar a configuração do Vite com a configuração do Vitest:

vitest.config.mjsvite.config.mjs

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config.mjs';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // ...
    },
  })
);

import { defineConfig } from 'vite';
import Vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [Vue()],
});

No entanto, recomendamos usar o mesmo arquivo para Vite e Vitest, em vez de criar dois arquivos separados.

Suporte a Workspaces

Gerencie diferentes configurações de projeto dentro do mesmo projeto com Vitest Workspaces. Você pode definir uma lista de arquivos e pastas que definem seu workspace no arquivo vitest.workspace. O arquivo aceita as extensões js/ts/json. Este recurso é ideal para configurações de monorepo.

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  // você pode usar uma lista de padrões glob para definir seus workspaces
  // Vitest requer uma lista de arquivos de configuração
  // ou diretórios onde há um arquivo de configuração
  'packages/*',
  'tests/*/vitest.config.{e2e,unit}.ts',
  // você pode até executar os mesmos testes,
  // mas com configurações diferentes no mesmo processo "vitest"
  {
    test: {
      name: 'happy-dom',
      root: './shared_tests',
      environment: 'happy-dom',
      setupFiles: ['./setup.happy-dom.ts'],
    },
  },
  {
    test: {
      name: 'node',
      root: './shared_tests',
      environment: 'node',
      setupFiles: ['./setup.node.ts'],
    },
  },
]);

Interface de Linha de Comando

Em projetos com o Vitest instalado, você pode usar o binário vitest em seus scripts npm, ou executá-lo diretamente com npx vitest. Aqui estão os scripts npm padrão em um projeto Vitest recém-criado:

json

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

Para executar os testes uma vez sem monitorar as alterações nos arquivos, use vitest run. Você pode especificar opções adicionais da CLI como --port ou --https. Para uma lista completa das opções da CLI, execute npx vitest --help em seu projeto.

Para saber mais sobre a Interface de Linha de Comando.

Instalação Automática de Dependências

O Vitest solicitará a instalação de certas dependências se elas ainda não estiverem instaladas. Você pode desabilitar esse comportamento ao definir a variável de ambiente VITEST_SKIP_INSTALL_CHECKS=1.

Integrações com IDEs

Também oferecemos uma extensão oficial para o Visual Studio Code para aprimorar sua experiência de teste com o Vitest.

Instalar do VS Code Marketplace

Saiba mais sobre Integrações com IDEs

Exemplos

Exemplo	Fonte	Playground
`basic`	GitHub	Play Online
`fastify`	GitHub	Play Online
`in-source-test`	GitHub	Play Online
`lit`	GitHub	Play Online
`vue`	GitHub	Play Online
`marko`	GitHub	Play Online
`preact`	GitHub	Play Online
`react`	GitHub	Play Online
`solid`	GitHub	Play Online
`svelte`	GitHub	Play Online
`sveltekit`	GitHub	Play Online
`profiling`	GitHub	Não Disponível
`typecheck`	GitHub	Play Online
`workspace`	GitHub	Play Online

Projetos que usam Vitest

Usando Commits Não Lançados

Cada commit na branch principal e cada PR com o rótulo cr-tracked são publicados em pkg.pr.new. Você pode instalá-lo usando npm i https://pkg.pr.new/vitest@{commit}.

Se você quiser testar suas próprias modificações localmente, você pode compilá-las e vinculá-las manualmente (é necessário o pnpm):

bash

git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # você pode usar seu gerenciador de pacotes preferido para esta etapa

Em seguida, vá para o projeto onde você está usando o Vitest e execute pnpm link --global vitest (ou o comando de link global do gerenciador de pacotes que você utilizou).

Comunidade

Se você tiver dúvidas ou precisar de ajuda, entre em contato com a comunidade através do Discord e GitHub Discussions.

Introdução ​

Visão Geral ​

Experimentando o Vitest Online ​

Adicionando o Vitest ao Seu Projeto ​

Escrevendo Testes ​

Configurando o Vitest ​

Suporte a Workspaces ​

Interface de Linha de Comando ​

Instalação Automática de Dependências ​

Integrações com IDEs ​

Exemplos ​

Projetos que usam Vitest ​

Usando Commits Não Lançados ​

Comunidade ​

Introdução

Visão Geral

Experimentando o Vitest Online

Adicionando o Vitest ao Seu Projeto

Escrevendo Testes

Configurando o Vitest

Suporte a Workspaces

Interface de Linha de Comando

Instalação Automática de Dependências

Integrações com IDEs

Exemplos

Projetos que usam Vitest

Usando Commits Não Lançados

Comunidade