APIs Avançadas

WARNING

Este guia lista APIs avançadas para executar testes usando um script Node.js. Se você deseja apenas executar testes, provavelmente não precisará dele. Ele é voltado principalmente para desenvolvedores de bibliotecas.

Você pode importar qualquer método do ponto de entrada vitest/node.

startVitest

function startVitest(
  mode: VitestRunMode,
  cliFilters: string[] = [],
  options: CliOptions = {},
  viteOverrides?: ViteUserConfig,
  vitestOptions?: VitestOptions
): Promise<Vitest>;

Você pode iniciar a execução de testes Vitest usando a API Node:

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest.close();

A função startVitest retorna uma instância Vitest caso os testes possam ser iniciados.

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

Se o modo de observação estiver ativado e o terminal suportar TTY, o Vitest registrará atalhos no console.

Você pode passar uma lista de filtros como o segundo argumento. O Vitest executará apenas os testes que contiverem pelo menos uma das strings fornecidas em seus caminhos de arquivo.

Além disso, você pode usar o terceiro argumento para passar argumentos CLI, os quais substituirão quaisquer opções de configuração de teste. Alternativamente, você pode passar a configuração completa do Vite como o quarto argumento, a qual terá precedência sobre quaisquer outras opções definidas pelo usuário.

Após a execução dos testes, você pode obter os resultados da API state.getTestModules:

import type { TestModule } from 'vitest/node';

const vitest = await startVitest('test');

console.log(vitest.state.getTestModules()); // [TestModule]

TIP

O guia "Executando Testes" contém um exemplo de uso.

createVitest

function createVitest(
  mode: VitestRunMode,
  options: CliOptions,
  viteOverrides: ViteUserConfig = {},
  vitestOptions: VitestOptions = {}
): Promise<Vitest>;

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

import { createVitest } from 'vitest/node';

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

TIP

O guia "Executando Testes" contém um exemplo de uso.

resolveConfig

function resolveConfig(
  options: UserConfig = {},
  viteOverrides: ViteUserConfig = {}
): Promise<{
  vitestConfig: ResolvedConfig;
  viteConfig: ResolvedViteConfig;
}>;

Este método resolve a configuração utilizando parâmetros personalizados. Caso nenhum parâmetro seja fornecido, o root será process.cwd().

import { resolveConfig } from 'vitest/node';

// vitestConfig contém apenas propriedades "test" resolvidas
const { vitestConfig, viteConfig } = await resolveConfig({
  mode: 'custom',
  configFile: false,
  resolve: {
    conditions: ['custom'],
  },
  test: {
    setupFiles: ['/my-setup-file.js'],
    pool: 'threads',
  },
});

INFO

Devido à forma como o createServer do Vite funciona, o Vitest precisa resolver a configuração no hook configResolve do plugin. Portanto, este método não é de fato usado internamente e é exposto exclusivamente como uma API pública.

Caso você passe a configuração para as APIs startVitest ou createVitest, o Vitest ainda resolverá a configuração novamente.

WARNING

O resolveConfig não resolve projetos. Para resolver as configurações de projetos, o Vitest precisa de um servidor Vite em execução.

Note também que viteConfig.test não será totalmente resolvido. Se você precisar da configuração do Vitest, use vitestConfig em vez disso.

parseCLI

function parseCLI(
  argv: string | string[],
  config: CliParseOptions = {}
): {
  filter: string[];
  options: CliOptions;
};

Você pode usar este método para analisar argumentos CLI. Ele aceita uma string (com argumentos separados por um único espaço) ou um array de strings de argumentos CLI no mesmo formato que o Vitest CLI utiliza. Ele retorna um filtro e opções que você pode passar posteriormente para os métodos createVitest ou startVitest.

import { parseCLI } from 'vitest/node';

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

result.options;
// {
//   coverage: { enabled: true },
//   browser: { name: 'chrome', enabled: true }
// }

result.filter;
// ['./files.ts']