API do Node

WARNING

O Vitest expõe uma API experimental privada. Alterações que quebrem a compatibilidade podem não seguir o SemVer, portanto, fixe a versão do Vitest ao utilizá-la.

startVitest

Você pode iniciar a execução de 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 uma instância de Vitest se os testes puderem ser iniciados com sucesso. Retorna undefined se uma das seguintes condições ocorrer:

• O Vitest não encontrou o pacote vite (geralmente instalado junto com o Vitest).
• Se a cobertura de código estiver ativada e o modo de execução (run mode) for "test", mas o pacote de cobertura não estiver instalado (@vitest/coverage-v8 ou @vitest/coverage-istanbul).
• Se o pacote de ambiente 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 como 1.

Se o modo de observação não estiver habilitado, o Vitest chamará o método close.

Se o modo de observação estiver habilitado e o terminal suportar TTY, o Vitest exibirá atalhos do console.

Você pode passar uma lista de filtros como um segundo argumento. O Vitest executará apenas os testes cujos caminhos contenham pelo menos uma das strings passadas.

Além disso, você pode usar o terceiro argumento para passar argumentos de linha de comando (CLI), que substituirão quaisquer opções de configuração de teste.

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

Após executar os testes, você pode obter os resultados através da API state.getFiles:

const vitest = await startVitest('test');

console.log(vitest.state.getFiles()); // [{ type: 'file', ... }]

Desde o Vitest 2.1, recomenda-se usar a API de "Tarefas Reportadas" (Reported Tasks) juntamente com state.getFiles. No futuro, o Vitest retornará esses objetos diretamente:

const vitest = await startVitest('test');

const [fileTask] = vitest.state.getFiles();
const testFile = vitest.state.getReportedEntity(fileTask);

createVitest

Você pode criar uma instância do Vitest usando a função createVitest. Ela retorna a mesma instância de 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 os argumentos da linha de comando (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 posteriormente passar 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. Pode ser:

• test ao executar testes de tempo de execução.
• benchmark ao executar benchmarks.

mode

test

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

benchmark

O modo de benchmark executa funções bench e lançará um erro ao encontrar 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 arquivos de teste.

provide

O Vitest expõe o método provide, que serve como um atalho para vitest.getCoreWorkspaceProject().provide. Com este método, você pode passar valores da thread principal para os testes. Todos os valores são verificados com structuredClone antes de serem armazenados, mas os próprios valores não são clonados.

Para receber os valores no teste, você precisa importar o método inject do ponto de entrada vitest:

import { inject } from 'vitest';
const port = inject('wsPort'); // 3000

Para uma melhor segurança de tipos, recomendamos que você estenda o tipo de ProvidedContext:

import { createVitest } from 'vitest/node';

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

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

WARNING

Tecnicamente, provide é um método de WorkspaceProject, então ele é limitado ao projeto específico. No entanto, todos os projetos herdam os valores do projeto core, o que faz de vitest.provide uma maneira universal de passar valores para os testes.

TIP

Este método também está disponível para arquivos de configuração global para casos em que você não deseja usar a API pública:

export default function setup({ provide }) {
  provide('wsPort', 3000);
}