Primeiros Passos

Visão Geral

Vitest (pronuncia-se "ví-test") é um framework de testes de última geração desenvolvido com Vite.

Você pode saber 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. No entanto, não requer a instalação de nada em sua máquina.

Adicionando 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 que você instale uma instância do vitest em seu package.json, utilizando 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 irá executar o comando especificado. Por padrão, o npx primeiro verificará se o comando existe nos binários do projeto local. Se não for encontrado lá, o npx procurará no $PATH do sistema e o executará se encontrado. Se o comando não for encontrado em nenhum dos locais, o npx o instalará em um local temporário antes da execução.

Escrevendo Testes

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

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

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 testes devem ter .test. ou .spec. no nome do arquivo.

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

json

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

Por fim, execute npm run test, yarn test ou pnpm test, conforme seu gerenciador de pacotes. O Vitest imprimirá a seguinte 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 test runner.

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

Configurando o Vitest

Uma das principais vantagens do Vitest é a sua configuração unificada com o Vite. Se presente, o vitest lerá o arquivo vite.config.ts raiz para usar os plugins e a configuração do seu aplicativo Vite. Por exemplo, as configurações de resolve.alias e plugins do Vite funcionarão automaticamente. Caso deseje uma configuração diferente durante os testes, você pode:

Criar vitest.config.ts, que terá maior prioridade
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á definida como test se não for substituída) 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. A extensão .json não é suportada.

Se você não estiver utilizando o Vite como ferramenta de build, pode configurar o Vitest através da propriedade test em seu arquivo de configuração:

import { defineConfig } from 'vitest/config';

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

TIP

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

Caso você já esteja utilizando 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 triple-slash no topo do seu arquivo de configuração.

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

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

O <reference types="vitest" /> deixará de funcionar na próxima versão principal, 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 as opções aqui.
  },
});

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

WARNING

Se você optar por ter dois arquivos de configuração separados para Vite e Vitest, assegure-se de definir as mesmas opções do Vite no arquivo de configuração do Vitest, pois ele sobrescreverá o arquivo do Vite, em vez de estendê-lo. Você também pode utilizar o método mergeConfig das entradas vite ou vitest/config para combinar 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()],
});

Entretanto, recomendamos utilizar o mesmo arquivo para Vite e Vitest, ao invés de criar dois arquivos separados.

Suporte a Projetos

Execute diferentes configurações de projeto dentro do mesmo projeto utilizando Projetos de Teste. Você pode especificar uma lista de arquivos e pastas que definem seus projetos no arquivo vitest.config.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      // você pode usar uma lista de padrões glob para definir seus projetos
      // Vitest espera uma lista de arquivos de configuração
      // ou diretórios que contenham 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 um projeto onde o Vitest está instalado, você pode utilizar o binário vitest em seus scripts npm ou executá-lo diretamente com npx vitest. A seguir, 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 única vez, sem observar alterações nos arquivos, utilize vitest run. Você pode especificar opções adicionais da CLI como --port ou --https. Para uma lista completa de opções da CLI, execute npx vitest --help em seu projeto.

Para mais informações sobre a Interface de Linha de Comando, consulte.

Instalação Automática de Dependências

O Vitest irá solicitar que você instale determinadas dependências, caso ainda não estejam instaladas. Você pode desativar esse comportamento configurando a variável de ambiente VITEST_SKIP_INSTALL_CHECKS=1.

Integrações com IDE

Além disso, disponibilizamos uma extensão oficial para o Visual Studio Code, que aprimora sua experiência de teste com o Vitest.

Instalar do VS Code Marketplace

Para mais informações sobre Integrações com IDE, consulte.

Exemplos

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

Projetos usando Vitest

Usando Commits Não Lançados

Cada commit no ramo principal e um PR com a tag cr-tracked são publicados em pkg.pr.new. Você pode instalá-lo com npm i https://pkg.pr.new/vitest@{commit}.

Se você quiser testar sua própria modificação localmente, pode compilá-la e linká-la 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 # use seu gerenciador de pacotes preferido para vincular globalmente

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 seu gerenciador de pacotes).

Comunidade

Se você tiver dúvidas ou precisar de ajuda, entre em contato com a comunidade pelo Discord ou nas Discussões do GitHub.

Primeiros Passos ​

Visão Geral ​

Experimentando o Vitest Online ​

Adicionando Vitest ao Seu Projeto ​

Escrevendo Testes ​

Configurando o Vitest ​

Suporte a Projetos ​

Interface de Linha de Comando ​

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

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 Vitest ao Seu Projeto

Escrevendo Testes

Configurando o Vitest

Suporte a Projetos

Interface de Linha de Comando

Instalação Automática de Dependências

Integrações com IDE

Exemplos

Projetos usando Vitest

Usando Commits Não Lançados

Comunidade