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.js') ou import index from './index.js')), 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
-r, --root <caminho>	Caminho raiz
-c, --config <caminho>	Caminho para o arquivo de configuração
-u, --update	Atualizar snapshot
-w, --watch	Habilitar o modo de observação (watch)
-t, --testNamePattern <padrão>	Executar testes com nomes completos que correspondam ao padrão regexp especificado
--dir <caminho>	Diretório base para procurar os arquivos de teste
--ui	Habilitar a interface do usuário (UI)
--open	Abrir a interface do usuário automaticamente (padrão: !process.env.CI)
--api.port [porta]	Especificar a porta do servidor. Observe que, se a porta já estiver em uso, o Vite tentará automaticamente a próxima porta disponível, portanto, esta pode não ser a porta real que o servidor acaba ouvindo. Se verdadeiro, será definido como 51204
--api.host [host]	Especificar quais endereços IP o servidor deve ouvir. Defina isso como 0.0.0.0 ou true para ouvir em todos os endereços, incluindo endereços LAN e públicos
--api.strictPort	Definir como verdadeiro para sair se a porta já estiver em uso, em vez de tentar automaticamente a próxima porta disponível
--silent	Silenciar a saída do console dos testes
--hideSkippedTests	Ocultar logs para testes ignorados
--reporter <nome>	Especificar os reporters
--outputFile <nome_do_arquivo/-s>	Escrever os resultados dos testes em um arquivo quando o reporter suportado também for especificado, usar a notação de ponto do cac para saídas individuais de múltiplos reporters (exemplo: --outputFile.tap=./tap.txt)
--coverage.all	Se deve incluir todos os arquivos, incluindo os não testados, no relatório
--coverage.provider <nome>	Selecionar a ferramenta para coleta de cobertura, os valores disponíveis são: "v8", "istanbul" e "custom"
--coverage.enabled	Habilita a coleta de cobertura. Pode ser substituído usando a opção --coverage CLI (padrão: false)
--coverage.include <padrão>	Arquivos incluídos na cobertura como padrões glob. Pode ser especificado mais de uma vez ao usar vários padrões (padrão: **)
--coverage.exclude <padrão>	Arquivos a serem excluídos na cobertura. Pode ser especificado mais de uma vez ao usar várias extensões (padrão: Visite coverage.exclude)
--coverage.extension <extensão>	Extensão a ser incluída na cobertura. Pode ser especificado mais de uma vez ao usar várias extensões (padrão: [".js", ".cjs", ".mjs", ".ts", ".mts", ".cts", ".tsx", ".jsx", ".vue", ".svelte"])
--coverage.clean	Limpar os resultados da cobertura antes de executar os testes (padrão: true)
--coverage.cleanOnRerun	Limpar o relatório de cobertura na reexecução de observação (padrão: true)
--coverage.reportsDirectory <caminho>	Diretório para gravar o relatório de cobertura (padrão: ./coverage)
--coverage.reporter <nome>	Reporters de cobertura para usar. Visite coverage.reporter para mais informações (padrão: ["text", "html", "clover", "json"])
--coverage.reportOnFailure	Gerar relatório de cobertura mesmo quando os testes falham (padrão: false)
--coverage.allowExternal	Coletar cobertura de arquivos fora da raiz do projeto (padrão: false)
--coverage.skipFull	Não mostrar arquivos com 100% de cobertura de declaração, ramo e função (padrão: false)
--coverage.thresholds.100	Atalho para definir todos os limites de cobertura para 100 (padrão: false)
--coverage.thresholds.perFile	Verificar limites para cada arquivo. Consulte --coverage.thresholds.lines, --coverage.thresholds.functions, --coverage.thresholds.branches e --coverage.thresholds.statements para os limites reais (padrão: false)
--coverage.thresholds.autoUpdate	Atualizar os valores de limite: "lines", "functions", "branches" e "statements" para o arquivo de configuração quando a cobertura atual estiver acima dos limites configurados (padrão: false)
--coverage.thresholds.lines <número>	Limite para linhas. Visite istanbuljs para mais informações. Esta opção não está disponível para provedores personalizados
--coverage.thresholds.functions <número>	Limite para funções. Visite istanbuljs para mais informações. Esta opção não está disponível para provedores personalizados
--coverage.thresholds.branches <número>	Limite para ramificações. Visite istanbuljs para mais informações. Esta opção não está disponível para provedores personalizados
--coverage.thresholds.statements <número>	Limite para declarações. Visite istanbuljs para mais informações. Esta opção não está disponível para provedores personalizados
--coverage.ignoreClassMethods <nome>	Array de nomes de métodos de classe para ignorar na cobertura. Visite istanbuljs para mais informações. Esta opção está disponível apenas para os provedores istanbul (default: [])
--coverage.processingConcurrency <number>	Limite de simultaneidade usado ao processar os resultados da cobertura. (padrão mínimo entre 20 e o número de CPUs)
--coverage.customProviderModule <path>	Especifica o nome ou caminho do módulo para o módulo provedor de cobertura personalizado. Visite Custom Coverage Provider para obter mais informações. Esta opção está disponível apenas para provedores customizados
--coverage.watermarks.statements <watermarks>	Marcas d'água alta e baixa para statements no formato de <alto>,<baixo>
--coverage.watermarks.lines <watermarks>	Marcas d'água alta e baixa para linhas no formato de <alto>,<baixo>
--coverage.watermarks.branches <watermarks>	Marcas d'água alta e baixa para branches no formato de <alto>,<baixo>
--coverage.watermarks.functions <watermarks>	Marcas d'água alta e baixa para funções no formato de <alto>,<baixo>
--mode <nome>	Substituir o modo Vite (padrão: test ou benchmark)
--workspace <caminho>	Caminho para um arquivo de configuração do workspace
--isolate	Executar cada arquivo de teste isoladamente. Para desabilitar o isolamento, use --no-isolate (padrão: true)
--globals	Injetar APIs globalmente
--dom	Simular a API do navegador com happy-dom
--browser.enabled	Executar testes no navegador. Equivalente a --browser.enabled (padrão: false)
--browser.name <nome>	Executar todos os testes em um navegador específico. Alguns navegadores estão disponíveis apenas para provedores específicos (consulte --browser.provider). Visite browser.name para mais informações
--browser.headless	Executar o navegador no modo headless (ou seja, sem abrir a GUI (Interface Gráfica do Usuário)). Se você estiver executando o Vitest em CI, ele será habilitado por padrão (padrão: process.env.CI)
--browser.api.port [porta]	Especifique a porta do servidor. Observe que se a porta já estiver em uso, o Vite tentará automaticamente a próxima porta disponível, então esta pode não ser a porta real que o servidor termina escutando. Se verdadeiro, será definido para 63315
--browser.api.host [host]	Especifique quais endereços IP o servidor deve escutar. Defina isso para 0.0.0.0 or true para escutar em todos os endereços, incluindo LAN e endereços públicos
--browser.api.strictPort	Defina como verdadeiro para sair se a porta já estiver em uso, ao invés de tentar automaticamente a próxima porta disponível
--browser.provider <nome>	Provedor utilizado para rodar testes no navegador. Alguns navegadores estão disponíveis apenas para provedores específicos. Pode ser "webdriverio", "playwright", ou o caminho para um provedor customizado. Visite browser.provider para mais informações (default: "webdriverio")
--browser.providerOptions <options>	Opções que são passadas para um provedor de navegador. Visite browser.providerOptions para mais informações
--browser.slowHijackESM	Deixe o Vitest utilizar sua própria resolução de módulo no navegador para habilitar APIs como vi.mock e vi.spyOn. Visite browser.slowHijackESM para mais informações (default: false)
--browser.isolate	Execute cada arquivo de teste do navegador isoladamente. Para desabilitar o isolamento, use --browser.isolate=false (padrão: true)
--browser.fileParallelism	Deve todos os arquivos de teste rodar em paralelo. Use --browser.file-parallelism=false para desabilitar (default: mesmo que --file-parallelism)
--pool <pool>	Especifica o pool, se não estiver rodando no navegador (default: threads)
--poolOptions.threads.isolate	Isolar testes no pool de threads (default: true)
--poolOptions.threads.singleThread	Rodar testes dentro de uma única thread (default: false)
--poolOptions.threads.maxThreads <workers>	Número máximo de threads para rodar testes em
--poolOptions.threads.minThreads <workers>	Número mínimo de threads para rodar testes em
--poolOptions.threads.useAtomics	Use Atomics para sincronizar threads. Isto pode melhorar a performance em alguns casos, mas pode causar falhas de segmentação em versões antigas do Node (default: false)
--poolOptions.vmThreads.isolate	Isolar testes no pool de threads (default: true)
--poolOptions.vmThreads.singleThread	Rodar testes dentro de uma única thread (default: false)
--poolOptions.vmThreads.maxThreads <workers>	Número máximo de threads para rodar testes em
--poolOptions.vmThreads.minThreads <workers>	Número mínimo de threads para rodar testes em
--poolOptions.vmThreads.useAtomics	Use Atomics para sincronizar threads. Isto pode melhorar a performance em alguns casos, mas pode causar falhas de segmentação em versões antigas do Node (default: false)
--poolOptions.vmThreads.memoryLimit <limit>	Limite de memória para o pool de threads VM. Se você ver vazamentos de memória, tente ajustar este valor.
--poolOptions.forks.isolate	Isolar testes no pool de forks (default: true)
--poolOptions.forks.singleFork	Rodar testes dentro de um único child_process (default: false)
--poolOptions.forks.maxForks <workers>	Número máximo de processos para rodar testes em
--poolOptions.forks.minForks <workers>	Número mínimo de processos para rodar testes em
--poolOptions.vmForks.isolate	Isolar testes no pool de forks (default: true)
--poolOptions.vmForks.singleFork	Rodar testes dentro de um único child_process (default: false)
--poolOptions.vmForks.maxForks <workers>	Número máximo de processos para rodar testes em
--poolOptions.vmForks.minForks <workers>	Número mínimo de processos para rodar testes em
--poolOptions.vmForks.memoryLimit <limit>	Limite de memória para o pool de forks VM. Se você ver vazamentos de memória, tente ajustar este valor.
--fileParallelism	Se todos os arquivos de teste devem ser executados em paralelo. Use --no-file-parallelism para desativar (padrão: true)
--maxWorkers <workers>	Número máximo de workers para executar testes em
--minWorkers <workers>	Número mínimo de workers para executar testes em
--environment <nome>	Especificar o ambiente do runner, se não estiver executando no navegador (padrão: node)
--passWithNoTests	Passar quando nenhum teste for encontrado
--logHeapUsage	Mostrar o tamanho do heap para cada teste ao executar no node
--allowOnly	Permitir testes e suítes que são marcados como only (padrão: !process.env.CI)
--dangerouslyIgnoreUnhandledErrors	Ignorar quaisquer erros não tratados que ocorram
--shard <shards>	Fragmento do conjunto de testes para executar em um formato de <index>/<count>
--changed [desde]	Executar testes que são afetados pelos arquivos alterados (padrão: false)
--sequence.shuffle.files	Executar arquivos em ordem aleatória. Testes de longa duração não começarão mais cedo se você habilitar esta opção. (padrão: false)
--sequence.shuffle.tests	Executar testes em ordem aleatória (padrão: false)
--sequence.concurrent	Fazer os testes serem executados em paralelo (padrão: false)
--sequence.seed <seed>	Defina a semente de randomização. Esta opção não terá efeito se --sequence.shuffle for falso. Visite a página "Random Seed" para mais informações
--sequence.hooks <order>	Altera a ordem em que os hooks são executados. Os valores aceitos são: "stack", "list" e "parallel". Visite sequence.hooks para mais informações (padrão: "parallel")
--sequence.setupFiles <order>	Altera a ordem em que os arquivos de setup são executados. Os valores aceitos são: "list" e "parallel". Se definido como "list", executará os arquivos de setup na ordem em que são definidos. Se definido como "parallel", executará os arquivos de setup em paralelo (padrão: "parallel")
--inspect [[host:]porta]	Habilitar o inspetor do Node.js (padrão: 127.0.0.1:9229)
--inspectBrk [[host:]porta]	Habilitar o inspetor do Node.js e interromper antes do início do teste
--testTimeout <timeout>	Timeout padrão de um teste em milissegundos (padrão: 5000)
--hookTimeout <timeout>	Timeout padrão do hook em milissegundos (padrão: 10000)
--bail <número>	Interromper a execução do teste quando um determinado número de testes falharem (padrão: 0)
--retry <vezes>	Tentar novamente o teste um número específico de vezes se ele falhar (padrão: 0)
--diff <caminho>	Caminho para uma configuração de diff que será usada para gerar a interface diff
--exclude <glob>	Globs de arquivo adicionais a serem excluídos do teste
--expandSnapshotDiff	Mostra o diff completo quando um snapshot falha
--disableConsoleIntercept	Desabilita a interceptação automática de logs do console (padrão: false)
--typecheck.enabled	Habilitar a verificação de tipo junto com os testes (padrão: false)
--typecheck.only	Execute apenas os testes de verificação de tipo. Isso habilita automaticamente a verificação de tipo (padrão: false)
--typecheck.checker <name>	Especifique o verificador de tipo a ser usado. Os valores disponíveis são: "tcs" e "vue-tsc" e um caminho para um executável (padrão: "tsc")
--typecheck.allowJs	Permite que arquivos JavaScript sejam verificados por tipo. Por padrão, usa o valor de tsconfig.json
--typecheck.ignoreSourceErrors	Ignorar erros de tipo de arquivos de origem
--typecheck.tsconfig <path>	Caminho para um arquivo tsconfig personalizado
--project <name>	O nome do projeto para executar se você estiver usando o recurso de espaço de trabalho do Vitest. Isso pode ser repetido para vários projetos: --project=1 --project=2. Você também pode filtrar projetos usando curingas como --project=packages*
--slowTestThreshold <threshold>	Limite em milissegundos para um teste ser considerado lento (default: 300)
--teardownTimeout <timeout>	Timeout padrão de uma função de teardown em milissegundos (default: 10000)
--maxConcurrency <number>	Número máximo de testes concorrentes em um conjunto (default: 5)
--run	Desabilitar o modo de observação
--segfaultRetry <times>	Tentar novamente o conjunto de testes se ele falhar devido a uma falha de segmentação (padrão: true)
--no-color	Remove cores da saída do console
--clearScreen	Limpa a tela do terminal ao re-executar os testes durante o modo de observação (padrão: true)
--standalone	Inicia o Vitest sem executar testes. Os filtros de arquivos serão ignorados, os testes serão executados apenas na alteração (default: false)

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 nas alterações feitas no último commit, você pode usar --changed HEAD~1. Você também pode passar o hash do commit (por exemplo, --changed 09a9920) ou o nome do branch (por exemplo, --changed origin/develop).

  Quando usado com code coverage, o relatório conterá apenas os arquivos relacionados às alterações.

  Se combinado com a opção de configuração forceRerunTriggers, todo o conjunto de testes será executado se pelo menos um dos arquivos listados na lista forceRerunTriggers for alterado. Por padrão, as alterações no arquivo de configuração do Vitest e em package.json sempre executarão novamente todo o conjunto.

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.