Interface de Linha de Comando

Comandos

vitest

Inicia o Vitest no diretório atual. Entrará automaticamente no modo de observação no ambiente de desenvolvimento e no modo de execução no CI (Integração Contínua).

Você pode passar um argumento adicional como filtro dos arquivos de teste a serem executados. Por exemplo:

vitest foobar

Executará apenas os arquivos de teste que contenham foobar em seu caminho. Este filtro verifica apenas a inclusão e não suporta expressões regulares ou padrões globais.

vitest run

Executa os testes uma única vez, sem o modo de observação.

vitest watch

Executa todos os conjuntos de testes, observando as alterações e reexecutando os testes quando houver mudanças. É o mesmo que chamar vitest sem um argumento. No CI, voltará a executar vitest run.

vitest dev

Sinônimo de vitest watch.

vitest related

Executa apenas os testes que cobrem uma lista de arquivos de código fonte. Funciona com importações estáticas (por exemplo, import('./index.ts') ou import index from './index.ts')), mas não com importações dinâmicas (por exemplo, import(filepath)). Todos os arquivos devem ser relativos à pasta raiz do projeto.

Útil para executar com lint-staged ou na sua configuração de CI.

vitest related /src/index.ts /src/hello-world.js

TIP

Lembre-se de que o Vitest é executado com o modo de observação ativado por padrão. Se você estiver usando ferramentas como lint-staged, passe a opção --run para que o comando possa terminar normalmente.

// .lintstagedrc.js
export default {
  '*.{js,ts}': 'vitest related --run',
};

vitest bench

Executa apenas testes de benchmark que comparam resultados de desempenho.

Opções

Opções
-v, --version	Exibe o número da versão do Vitest.
-r, --root <path>	Define o diretório raiz do projeto.
-c, --config <path>	Caminho para o arquivo de configuração do Vitest.
-u, --update	Atualiza os snapshots.
-w, --watch	Ativa o modo de observação inteligente e instantâneo.
-t, --testNamePattern <pattern>	Executa testes cujos nomes completos correspondam ao padrão especificado.
--dir <path>	Diretório base para procurar os arquivos de teste.
--ui	Ativa a interface do usuário (UI) do Vitest.
--open	Abre a interface do usuário automaticamente se estiver habilitada.
--api [api]	Disponibiliza a API, com opções disponíveis: --api.port <port>, --api.host [host] e --api.strictPort.
--threads	Habilita o uso de threads para execução dos testes.
--single-thread	Executa os testes em uma única thread. Requer --threads.
--experimental-vm-threads	Executa testes em um pool de workers usando isolamento de VM (Máquina Virtual).
--experimental-vm-worker-memory-limit	Define o limite máximo de memória permitido para um worker. Quando atingido, um novo worker será criado.
--silent	Suprime a saída do console dos testes.
--isolate	Isola o ambiente para cada arquivo de teste.
--reporter <name>	Seleciona o relator (reporter) de resultados: default, verbose, dot, junit, json ou um caminho para um relator personalizado.
--outputFile <filename/-s>	Escreve os resultados dos testes em um arquivo quando a opção --reporter=json ou --reporter=junit é especificada. Via notação de ponto do cac, você pode especificar saídas individuais para vários relatores.
--coverage	Habilita o relatório de cobertura de código.
--run	Desativa o modo de observação.
--mode	Substitui o modo do Vite.
--mode <name>	Substitui o modo do Vite pelo nome especificado.
--globals	Injeta as APIs do Vitest globalmente.
--dom	Simula a API do navegador com happy-dom.
--browser [options]	Executa testes no navegador.
--environment <env>	Define o ambiente de execução dos testes.
--passWithNoTests	Considera a execução como bem-sucedida mesmo quando nenhum teste é encontrado.
--logHeapUsage	Mostra o tamanho do heap (memória alocada) para cada teste.
--allowOnly	Permite a execução de apenas testes e suítes marcados com .only.
--dangerouslyIgnoreUnhandledErrors	Ignora quaisquer erros não tratados que ocorram durante a execução dos testes. Use com cautela!
--changed [since]	Executa testes apenas para arquivos alterados. Veja docs.
--shard <shard>	Executa testes em um shard (fragmento) especificado. Veja docs.
--sequence	Define a ordem de execução dos testes. Use notação de ponto do cac para especificar opções (por exemplo, use --sequence.shuffle para executar os testes em ordem aleatória ou --sequence.shuffle --sequence.seed SEED_ID para executar uma ordem específica).
--no-color	Remove as cores da saída do console.
--inspect	Habilita o inspetor do Node.js para depuração.
--inspect-brk	Ativa o inspetor do Node.js com breakpoint na inicialização.
--bail <number>	Interrompe a execução dos testes quando o número especificado de testes falhar.
--retry <times>	Repete o teste um número específico de vezes se ele falhar.
-h, --help	Exibe as opções de linha de comando disponíveis.

TIP

O Vitest suporta tanto camelCase quanto kebab-case para argumentos de linha de comando. Por exemplo, --passWithNoTests e --pass-with-no-tests funcionarão (as exceções são --no-color e --inspect-brk).

O Vitest também suporta diferentes maneiras de especificar o valor: --reporter dot e --reporter=dot são ambos válidos.

Se a opção suportar um array de valores, passe a opção várias vezes:

vitest --reporter=dot --reporter=default

Opções booleanas podem ser negadas com o prefixo no-. Especificar o valor como false também funciona:

vitest --no-api
vitest --api=false

changed

• Tipo: boolean | string

• Padrão: false

  Executa testes apenas para arquivos alterados. Se nenhum valor for fornecido, ele executará testes em alterações não commitadas (incluindo staged e unstaged).

  Para executar testes em alterações feitas no último commit, use --changed HEAD~1. Você também pode passar o hash do commit ou o nome da branch.

  Se combinado com a opção de configuração forceRerunTriggers, ele executará todo o conjunto de testes se uma correspondência for encontrada.

shard

• Tipo: string

• Padrão: desabilitado

  Fragmento (shard) do conjunto de testes a ser executado no formato <index>/<count>, onde:

  • count é um inteiro positivo, representando o número total de partes em que os testes foram divididos.
  • index é um inteiro positivo, representando o índice da parte a ser executada (começando em 1).

  Este comando dividirá todos os testes em count partes iguais e executará apenas os testes que pertencem à parte index. Por exemplo, para dividir seu conjunto de testes em três partes, use:

  vitest run --shard=1/3
  vitest run --shard=2/3
  vitest run --shard=3/3

WARNING

Esta opção não pode ser usada com --watch habilitado.