TestProject 3.0.0+

WARNING

Questa guida descrive le API avanzate di Node.js. Se desideri semplicemente definire progetti, consulta la guida "Test Projects".

name

Il nome è una stringa unica assegnata dall'utente o determinata da Vitest. Se l'utente non ha fornito un nome, Vitest tenta di caricare un package.json nella root del progetto e di ricavarne la proprietà name. Se non è presente un package.json, Vitest utilizza il nome della cartella di default. I progetti incorporati utilizzano numeri come nome (convertiti in stringa).

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // ha package.json con "@pkg/server"
      './utils', // non ha un file package.json
      {
        // non modifica il nome
        test: {
          pool: 'threads',
        },
      },
      {
        // nome modificato
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Se il progetto root non fa parte dei progetti dell'utente, il suo name non verrà risolto.

vitest

vitest fa riferimento al processo globale Vitest.

serializedConfig

Questa è la configurazione che i processi di test ricevono. Vitest serializza manualmente la configurazione rimuovendo tutte le funzioni e le proprietà non serializzabili. Poiché questo valore è disponibile sia nei test che in Node.js, il suo tipo viene esportato dal punto di ingresso principale.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

La proprietà serializedConfig è un getter. Ogni volta che vi si accede, Vitest serializza nuovamente la configurazione qualora sia stata modificata. Ciò significa anche che restituisce sempre un riferimento diverso:

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

La configurazione di test con la quale Vitest è stato inizializzato. Se questo è il progetto root, globalConfig e config faranno riferimento allo stesso oggetto. Questa configurazione è utile per valori che non possono essere impostati a livello di progetto, come coverage o reporters.

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

vitest.config === vitest.projects[0].globalConfig;

config

Questa è la configurazione di test risolta del progetto.

hash 3.2.0+

L'hash univoco di questo progetto. Questo valore rimane costante tra le esecuzioni.

È basato sulla root del progetto e sul suo nome. Si noti che il percorso root non è consistente tra diversi sistemi operativi, quindi anche l'hash sarà diverso.

vite

Questo è il ViteDevServer del progetto. Tutti i progetti hanno i propri server Vite.

browser

Questo valore sarà impostato solo se i test vengono eseguiti nel browser. Se browser è abilitato, ma i test non sono ancora stati eseguiti, questo risulterà undefined. Se è necessario verificare se il progetto supporta i test del browser, utilizzare il metodo project.isBrowserEnabled().

WARNING

L'API del browser è ancora più sperimentale e non segue SemVer. L'API del browser sarà standardizzata separatamente dal resto delle API.

provide

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

Un modo per fornire valori personalizzati per i test oltre al campo config.provide. Tutti i valori vengono convalidati con structuredClone prima di essere memorizzati, ma i valori all'interno di providedContext stessi non vengono clonati.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

I valori possono essere forniti in modo dinamico. Il valore fornito nei test verrà aggiornato alla successiva esecuzione.

TIP

Questo metodo è disponibile anche per i file di setup globale per i casi in cui non è possibile utilizzare l'API pubblica:

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

getProvidedContext

function getProvidedContext(): ProvidedContext;

Questo restituisce l'oggetto del contesto. Ogni progetto eredita anche il contesto globale impostato da vitest.provide.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

I valori del contesto del progetto sovrascriveranno sempre il contesto del progetto root.

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

Crea una specifica di test che può essere utilizzata in vitest.runTestSpecifications. La specifica associa il file di test a un project specifico e a delle locations di test (opzionale). Le locations di test sono le linee di codice sorgente in cui il test è definito. Se vengono fornite le locations, Vitest eseguirà solo i test definiti su quelle linee. Si noti che se testNamePattern è definito, verrà applicato anch'esso.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // linee di test opzionali
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification richiede un ID modulo risolto. Non risolve automaticamente il file né ne verifica l'esistenza sul file system.

Si noti anche che project.createSpecification restituisce sempre una nuova istanza.

isRootProject

function isRootProject(): boolean;

Controlla se il progetto attuale è il progetto root. È possibile ottenere il progetto root anche chiamando vitest.getRootProject().

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * File di test che corrispondono ai filtri.
   */
  testFiles: string[];
  /**
   * File di test di controllo del tipo che corrispondono ai filtri. Questo sarà vuoto a meno che `typecheck.enabled` non sia `true`.
   */
  typecheckTestFiles: string[];
};

La funzione globTestFiles trova tutti i file di test. Questa funzione restituisce un oggetto contenente test regolari e test di controllo del tipo.

Questo metodo accetta filters. I filtri possono essere solo una porzione del percorso del file, a differenza di altri metodi sull'istanza Vitest:

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest utilizza fast-glob per trovare i file di test. test.dir, test.root, root o process.cwd() definiscono l'opzione cwd.

Questo metodo prende in considerazione diverse opzioni di configurazione:

• test.include, test.exclude per trovare file di test regolari
• test.includeSource, test.exclude per trovare test in-source
• test.typecheck.include, test.typecheck.exclude per trovare test di controllo del tipo

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

Questo metodo matchesTestGlob verifica se il file è un file di test regolare. Utilizza le stesse proprietà di configurazione che globTestFiles utilizza per la convalida.

Questo metodo accetta anche un secondo parametro, che è il codice sorgente. Viene utilizzato per convalidare se il file è un test in-source. Se si chiama questo metodo più volte per diversi progetti, si consiglia di leggere il file una volta e passarlo direttamente come argomento. Se il file non è un file di test, ma corrisponde al glob includeSource, Vitest leggerà il file sincronicamente a meno che non venga fornito il source.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // true se `includeSource` è impostato

import

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

Importa un file utilizzando il gestore di moduli di Vite. Il file verrà trasformato da Vite con la configurazione del progetto specificata ed eseguito in un contesto separato. Si noti che moduleId è relativo a config.root.

DANGER

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

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

dynamicExample !== staticExample; // ✅

INFO

Internamente, Vitest utilizza 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.

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

Questa è una scorciatoia per project.vitest.onTestsRerun. Accetta una callback che verrà eseguita quando i test sono stati programmati per essere rieseguiti (di solito, a causa di una modifica del file).

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

Restituisce true se questo progetto esegue test nel browser.

close

function close(): Promise<void>;

Chiude il progetto e tutte le risorse ad esso associate. Può essere chiamato solo una volta; la promessa di chiusura viene salvata nella cache e rimane valida fino al riavvio del server. Se le risorse sono nuovamente necessarie, è necessario creare un nuovo progetto.

In dettaglio, questo metodo chiude il server Vite, arresta il servizio di controllo del tipo, chiude il browser se è in esecuzione, elimina la directory temporanea che contiene il codice sorgente e resetta il contesto fornito.