API di Vitest

L'istanza di Vitest opera in una specifica modalità di test, che può assumere i seguenti valori:

• test: quando vengono eseguiti test di runtime.
• benchmark: quando si eseguono benchmark sperimentale.

Novità in Vitest 3

Vitest 3 si sta avvicinando alla stabilizzazione della sua API pubblica. Per raggiungere questo obiettivo, abbiamo deprecato e rimosso alcuni dei metodi precedentemente pubblici della classe Vitest. Le seguenti API sono ora private:

• configOverride (utilizzare setGlobalTestNamePattern o enableSnapshotUpdate)
• coverageProvider
• filenamePattern
• runningPromise
• closingPromise
• isCancelling
• coreWorkspaceProject
• resolvedProjects
• _browserLastPort
• _options
• reporters
• vitenode
• runner
• pool
• setServer
• _initBrowserServers
• rerunTask
• changeProjectName
• changeNamePattern
• changeFilenamePattern
• rerunFailed
• _createRootProject (rinominato in _ensureRootProject, ma rimane privato)
• filterTestsBySource (spostato nella nuova istanza interna vitest.specifications)
• runFiles (utilizzare runTestSpecifications invece)
• onAfterSetServer

Le seguenti API sono state deprecate:

• invalidates
• changedTests (utilizzare onFilterWatchedSpecification invece)
• server (utilizzare vite invece)
• getProjectsByTestFile (utilizzare getModuleSpecifications invece)
• getFileWorkspaceSpecs (utilizzare getModuleSpecifications invece)
• getModuleProjects (filtrare da this.projects manualmente)
• updateLastChanged (rinominato in invalidateFile)
• globTestSpecs (utilizzare globTestSpecifications invece)
• globTestFiles (utilizzare globTestSpecifications invece)
• listFile (utilizzare getRelevantTestSpecifications invece)

mode

test

La modalità test eseguirà solo le funzioni definite con test o it e genererà un errore se incontra bench. Questa modalità utilizza le opzioni include ed exclude della configurazione per individuare i file di test.

benchmark sperimentale

La modalità benchmark eseguirà le funzioni bench e genererà un errore se incontra test o it. Questa modalità utilizza le opzioni benchmark.include e benchmark.exclude della configurazione per individuare i file di benchmark.

config

La configurazione principale (o globale) di Vitest. Se sono definiti dei progetti, questi faranno riferimento a questa configurazione come globalConfig.

WARNING

Questa è la configurazione di Vitest e non estende quella di Vite. Contiene solo i valori risolti dalla proprietà test.

vite

Questo rappresenta un'istanza globale di ViteDevServer.

state sperimentale

WARNING

L'API pubblica state è sperimentale (ad eccezione di vitest.state.getReportedEntity). Le modifiche che rompono la compatibilità potrebbero non seguire SemVer; si consiglia di fissare la versione di Vitest quando la si utilizza.

Lo stato globale mantiene le informazioni sui test in corso. Per impostazione predefinita, utilizza la stessa API di @vitest/runner, ma si raccomanda di utilizzare l'API Reported Tasks chiamando state.getReportedEntity() sull'API @vitest/runner:

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

In futuro, la vecchia API non sarà più disponibile.

snapshot

Il gestore globale degli snapshot. Vitest monitora tutti gli snapshot utilizzando il metodo snapshot.add.

È possibile ottenere l'ultimo riepilogo degli snapshot tramite la proprietà vitest.snapshot.summary.

cache

Il gestore della cache che conserva le informazioni sugli ultimi risultati dei test e sulle statistiche dei file di test. In Vitest, questo è utilizzato solo dal sequencer predefinito per ordinare i test.

projects

Un array di progetti di test definiti dall'utente. Se l'utente non ne specifica alcuno, questo array conterrà solo un progetto radice.

Vitest garantisce che ci sia sempre almeno un progetto in questo array. Se l'utente specifica un nome --project inesistente, Vitest genererà un errore prima che questo array venga definito.

getRootProject

function getRootProject(): TestProject;

