API Vitest

A instância Vitest exige o modo de teste atual. Pode ser um dos seguintes:

test ao executar testes em tempo de execução
benchmark ao executar benchmarks experimental

Novo no Vitest 3

O Vitest 3 está mais próximo de estabilizar a API pública. Para isso, descontinuamos e removemos alguns dos métodos públicos anteriores da classe Vitest. Essas APIs tornaram-se privadas:

configOverride (use setGlobalTestNamePattern ou enableSnapshotUpdate)
coverageProvider
filenamePattern
runningPromise
closingPromise
isCancelling
coreWorkspaceProject
resolvedProjects
_browserLastPort
_options
reporters
vitenode
runner
pool
setServer
_initBrowserServers
rerunTask
changeProjectName
changeNamePattern
changeFilenamePattern
rerunFailed
_createRootProject (renomeado para _ensureRootProject, mas ainda privado)
filterTestsBySource (isso foi movido para a nova instância interna vitest.specifications)
runFiles (use runTestSpecifications em vez disso)
onAfterSetServer

Essas APIs foram descontinuadas:

invalidates
changedTests (use onFilterWatchedSpecification em vez disso)
server (use vite em vez disso)
getProjectsByTestFile (use getModuleSpecifications em vez disso)
getFileWorkspaceSpecs (use getModuleSpecifications em vez disso)
getModuleProjects (filtre por this.projects você mesmo)
updateLastChanged (renomeado para invalidateFile)
globTestSpecs (use globTestSpecifications em vez disso)
globTestFiles (use globTestSpecifications em vez disso)
listFile (use getRelevantTestSpecifications em vez disso)

mode

test

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

benchmark experimental

O modo de benchmark invoca funções bench e lança um erro ao encontrar test ou it. Este modo utiliza as opções benchmark.include e benchmark.exclude da configuração para encontrar arquivos de benchmark.

config

A configuração raiz e global. Se os projetos forem definidos, eles farão referência a ela como globalConfig.

WARNING

Esta é a configuração do Vitest, ela não estende a configuração do Vite. Ela contém apenas valores resolvidos da propriedade test.

vite

Este é um ViteDevServer global.

state experimental

WARNING

state público é uma API em fase experimental (exceto vitest.state.getReportedEntity). Quebras de compatibilidade podem não seguir o SemVer, por favor, fixe a versão do Vitest ao utilizá-lo.

O estado global armazena informações dos testes atuais. Ele usa a mesma API de @vitest/runner por padrão, mas recomendamos usar a API de Tarefas Reportadas em vez disso, ao chamar state.getReportedEntity() na API @vitest/runner:

const task = vitest.state.idMap.get(taskId); // old API
const testCase = vitest.state.getReportedEntity(task); // new API

No futuro, a API antiga não estará mais disponível.

snapshot

O gerenciador global de snapshots. O Vitest acompanha todos os snapshots usando o método snapshot.add.

Você pode obter o resumo mais recente dos snapshots pela propriedade vitest.snapshot.summary.

cache

Gerenciador de cache que armazena informações dos últimos resultados de teste e estatísticas de arquivos de teste. No próprio Vitest, isso é usado apenas pelo sequenciador padrão para organizar os testes.

projects

Um array de projetos de teste dos projetos do usuário. Se o usuário não os especificar, este array conterá apenas um projeto raiz.

O Vitest garante que sempre haja pelo menos um projeto neste array. Se o usuário especificar um nome --project inexistente, o Vitest lançará um erro antes da definição deste array.

getRootProject

function getRootProject(): TestProject;

Este método retorna o projeto de teste raiz. O projeto raiz geralmente não executa testes e não é incluído em vitest.projects, a menos que o usuário inclua explicitamente a configuração raiz em sua configuração, ou se nenhum projeto for definido.

O objetivo principal do projeto raiz é definir a configuração global. Na verdade, rootProject.config referencia rootProject.globalConfig e vitest.config diretamente:

(rootProject.config === rootProject.globalConfig) === rootProject.vitest.config;

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

O Vitest disponibiliza o método provide, que é um atalho para vitest.getRootProject().provide. Com este método, você pode transmitir valores do thread principal para os testes. Todos os valores são processados 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 tipagem, 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 TestProject, sendo, portanto, limitado ao projeto específico. No entanto, todos os projetos herdam os valores do projeto raiz, o que torna vitest.provide uma maneira universal de transmitir valores para os testes.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Este método retorna o objeto de contexto raiz. Este é um atalho para vitest.getRootProject().getProvidedContext.

