API do Node

WARNING

O Vitest expõe uma API privada experimental. Mudanças que quebram a compatibilidade podem não seguir o versionamento semântico (semver). Por isso, é recomendado fixar a versão do Vitest que você está usando.

startVitest

Você pode iniciar a execução dos testes do Vitest usando sua API do Node:

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest?.close();

A função startVitest retorna a instância Vitest se os testes puderem ser iniciados com sucesso. Ela retorna undefined se um dos seguintes eventos ocorrer:

• O Vitest não encontrou o pacote vite (geralmente instalado junto com o Vitest).
• Se a cobertura de código estiver habilitada e o modo de execução for "test", mas o pacote de cobertura não estiver instalado (@vitest/coverage-v8 ou @vitest/coverage-istanbul).
• Se o pacote de ambiente de teste não estiver instalado (jsdom/happy-dom/@edge-runtime/vm).

Se undefined for retornado ou os testes falharem durante a execução, o Vitest define process.exitCode para 1.

Se o modo watch não estiver habilitado, o Vitest chamará o método close().

Se o modo watch estiver habilitado e o terminal suportar TTY, o Vitest registrará atalhos no console.

Você pode passar uma lista de filtros como segundo argumento. O Vitest executará apenas os testes que contiverem pelo menos uma das strings passadas no caminho do arquivo.

Adicionalmente, você pode usar o terceiro argumento para passar argumentos de linha de comando (CLI), que substituirão quaisquer opções de configuração de testes.

Alternativamente, você pode passar a configuração completa do Vite como o quarto argumento, que terá precedência sobre quaisquer outras opções definidas pelo usuário.

createVitest

Você pode criar a instância do Vitest usando a função createVitest. Ela retorna a mesma instância Vitest que startVitest, mas não inicia os testes e não valida os pacotes instalados.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test', {
  watch: false,
});

parseCLI

Você pode usar este método para analisar argumentos da CLI. Ele aceita uma string (onde os argumentos são separados por um único espaço) ou um array de strings de argumentos da CLI no mesmo formato que a CLI do Vitest usa. Ele retorna um filtro e options que você pode passar posteriormente para os métodos createVitest ou startVitest.

import { parseCLI } from 'vitest/node';

parseCLI('vitest ./files.ts --coverage --browser=chrome');

Vitest

A instância do Vitest requer o modo de teste atual, que pode ser:

• test ao executar testes de runtime
• benchmark ao executar benchmarks

mode

test

O modo de teste executará apenas as funções test ou it, lançando um erro quando bench for encontrado. Este modo usa as opções include e exclude na configuração para encontrar arquivos de teste.

benchmark

O modo de benchmark executa as funções bench, lançando um erro quando encontra test ou it. Este modo usa as opções benchmark.include e benchmark.exclude na configuração para encontrar arquivos de benchmark.

start

Você pode iniciar a execução de testes ou benchmarks com o método start. Você pode passar um array de strings para filtrar os arquivos de teste.