Questo metodo restituisce il progetto di test radice. Il progetto radice generalmente non esegue alcun test e non è incluso in vitest.projects a meno che l'utente non includa esplicitamente la configurazione radice nella propria configurazione, o i progetti non siano definiti affatto.

L'obiettivo principale del progetto radice è definire la configurazione globale. Infatti, rootProject.config fa riferimento a rootProject.globalConfig e vitest.config direttamente:

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

provide

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

Vitest espone il metodo provide, che funge da scorciatoia per vitest.getRootProject().provide. Con questo metodo è possibile trasferire valori dal thread principale ai test. Tutti i valori vengono controllati con structuredClone prima di essere memorizzati, ma i valori stessi non vengono clonati.

Per ricevere i valori nel test, è necessario importare il metodo inject dal punto di ingresso di vitest:

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

Per una migliore sicurezza dei tipi, ti incoraggiamo a estendere il tipo di 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 è un metodo di TestProject, e quindi è limitato al progetto specifico. Tuttavia, tutti i progetti ereditano i valori dal progetto radice, il che rende vitest.provide un modo universale per fornire valori ai test.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Questo restituisce l'oggetto contesto principale. Questa è una scorciatoia per vitest.getRootProject().getProvidedContext.

getProjectByName

function getProjectByName(name: string): TestProject;

Questo metodo restituisce il progetto tramite il suo nome. È simile a una chiamata di vitest.projects.find.

WARNING

Nel caso in cui il progetto non esista, questo metodo restituirà il progetto principale. Assicurati di verificare i nomi se il progetto che stai cercando è quello che viene restituito.

Se l'utente non ha specificato un nome personalizzato, Vitest assegnerà una stringa vuota come nome.

globTestSpecifications

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

Questo metodo costruisce nuove specifiche di test identificando ogni test in tutti i progetti con project.globTestFiles. Accetta filtri stringa per corrispondere ai file di test; questi sono gli stessi filtri supportati dalla CLI.

Questo metodo memorizza automaticamente nella cache tutte le specifiche di test. Quando chiami getModuleSpecifications successivamente, restituirà le stesse specifiche a meno che clearSpecificationsCache non sia stato chiamato in precedenza.

WARNING

A partire da Vitest 3, è possibile avere più specifiche di test con lo stesso ID modulo (percorso file) se poolMatchGlob include più pool o se typecheck è abilitato. Questa possibilità verrà rimossa in 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[]>;

Questo metodo risolve le specifiche di test invocando project.globTestFiles. Accetta filtri stringa per corrispondere ai file di test; questi sono gli stessi filtri supportati dalla CLI. Se il flag --changed è stato specificato, l'elenco verrà filtrato per includere solo i file modificati. getRelevantTestSpecifications non esegue alcun file di test.

WARNING

Questo metodo può risultare lento poiché deve elaborare i flag --changed. Non usarlo se hai solo bisogno di un elenco di file di test.

• Se hai bisogno di ottenere l'elenco delle specifiche per i file di test noti, usa getModuleSpecifications invece.
• Se hai bisogno di ottenere l'elenco di tutti i possibili file di test, usa globTestSpecifications.

mergeReports

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

Unisce i report da più esecuzioni situate nella directory specificata (il valore di --merge-reports se non specificato). Questo valore può anche essere impostato su config.mergeReports (per impostazione predefinita, leggerà dalla cartella .vitest-reports).

Si noti che il percorso directory sarà sempre risolto in relazione alla directory di lavoro.

Questo metodo viene chiamato automaticamente da startVitest se config.mergeReports è impostato.

collect

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

Esegue i file di test senza invocare i callback di test. collect restituisce gli errori non gestiti e un array di moduli di test. Accetta filtri stringa per corrispondere ai file di test; questi sono gli stessi filtri supportati dalla CLI.

Questo metodo risolve le specifiche dei test basandosi sui valori include, exclude e includeSource della configurazione. Maggiori informazioni su project.globTestFiles. Se il flag --changed è stato specificato, l'elenco verrà filtrato per includere solo i file che sono stati modificati.

WARNING

Si noti che Vitest non utilizza l'analisi statica per individuare i test. Vitest eseguirà ogni file di test in isolamento, esattamente come esegue i test regolari.

