Primeiros Passos

Visão Geral

Vitest é um framework de teste de nova geração alimentado por 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 da web e é quase idêntico à configuração local, mas você não precisa instalar nada em sua máquina.

Adicionando o Vitest ao seu Projeto

Aprenda a instalar por vídeo

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

TIP

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

Recomenda-se instalar o vitest como uma dependência de desenvolvimento no seu package.json, utilizando um dos métodos listados acima. No entanto, se você preferir executar o vitest diretamente, você pode usar npx vitest (o comando npx é fornecido com o npm e o Node.js).

O comando npx irá executar o comando a partir de um node_modules/.bin local, instalando quaisquer pacotes necessários para a execução. Por padrão, o npx verifica se o comando existe no $PATH ou nos binários do projeto local e o executa. Se o comando não for encontrado, ele será instalado antes da execução.

Escrevendo Testes

Como exemplo, vamos escrever um teste simples para verificar 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';

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

TIP

Por padrão, os testes devem conter ".test." ou ".spec." em seus nomes de arquivo.

Em seguida, para executar o teste, adicione a seguinte seção ao seu package.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:

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

Arquivos de Teste  1 passou (1)
    Tests  1 passou (1)
  Iniciado às 02:15:44
  Duration  311ms

Aprenda mais sobre o uso do Vitest, veja 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á o arquivo vite.config.ts na raiz do seu projeto para identificar os plugins e configurações do seu aplicativo Vite. Por exemplo, sua configuração do Vite para resolve.alias e plugins funcionará automaticamente. Caso necessite de uma configuração diferente para os testes, você pode:

• Criar vitest.config.ts, que terá a prioridade mais alta
• Passar a opção --config para a 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 substituído) para aplicar condicionalmente uma configuração diferente em vite.config.ts

O Vitest suporta os mesmos tipos 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, pode configurar o Vitest utilizando a propriedade test no seu arquivo de configuração:

import { defineConfig } from 'vitest/config';

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

TIP

Mesmo que você não utilize o Vite diretamente, o Vitest depende fortemente dele para o processo de transformação dos arquivos. 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 na sua configuração do Vite. Você também precisará adicionar uma referência aos tipos do Vitest usando uma diretiva de barra tripla no topo do seu arquivo de configuração.

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

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

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

WARNING

Caso opte por arquivos de configuração separados para Vite e Vitest, defina as mesmas opções do Vite no arquivo de configuração do Vitest. O arquivo do Vitest irá substituir, e não estender, o arquivo do Vite. Você também pode usar o método mergeConfig das entradas vite ou vitest/config para mesclar a configuração do Vite com a do Vitest:

vitest.config.mjs

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

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

vite.config.mjs

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

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

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

Suporte a Workspaces (Espaços de Trabalho)

Execute diferentes configurações de projeto dentro do mesmo projeto com Vitest Workspaces. Você pode definir os arquivos e pastas que compõem seu workspace no arquivo vitest.workspace. O arquivo suporta extensões js/ts/json. Este recurso funciona muito bem com configurações de monorepo.

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  // you can use a list of glob patterns to define your workspaces
  // Vitest expects a list of config files
  // or directories where there is a config file
  'packages/*',
  'tests/*/vitest.config.{e2e,unit}.ts',
  // you can even run the same tests,
  // but with different configs in the same "vitest" process
  {
    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 (CLI)

Em um projeto onde o Vitest está instalado, você pode usar o binário vitest nos seus scripts npm ou executá-lo diretamente com npx vitest. A seguir, os scripts npm padrão em um projeto Vitest inicializado:

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

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

Aprenda mais sobre a Interface de Linha de Comando

Integrações com IDE

Também fornecemos uma extensão oficial para o Visual Studio Code para melhorar sua experiência com testes utilizando o Vitest.

Instalar da VS Code Marketplace

Aprenda mais sobre Integrações com IDE

Exemplos

Exemplo	Fonte	Playground
basic	GitHub	Play Online
fastify	GitHub	Play Online
lit	GitHub	Play Online
marko	GitHub	Play Online
preact	GitHub	Play Online
react	GitHub	Play Online
solid	GitHub	Play Online
sveltekit	GitHub	Play Online
typecheck	GitHub	Play Online
workspace	GitHub	Play Online

Projetos usando Vitest

• unocss
• unplugin-auto-import
• unplugin-vue-components
• vue
• vite
• vitesse
• vitesse-lite
• fluent-vue
• vueuse
• milkdown
• gridjs-svelte
• spring-easing
• bytemd
• faker
• million
• Vitamin
• neodrag
• svelte-multiselect
• iconify
• tdesign-vue-next
• cz-git

Usando Commits Não Lançados

Se você não pode esperar por um novo lançamento para testar os novos recursos, será necessário clonar o repositório do vitest para sua máquina local e, em seguida, construir e linká-lo você mesmo (pnpm é necessário):

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 este passo

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

Comunidade

Em caso de dúvidas ou necessidade de ajuda, procure a comunidade através do Discord ou das Discussões do GitHub.