API di Node

WARNING

Vitest espone API private sperimentali. Le modifiche che causano interruzioni potrebbero non rispettare SemVer. Si consiglia di fissare la versione di Vitest quando la si utilizza.

startVitest

È possibile avviare i test di Vitest tramite la sua API Node:

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest?.close();

La funzione startVitest restituisce un'istanza di Vitest se i test possono essere avviati correttamente. Restituisce undefined se si verifica una delle seguenti condizioni:

• Vitest non ha trovato il pacchetto vite (solitamente installato con Vitest).
• La copertura del codice è abilitata e la modalità di test è attiva, ma il pacchetto di coverage non è installato (@vitest/coverage-v8 o @vitest/coverage-istanbul).
• Il pacchetto dell'ambiente non è installato (jsdom/happy-dom/@edge-runtime/vm).

Se viene restituito undefined o se i test falliscono durante l'esecuzione, Vitest imposta process.exitCode su 1.

Se la modalità watch non è abilitata, Vitest chiamerà il metodo close.

Se la modalità watch è abilitata e il terminale supporta TTY, Vitest registrerà le scorciatoie da tastiera nella console.

È possibile passare una lista di filtri come secondo argomento alla funzione. Vitest eseguirà solo i test che contengono almeno una delle stringhe passate nel percorso del file.

Inoltre, è possibile utilizzare il terzo argomento per passare gli argomenti della CLI, sovrascrivendo così qualsiasi opzione di configurazione del test.

In alternativa, è possibile passare la configurazione completa di Vite come quarto argomento, che avrà la precedenza su tutte le altre opzioni definite dall'utente.

Dopo aver eseguito i test, è possibile ottenere i risultati tramite l'API state.getFiles:

const vitest = await startVitest('test');

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

A partire da Vitest 2.1, è consigliato utilizzare l'API "Reported Tasks" (Attività Segnalate) in combinazione con state.getFiles. In futuro, Vitest restituirà direttamente questi oggetti:

const vitest = await startVitest('test');

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

createVitest

È possibile creare un'istanza di Vitest tramite la funzione createVitest. Restituisce la stessa istanza Vitest di startVitest, ma non avvia i test né convalida i pacchetti installati.

import { createVitest } from 'vitest/node';

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

parseCLI

Questo metodo permette di analizzare gli argomenti della CLI. Accetta una stringa in cui gli argomenti sono separati da uno spazio oppure un array di stringhe di argomenti della CLI, nello stesso formato utilizzato dalla CLI di Vitest. Restituisce un filtro e options da passare successivamente ai metodi createVitest o startVitest.

import { parseCLI } from 'vitest/node';

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

Vitest

L'istanza di Vitest richiede di specificare la modalità di test corrente. Può essere:

• test quando si eseguono test runtime
• benchmark quando si eseguono benchmark

mode

test

La modalità test invocherà solo le funzioni definite all'interno di test o it e genererà un errore se incontra bench. Questa modalità utilizza le opzioni include ed exclude nella configurazione per individuare i file di test.

benchmark

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

start

È possibile avviare l'esecuzione dei test o dei benchmark tramite il metodo start. È possibile passare un array di stringhe per filtrare i file di test da eseguire.

provide

Vitest espone il metodo provide, che è un'abbreviazione di vitest.getCoreWorkspaceProject().provide. Questo metodo permette di passare valori dal thread principale ai test. Tutti i valori vengono verificati tramite structuredClone prima di essere memorizzati, ma i valori stessi non vengono clonati.

Per ricevere i valori nel test, è necessario importare il metodo inject dall'entrypoint di vitest:

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

Per una migliore type safety, si consiglia di 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 WorkspaceProject e, pertanto, è limitato allo specifico progetto. Tuttavia, tutti i progetti ereditano i valori dal progetto core, rendendo vitest.provide un metodo universale per passare valori ai test.

TIP

Questo metodo è disponibile anche per i file di setup globali nei casi in cui non si desidera utilizzare l'API pubblica:

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