Primeiros Passos

Visão Geral

Vitest é um framework de teste unitário ultrarrápido, impulsionado pelo 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

npmyarnpnpm

bash

npm install -D vitest

bash

yarn add -D vitest

bash

pnpm add -D vitest

TIP

O Vitest requer Vite >= v3.0.0 e Node >= v14.18

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);
});

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

Arquivos de Teste  1 passou (1)
    Tests  1 passou (1)
  Iniciado às 02:15:44
  Duration  311ms (transform 23ms, setup 0ms, collect 16ms, tests 2ms, environment 0ms, prepare 106ms)

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.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()],
});

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:

json

{
  "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
`graphql`	GitHub	Play Online
`image-snapshot`	GitHub	Play Online
`lit`	GitHub	Play Online
`mocks`	GitHub	Play Online
`nextjs`	GitHub	Play Online
`playwright`	GitHub
`puppeteer`	GitHub
`react-enzyme`	GitHub	Play Online
`react-mui`	GitHub	Play Online
`react-storybook`	GitHub	Play Online
`react-testing-lib-msw`	GitHub	Play Online
`react-testing-lib`	GitHub	Play Online
`react`	GitHub	Play Online
`ruby`	GitHub	Play Online
`solid`	GitHub	Play Online
`svelte`	GitHub	Play Online
`vitesse`	GitHub	Play Online
`vue-jsx`	GitHub	Play Online
`vue`	GitHub	Play Online
`vue2`	GitHub	Play Online

Projetos usando Vitest

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):

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 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.

Primeiros Passos ​

Visão Geral ​

Experimentando o Vitest Online ​

Adicionando o Vitest ao seu Projeto ​

Escrevendo Testes ​

Configurando o Vitest ​

Suporte a Workspaces (Espaços de Trabalho) ​

Interface de Linha de Comando (CLI) ​

Integrações com IDE ​

Exemplos ​

Projetos usando Vitest ​

Usando Commits Não Lançados ​

Comunidade ​

Primeiros Passos

Visão Geral

Experimentando o Vitest Online

Adicionando o Vitest ao seu Projeto

Escrevendo Testes

Configurando o Vitest

Suporte a Workspaces (Espaços de Trabalho)

Interface de Linha de Comando (CLI)

Integrações com IDE

Exemplos

Projetos usando Vitest

Usando Commits Não Lançados

Comunidade