Questo rende questo metodo molto lento, a meno che non si disabiliti l'isolamento prima di individuare i test.

start

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

Inizializza i reporter, il provider di copertura e avvia l'esecuzione dei test. Questo metodo accetta filtri stringa per corrispondere ai file di test; questi sono gli stessi filtri supportati dalla CLI.

WARNING

Questo metodo non dovrebbe essere chiamato se vitest.init() è già stato invocato. Utilizzare runTestSpecifications o rerunTestSpecifications se è necessario eseguire test dopo che Vitest è stato inizializzato.

Questo metodo viene chiamato automaticamente da startVitest se config.mergeReports e config.standalone non sono impostati.

init

function init(): Promise<void>;

Inizializza i reporter e il provider di copertura. Questo metodo non esegue alcun test. Se il flag --watch è specificato, Vitest eseguirà comunque i test modificati anche se questo metodo non è stato chiamato.

Internamente, questo metodo viene chiamato solo se il flag --standalone è attivo.

WARNING

Questo metodo non dovrebbe essere chiamato se vitest.start() è già stato invocato.

Questo metodo viene chiamato automaticamente da startVitest se config.standalone è impostato.

getModuleSpecifications

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

Restituisce un elenco di specifiche di test associate all'ID del modulo. L'ID deve essere già risolto in un percorso di file assoluto. Se l'ID non rientra nei pattern include o includeSource, l'array restituito sarà vuoto.

Questo metodo può restituire specifiche già memorizzate nella cache in base a moduleId e pool. Si noti che project.createSpecification restituisce sempre una nuova istanza e non viene automaticamente memorizzata nella cache. Tuttavia, le specifiche vengono automaticamente memorizzate nella cache quando viene chiamato runTestSpecifications.

WARNING

A partire da Vitest 3, questo metodo utilizza una cache per determinare se il file è un test. Per assicurarsi che la cache non sia vuota, invocare globTestSpecifications almeno una volta.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest memorizza automaticamente nella cache le specifiche di test per ogni file quando si invoca globTestSpecifications o runTestSpecifications. Questo metodo svuota la cache per il file specificato o l'intera cache a seconda del primo argomento.

runTestSpecifications

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

Questo metodo esegue ogni test in base alle specifiche ricevute. Il secondo argomento, allTestsRun, viene utilizzato dal provider di copertura per determinare se deve applicare la strumentazione per la copertura su ogni file nella directory radice (questo è importante solo se la copertura è abilitata e coverage.all è impostato su true).

WARNING

Questo metodo non innesca i callback onWatcherRerun, onWatcherStart e onTestsRerun. Se stai rieseguendo i test a seguito di una modifica del file, considera l'utilizzo di rerunTestSpecifications.

rerunTestSpecifications

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

Questo metodo genera gli eventi reporter.onWatcherRerun e onTestsRerun, quindi esegue i test utilizzando runTestSpecifications. Se non ci sono stati errori nel processo principale, genererà l'evento reporter.onWatcherStart.

updateSnapshot

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

Aggiorna gli snapshot dei file specificati. Se non vengono forniti file, aggiornerà i file contenenti test falliti e snapshot obsoleti.

collectTests

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

Esegue i file di test senza invocare i callback di test. collectTests restituisce gli errori non gestiti e un array di moduli di test.

Questo metodo funziona esattamente come collect, ma è necessario fornire le specifiche di test autonomamente.

WARNING

Si noti che Vitest non utilizza l'analisi statica per individuare i test. Vitest eseguirà ogni file di test in isolamento, esattamente come esegue i test regolari.

Questo rende questo metodo molto lento, a meno che non si disabiliti l'isolamento prima di individuare i test.

cancelCurrentRun

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

Questo metodo annullerà in modo controllato tutti i test in corso. Attenderà che i test avviati terminino l'esecuzione e non eseguirà i test che erano stati programmati ma non sono ancora iniziati.

setGlobalTestNamePattern

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

Questo metodo sovrascrive il pattern globale per i nomi dei test.

WARNING

Questo metodo non avvia l'esecuzione di test. Per eseguire i test con il pattern aggiornato, invocare runTestSpecifications.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Questo metodo reimposta il pattern per i nomi dei test. Ciò significa che Vitest non ignorerà più alcun test.