getProjectByName

function getProjectByName(name: string): TestProject;

Este método retorna o projeto pelo seu nome. Semelhante a chamar vitest.projects.find.

WARNING

Caso o projeto não exista, este método retornará o projeto raiz. Certifique-se de verificar os nomes novamente para confirmar se o projeto retornado é o que você procura.

Se o usuário não personalizou um nome, o Vitest atribuirá uma string vazia como seu nome.

globTestSpecifications

function globTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Este método constrói novas especificações de teste ao coletar cada teste em todos os projetos com project.globTestFiles. Ele aceita filtros de string para filtrar os arquivos de teste - são os mesmos filtros suportados pela CLI.

Este método armazena automaticamente em cache todas as especificações de teste. Quando você chamar getModuleSpecifications na próxima vez, ele retornará as mesmas especificações, a menos que clearSpecificationsCache tenha sido chamado anteriormente.

WARNING

A partir do Vitest 3, é possível ter várias especificações de teste com o mesmo ID de módulo (caminho do arquivo) se poolMatchGlob possuir vários pools ou se typecheck estiver habilitado. Essa funcionalidade será removida no Vitest 4.

const specifications = await vitest.globTestSpecifications(['my-filter']);
// [TestSpecification{ moduleId: '/tests/my-filter.test.ts' }]
console.log(specifications);

getRelevantTestSpecifications

function getRelevantTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Este método resolve cada especificação de teste ao chamar project.globTestFiles. Ele aceita filtros de string para filtrar os arquivos de teste - são os mesmos filtros suportados pela CLI. Se a flag --changed for especificada, a lista será filtrada para incluir apenas os arquivos alterados. getRelevantTestSpecifications não executa arquivos de teste.

WARNING

Este método pode ser lento porque precisa processar as flags --changed. Não o utilize se você precisar apenas de uma lista de arquivos de teste.

Se você precisa obter a lista de especificações para arquivos de teste conhecidos, use getModuleSpecifications em vez disso.
Se você precisa obter a lista de todos os arquivos de teste possíveis, use globTestSpecifications.

mergeReports

function mergeReports(directory?: string): Promise<TestRunResult>;

Mescla relatórios de múltiplas execuções localizadas no diretório especificado (valor de --merge-reports caso não seja especificado). Este valor também pode ser definido em config.mergeReports (por padrão, ele lerá da pasta .vitest-reports).

Note que o directory sempre será resolvido em relação ao diretório de trabalho.

Este método é chamado automaticamente por startVitest se config.mergeReports estiver definido.

collect

function collect(filters?: string[]): Promise<TestRunResult>;

Executa arquivos de teste sem invocar os callbacks de teste. collect retorna erros não processados e um array de módulos de teste. Ele aceita filtros de string para filtrar os arquivos de teste - são os mesmos filtros suportados pela CLI.

Este método resolve as especificações de teste com base nos valores de include, exclude e includeSource da configuração. Leia mais em project.globTestFiles. Se a flag --changed for especificada, a lista será filtrada para incluir apenas os arquivos alterados.

WARNING

Note que o Vitest não usa análise estática para coletar testes. O Vitest executará cada arquivo de teste isoladamente, assim como executa testes comuns.

Isso torna este método muito lento, a menos que você desabilite o isolamento antes da coleta dos testes.

start

function start(filters?: string[]): Promise<TestRunResult>;

Inicializa os reporters, o provedor de cobertura e executa testes. Este método aceita filtros de string para filtrar os arquivos de teste - são os mesmos filtros suportados pela CLI.

WARNING

Este método não deve ser chamado se vitest.init() também for chamado. Use runTestSpecifications ou rerunTestSpecifications em vez disso, se você precisar executar testes após a inicialização do Vitest.

Este método é chamado automaticamente por startVitest se config.mergeReports e config.standalone não estiverem definidos.

init

function init(): Promise<void>;

Inicializa os reporters e o provedor de cobertura. Este método não executa nenhum teste. Se a flag --watch for especificada, o Vitest ainda executará os testes que foram alterados, mesmo que este método não tenha sido chamado.

Internamente, este método é chamado apenas se a flag --standalone estiver ativada.

WARNING

Este método não deve ser chamado se vitest.start() também for invocado.

Este método é chamado automaticamente por startVitest se config.standalone estiver definido.

getModuleSpecifications

function getModuleSpecifications(moduleId: string): TestSpecification[];