WARNING

Questo metodo non avvia l'esecuzione di test. Per eseguire i test senza un pattern, invocare runTestSpecifications.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Abilita la modalità che permette l'aggiornamento degli snapshot durante l'esecuzione dei test. Ogni test eseguito dopo l'invocazione di questo metodo aggiornerà gli snapshot. Per disabilitare la modalità, invocare resetSnapshotUpdate.

WARNING

Questo metodo non avvia l'esecuzione di test. Per aggiornare gli snapshot, eseguire i test con runTestSpecifications.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Disabilita la modalità che permette l'aggiornamento degli snapshot durante l'esecuzione dei test. Questo metodo non avvia l'esecuzione di alcun test.

invalidateFile

function invalidateFile(filepath: string): void;

Questo metodo invalida la voce del file nella cache di ogni progetto. È utile soprattutto se si utilizza un watcher personalizzato, poiché la cache di Vite persiste in memoria.

DANGER

Se disabiliti il watcher di Vitest ma mantieni Vitest in esecuzione, è importante svuotare manualmente la cache con questo metodo, poiché non esiste un'opzione per disabilitare la cache. Questo metodo invaliderà anche i moduli che importano il file.

import

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

Importa un file tramite il runner del modulo Vite. Il file verrà trasformato da Vite utilizzando la configurazione globale ed eseguito in un contesto separato. Si noti che moduleId sarà risolto rispetto a config.root.

DANGER

project.import riutilizza il grafo dei moduli di Vite, quindi l'importazione dello stesso modulo tramite un'importazione regolare restituirà un modulo diverso:

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

dynamicExample !== staticExample; // ✅

INFO

Internamente, Vitest usa questo metodo per importare setup globali, provider di copertura personalizzati e reporter personalizzati, il che significa che tutti condividono lo stesso grafo dei moduli purché appartengano allo stesso server Vite.

close

function close(): Promise<void>;

Chiude tutti i progetti e le risorse correlate. Questo può essere invocato una sola volta; la promessa di chiusura viene mantenuta in cache fino al riavvio del server.

exit

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

Chiude tutti i progetti e termina il processo. Se force è impostato su true, il processo terminerà immediatamente dopo la chiusura dei progetti.

Questo metodo invocherà anche forzatamente process.exit() se il processo è ancora in esecuzione dopo config.teardownTimeout millisecondi.

shouldKeepServer

function shouldKeepServer(): boolean;

Questo metodo restituirà true se il server dovrebbe rimanere attivo dopo che i test sono stati completati. Questo di solito significa che la modalità watch è stata attivata.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Registra un gestore che verrà invocato quando il server viene riavviato a causa di una modifica della configurazione.

onCancel

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

Registra un gestore che verrà invocato quando l'esecuzione del test viene annullata con vitest.cancelCurrentRun.

onClose

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

Registra un gestore che verrà invocato quando il server viene chiuso.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Registra un gestore che verrà invocato quando i test vengono rieseguiti. I test possono essere rieseguiti quando rerunTestSpecifications viene invocato manualmente o quando un file viene modificato e il watcher integrato programma una riesecuzione.

onFilterWatchedSpecification

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

Registra un gestore che verrà invocato quando un file viene modificato. Questo callback dovrebbe restituire true o false, indicando se il file di test debba essere rieseguito.

Con questo metodo, puoi integrare la logica predefinita del watcher per ritardare o scartare i test che l'utente non desidera monitorare in quel momento:

const continuesTests: string[] = [];

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

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

Vitest può creare diverse specifiche per lo stesso file a seconda delle opzioni pool o locations, quindi non fare affidamento sulla referenza. Vitest può anche restituire specifiche memorizzate nella cache da vitest.getModuleSpecifications - la cache è basata su moduleId e pool. Si noti che project.createSpecification restituisce sempre una nuova istanza.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Verifica se il nome corrisponde al criterio di filtro del progetto attuale. Se non è presente un filtro del progetto, questo restituirà sempre true.

Non è possibile impostare programmaticamente l'opzione CLI --project.