Retorna uma lista de especificações de teste relacionadas ao moduleId. O ID já deve ter sido resolvido para um caminho de arquivo absoluto. Se o ID não corresponder aos padrões include ou includeSource, o array retornado será vazio.

Este método pode retornar especificações já em cache com base no moduleId e pool. Mas observe que project.createSpecification sempre retorna uma nova instância e não é automaticamente armazenada em cache. No entanto, as especificações são automaticamente armazenadas em cache quando runTestSpecifications é chamado.

WARNING

A partir do Vitest 3, este método utiliza um cache para verificar se o arquivo é um teste. Para garantir que o cache não esteja vazio, chame globTestSpecifications pelo menos uma vez.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

O Vitest armazena automaticamente em cache as especificações de teste para cada arquivo quando globTestSpecifications ou runTestSpecifications é chamado. Este método limpa o cache para o arquivo fornecido ou o cache inteiro, dependendo do primeiro argumento.

runTestSpecifications

function runTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Este método executa cada teste com base nas especificações fornecidas. O segundo argumento, allTestsRun, é usado pelo provedor de cobertura para determinar se é necessário instrumentar a cobertura em todos os arquivos na raiz (isso só é relevante se a cobertura estiver habilitada e coverage.all estiver definido como true).

WARNING

Este método não aciona os callbacks onWatcherRerun, onWatcherStart e onTestsRerun. Se você estiver executando novamente os testes devido à alteração do arquivo, considere usar rerunTestSpecifications em vez disso.

rerunTestSpecifications

function rerunTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Este método emite os eventos reporter.onWatcherRerun e onTestsRerun, e então executa os testes com runTestSpecifications. Se não houver erros no processo principal, emitirá o evento reporter.onWatcherStart.

updateSnapshot

function updateSnapshot(files?: string[]): Promise<TestRunResult>;

Atualiza snapshots nos arquivos especificados. Se nenhum arquivo for fornecido, ele atualizará os arquivos com testes falhos e snapshots obsoletos.

collectTests

function collectTests(
  specifications: TestSpecification[]
): Promise<TestRunResult>;

Executa arquivos de teste sem invocar os callbacks de teste. collectTests retorna erros não processados e um array de módulos de teste.

Este método funciona exatamente da mesma forma que collect, mas você precisa fornecer as especificações de teste manualmente.

WARNING

Note que o Vitest não usa análise estática para coletar testes. O Vitest executará cada arquivo de teste isoladamente, assim como executa testes comuns.

Isso torna este método muito lento, a menos que você desabilite o isolamento antes da coleta dos testes.

cancelCurrentRun

function cancelCurrentRun(reason: CancelReason): Promise<void>;

Este método cancelará de forma elegante todos os testes em andamento. Ele aguardará que os testes iniciados sejam concluídos e não executará os testes que estavam programados, mas ainda não foram iniciados.

setGlobalTestNamePattern

function setGlobalTestNamePattern(pattern: string | RegExp): void;

Este método substitui o padrão global de nome de teste.

WARNING

Este método não inicia a execução de testes. Para executar testes com o padrão recém-atualizado, chame runTestSpecifications.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Este método restaura o padrão de nome de teste. Isso significa que o Vitest não ignorará mais nenhum teste.

WARNING

Este método não inicia a execução de testes. Para executar testes sem um padrão, chame runTestSpecifications.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Habilita o modo que permite atualizar snapshots ao executar testes. Cada teste executado após a chamada deste método atualizará os snapshots. Para desativar o modo, chame resetSnapshotUpdate.

WARNING

Este método não inicia a execução de testes. Para atualizar os snapshots, execute os testes com runTestSpecifications.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Desabilita o modo que permite atualizar snapshots ao executar testes. Este método não inicia a execução de testes.

invalidateFile

function invalidateFile(filepath: string): void;

Este método invalida o arquivo do cache de cada projeto. É principalmente útil se você depende do seu próprio monitor, pois o cache do Vite persiste na memória.

DANGER

Se você desativar o monitor do Vitest, mas mantiver o Vitest em execução, é importante limpar manualmente o cache com este método, pois não há como desativar o cache. Este método também invalidará os módulos que importam o arquivo.

import

function import<T>(moduleId: string): Promise<T>

Importa um arquivo usando o carregador de módulos do Vite. O arquivo será transformado pelo Vite usando a configuração global e executado em um contexto separado. Note que moduleId será relativo a config.root.

DANGER

project.import reaproveita o grafo de módulos do Vite, portanto, importar o mesmo módulo usando uma importação regular resultará em um módulo diferente:

import * as staticExample from './example.js';
const dynamicExample = await vitest.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

Internamente, o Vitest usa este método para importar configurações globais, provedores de cobertura personalizados e reporters personalizados, o que significa que todos compartilham o mesmo grafo de módulos, desde que estejam no mesmo servidor Vite.

close

function close(): Promise<void>;

Fecha todos os projetos e seus recursos relacionados. Isso só pode ser chamado uma vez; a promessa de fechamento é mantida em cache até que o servidor seja reiniciado.

exit

function exit(force = false): Promise<void>;

Fecha todos os projetos e finaliza o processo. Se force for definido como true, o processo será finalizado imediatamente após o fechamento dos projetos.

Este método também forçará a chamada de process.exit() se o processo ainda estiver ativo após config.teardownTimeout milissegundos.

shouldKeepServer

function shouldKeepServer(): boolean;

Este método retornará true se o servidor deve permanecer em execução após os testes serem concluídos. Isso geralmente significa que o modo watch estava habilitado.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Registra uma função de tratamento que será chamada quando o servidor for reiniciado devido a uma alteração de configuração.

onCancel

function onCancel(fn: (reason: CancelReason) => Awaitable<void>): void;

Registra uma função de tratamento que será chamada quando a execução do teste for cancelada com vitest.cancelCurrentRun.

onClose

function onClose(fn: () => Awaitable<void>): void;

Registra uma função de tratamento que será chamada quando o servidor for fechado.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Registra uma função de tratamento que será chamada quando os testes forem executados novamente. Os testes podem ser executados novamente quando rerunTestSpecifications é chamado manualmente ou quando um arquivo é alterado e o monitor embutido agenda uma reexecução.

onFilterWatchedSpecification

function onFilterWatchedSpecification(
  fn: (specification: TestSpecification) => boolean
): void;

Registra uma função de tratamento que será chamada quando um arquivo for alterado. Este callback deve retornar true ou false, indicando se o arquivo de teste deve ser executado novamente.

Com este método, você pode integrar-se à lógica padrão do monitor para atrasar ou descartar testes que o usuário não deseja monitorar no momento:

const continuesTests: string[] = [];

myCustomWrapper.onContinuesRunEnabled(testItem =>
  continuesTests.push(item.fsPath)
);

vitest.onFilterWatchedSpecification(specification =>
  continuesTests.includes(specification.moduleId)
);

O Vitest pode criar diferentes especificações para o mesmo arquivo, dependendo das opções pool ou locations, portanto, não se baseie na referência. O Vitest também pode retornar especificações em cache a partir de vitest.getModuleSpecifications - o cache é baseado no moduleId e pool. Observe que project.createSpecification sempre retorna uma nova instância.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Verifica se o nome corresponde com o filtro de projeto atual. Se não existir filtro de projeto, isso sempre retornará true.

Não é possível alterar programaticamente a opção de CLI --project.

API Vitest ​

mode ​

test ​

benchmark experimental ​

config ​

vite ​

state experimental ​

snapshot ​

cache ​

projects ​

getRootProject ​

provide ​

getProvidedContext ​

getProjectByName ​

globTestSpecifications ​

getRelevantTestSpecifications ​

mergeReports ​

collect ​

start ​

init ​

getModuleSpecifications ​

clearSpecificationsCache ​

runTestSpecifications ​

rerunTestSpecifications ​

updateSnapshot ​

collectTests ​

cancelCurrentRun ​

setGlobalTestNamePattern ​

resetGlobalTestNamePattern ​

enableSnapshotUpdate ​

resetSnapshotUpdate ​

invalidateFile ​

import ​

close ​

exit ​

shouldKeepServer ​

onServerRestart ​

onCancel ​

onClose ​

onTestsRerun ​

onFilterWatchedSpecification ​

matchesProjectFilter 3.1.0+ ​

API Vitest

mode

test

benchmark experimental

config

vite

state experimental

snapshot

cache

projects

getRootProject

provide

getProvidedContext

getProjectByName

globTestSpecifications

getRelevantTestSpecifications

mergeReports

collect

start

init

getModuleSpecifications

clearSpecificationsCache

runTestSpecifications

rerunTestSpecifications

updateSnapshot

collectTests

cancelCurrentRun

setGlobalTestNamePattern

resetGlobalTestNamePattern

enableSnapshotUpdate

resetSnapshotUpdate

invalidateFile

import

close

exit

shouldKeepServer

onServerRestart

onCancel

onClose

onTestsRerun

onFilterWatchedSpecification

matchesProjectFilter 3.1.0+