Configurazione di Vitest

Se utilizzi Vite e possiedi un file vite.config, Vitest lo leggerà per allinearsi ai plugin e alla configurazione della tua applicazione Vite. Se desideri una configurazione diversa per i test o la tua applicazione principale non si basa specificamente su Vite, puoi:

• Creare vitest.config.ts, che avrà la priorità più alta e sovrascriverà la configurazione da vite.config.ts. (Vitest supporta tutte le estensioni JS e TS convenzionali, ma non json). Ciò significa che tutte le opzioni nel tuo vite.config verranno ignorate.
• Passare l'opzione --config alla CLI, ad esempio vitest --config ./path/to/vitest.config.ts.
• Usare process.env.VITEST o la proprietà mode su defineConfig (sarà impostata su test/benchmark se non sovrascritta con --mode) per applicare condizionalmente una configurazione diversa in vite.config.ts.

Per configurare vitest, aggiungi la proprietà test nella tua configurazione Vite. Dovrai anche aggiungere un riferimento ai tipi Vitest usando una direttiva triple slash all'inizio del tuo file di configurazione, se stai importando defineConfig da vite.

Esempi di Configurazione

Usando defineConfig da vite dovresti seguire questo:

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... Specificare le opzioni qui.
  },
});

La direttiva <reference types="vitest" /> non funzionerà più in Vitest 4, ma puoi già iniziare a migrare a vitest/config:

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... Specificare le opzioni qui.
  },
});

Usando defineConfig da vitest/config dovresti seguire questo:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ... Specificare le opzioni qui.
  },
});

Puoi recuperare le opzioni predefinite di Vitest e ampliarle se necessario:

import { configDefaults, defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    exclude: [...configDefaults.exclude, 'packages/template/*'],
  },
});

Se utilizzi un vitest.config.js separato, puoi anche estendere le opzioni di Vite da un altro file di configurazione se necessario:

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      exclude: ['packages/template/*'],
    },
  })
);

Se la tua configurazione Vite è una funzione, puoi definirla in questo modo:

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default defineConfig(configEnv =>
  mergeConfig(
    viteConfig(configEnv),
    defineConfig({
      test: {
        exclude: ['packages/template/*'],
      },
    })
  )
);

WARNING

Tutte le opzioni elencate in questa pagina sono contenute in una proprietà test nella configurazione:

export default defineConfig({
  test: {
    exclude: [],
  },
});

Poiché Vitest utilizza la configurazione di Vite, puoi anche usare qualsiasi opzione di configurazione da Vite. Ad esempio, define per definire variabili globali, o resolve.alias per definire alias - queste opzioni dovrebbero essere definite al livello superiore, non all'interno di una proprietà test.

Le opzioni di configurazione non supportate in una configurazione di progetto sono contrassegnate con *. Ciò significa che possono essere impostate solo nella configurazione Vitest radice.

include

• Tipo: string[]
• Predefinito: ['**/*.{test,spec}.?(c|m)[jt]s?(x)']
• CLI: vitest [...include], vitest **/*.test.js

Un elenco di pattern glob che corrispondono ai tuoi file di test.

NOTA

Quando si abilita la copertura, Vitest aggiunge automaticamente i pattern include dei file di test ai pattern exclude predefiniti della copertura. Vedi coverage.exclude.

exclude

• Tipo: string[]
• Predefinito: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**', '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*']
• CLI: vitest --exclude "**/excluded-file"

Un elenco di pattern glob da escludere dai tuoi file di test.

WARNING

Questa opzione non ha effetto sulla copertura. Se desideri rimuovere determinati file dal report di copertura, utilizza coverage.exclude.

Questa è l'unica opzione che non sovrascrive la tua configurazione se specificata tramite un flag CLI. Tutti i pattern glob aggiunti tramite il flag --exclude verranno aggiunti all'exclude della configurazione.

includeSource

• Tipo: string[]
• Predefinito: []

Pattern glob da includere per i file di test in-source.

Quando definito, Vitest eseguirà tutti i file corrispondenti che contengono import.meta.vitest.

name

• Tipo: string | { label: string, color?: LabelColor }

Assegna un nome personalizzato al progetto di test o al processo Vitest. Il nome sarà visibile nella CLI e nell'UI, e disponibile nell'API Node.js tramite project.name.

Il colore usato dalla CLI e dall'UI può essere modificato fornendo un oggetto con la proprietà color.

server

• Tipo: { sourcemap?, deps?, ... }

Opzioni del server Vite-Node.

server.sourcemap

• Tipo: 'inline' | boolean
• Predefinito: 'inline'

Inietta la sourcemap inline all'interno dei moduli.

server.debug

• Tipo: { dumpModules?, loadDumppedModules? }

Opzioni del debugger Vite-Node.

server.debug.dumpModules

• Tipo: boolean | string

Effettua il dump del modulo trasformato nel filesystem. Passando una stringa, il dump verrà salvato nel percorso specificato.

server.debug.loadDumppedModules

• Tipo: boolean

Legge il modulo di cui è stato fatto il dump dal filesystem, se presente. Utile per il debug modificando il risultato del dump dal filesystem.

server.deps

• Tipo: { external?, inline?, ... }

Gestione della risoluzione delle dipendenze.

server.deps.external

• Tipo: (string | RegExp)[]
• Predefinito: [/\/node_modules\//]

Esternalizzare significa che Vite non elaborerà il pacchetto, lasciandolo gestire direttamente a Node. Le dipendenze esternalizzate non verranno applicate ai trasformatori e ai risolutori di Vite, quindi non supportano l'HMR (Hot Module Replacement) al ricaricamento. Per impostazione predefinita, tutti i pacchetti all'interno di node_modules sono esternalizzati.

Queste opzioni supportano i nomi dei pacchetti così come sono scritti in node_modules o specificati all'interno di deps.moduleDirectories. Ad esempio, il pacchetto @company/some-name situato all'interno di packages/some-name dovrebbe essere specificato come some-name, e packages dovrebbe essere incluso in deps.moduleDirectories. In sostanza, Vitest controlla sempre il percorso del file, non il nome effettivo del pacchetto.

Se viene usata una regexp, Vitest la applica al percorso del file, non al nome del pacchetto.

server.deps.inline

• Tipo: (string | RegExp)[] | true
• Predefinito: []

Vite elaborerà i moduli inclusi direttamente (inlined). Questo potrebbe essere utile per gestire pacchetti che forniscono file .js in formato ESM (che Node non può gestire).

Se true, ogni dipendenza sarà inlined. Tutte le dipendenze, specificate in ssr.noExternal saranno inlined per impostazione predefinita.

server.deps.fallbackCJS

• Tipo boolean
• Predefinito: false

Quando una dipendenza è un pacchetto ESM valido, tenta di dedurre la versione CJS basandosi sul percorso. Questo potrebbe essere utile, se una dipendenza ha il file ESM sbagliato.

Questo potrebbe potenzialmente causare un'incoerenza se un pacchetto ha una logica diversa in modalità ESM e CJS.

server.deps.cacheDir

• Tipo string
• Predefinito: 'node_modules/.vite'

Directory in cui salvare i file di cache.

deps

• Tipo: { optimizer?, ... }

Gestione della risoluzione delle dipendenze.

deps.optimizer

• Tipo: { ssr?, web? }
• Vedi anche: Opzioni di Ottimizzazione delle Dipendenze

Attiva l'ottimizzazione delle dipendenze. Se hai molti test, questo potrebbe migliorarne le prestazioni.

Quando Vitest incontra una libreria esterna elencata in include, questa verrà impacchettata in un singolo file usando esbuild e importata come modulo intero. Questo è utile per diverse ragioni:

• Importare pacchetti con molte importazioni è oneroso. Impacchettandoli in un unico file possiamo risparmiare molto tempo.
• Importare librerie UI è costoso perché non sono pensate per essere eseguite all'interno di Node.js.
• La tua configurazione alias è ora rispettata all'interno dei pacchetti impacchettati.
• Il codice nei tuoi test viene eseguito in modo più coerente con l'esecuzione nel browser.

Tieni presente che solo i pacchetti nell'opzione deps.optimizer?.[mode].include vengono impacchettati (alcuni plugin lo popolano automaticamente, come Svelte). Puoi leggere di più sulle opzioni disponibili nella documentazione di Vite (Vitest non supporta le opzioni disable e noDiscovery). Per impostazione predefinita, Vitest usa optimizer.web per gli ambienti jsdom e happy-dom, e optimizer.ssr per gli ambienti node ed edge, ma è configurabile tramite transformMode.

Questa opzione eredita anche la tua configurazione optimizeDeps (per il web Vitest estenderà optimizeDeps, per SSR - ssr.optimizeDeps). Se ridefinisci l'opzione include/exclude in deps.optimizer, questa integrerà la tua configurazione optimizeDeps durante l'esecuzione dei test. Vitest rimuove automaticamente le voci corrispondenti da include, se sono elencate in exclude.

TIP

Non sarai in grado di modificare il codice di node_modules per il debug, poiché il codice è effettivamente situato nella tua directory cacheDir o test.cache.dir. Se vuoi eseguire il debug con istruzioni console.log, modificalo direttamente o forza la ricompilazione con l'opzione deps.optimizer?.[mode].force.

deps.optimizer.{mode}.enabled

• Tipo: boolean
• Predefinito: false

Abilita l'ottimizzazione delle dipendenze.

deps.web

• Tipo: { transformAssets?, ... }

Opzioni che si applicano ai file esterni quando la modalità di trasformazione è impostata su web. Per impostazione predefinita, jsdom e happy-dom usano la modalità web, mentre gli ambienti node ed edge usano la modalità di trasformazione ssr, quindi queste opzioni non avranno alcun effetto sui file all'interno di tali ambienti.

Di solito, i file all'interno di node_modules sono esternalizzati, ma queste opzioni influenzano anche i file in server.deps.external.

deps.web.transformAssets

• Tipo: boolean
• Predefinito: true

Vitest dovrebbe elaborare i file di asset (.png, .svg, .jpg, ecc.) e risolverli come fa Vite nel browser.

Questo modulo avrà un'esportazione predefinita uguale al percorso dell'asset, se non viene specificata alcuna query.

WARNING

Al momento, questa opzione funziona solo con i pool vmThreads e vmForks.

deps.web.transformCss

• Tipo: boolean
• Predefinito: true

Vitest dovrebbe elaborare i file CSS (.css, .scss, .sass, ecc.) e risolverli come fa Vite nel browser.

Se i file CSS sono disabilitati con le opzioni css, questa opzione si limiterà a silenziare gli errori ERR_UNKNOWN_FILE_EXTENSION.

WARNING

Al momento, questa opzione funziona solo con i pool vmThreads e vmForks.

deps.web.transformGlobPattern

• Tipo: RegExp | RegExp[]
• Predefinito: []

Pattern RegExp per corrispondere ai file esterni che dovrebbero essere trasformati.

Per impostazione predefinita, i file all'interno di node_modules sono esternalizzati e non trasformati, a meno che non siano CSS o un asset, e l'opzione corrispondente non sia disabilitata.

WARNING

Al momento, questa opzione funziona solo con i pool vmThreads e vmForks.

deps.interopDefault

• Tipo: boolean
• Predefinito: true

Interpreta l'esportazione predefinita dei moduli CJS come esportazioni nominate. Alcune dipendenze impacchettano solo moduli CJS e non usano esportazioni nominate che Node.js può analizzare staticamente quando un pacchetto viene importato usando la sintassi import invece di require. Quando si importano tali dipendenze in un ambiente Node usando esportazioni nominate, si vedrà questo errore:

import { read } from 'fs-jetpack';
         ^^^^
SyntaxError: Named export 'read' not found. The requested module 'fs-jetpack' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export.

Vitest non esegue analisi statica e non può rilevare errori prima dell'esecuzione del codice, quindi molto probabilmente vedrai questo errore durante l'esecuzione dei test, se questa funzionalità è disabilitata:

TypeError: createAsyncThunk is not a function
TypeError: default is not a function

Per impostazione predefinita, Vitest presume che tu stia usando un bundler per aggirare questo problema e non causerà errori, ma puoi disabilitare questo comportamento manualmente, se il tuo codice non viene elaborato.

deps.moduleDirectories

• Tipo: string[]
• Predefinito: ['node_modules']

Un elenco di directory da trattare come directory di moduli. Questa opzione di configurazione influisce sul comportamento di vi.mock: quando non viene fornita alcuna factory e il percorso di ciò che stai mockando corrisponde a uno dei valori di moduleDirectories, Vitest cercherà di risolvere il mock cercando una cartella __mocks__ nella radice del progetto.

Questa opzione influenzerà anche il modo in cui un file viene trattato come modulo durante l'esternalizzazione delle dipendenze. Per impostazione predefinita, Vitest importa moduli esterni usando Node.js nativo, saltando il passaggio di trasformazione di Vite.

Impostando questa opzione si sovrascriverà il valore predefinito. Se si desidera comunque cercare pacchetti in node_modules, includerlo insieme a qualsiasi altra opzione desiderata:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    deps: {
      moduleDirectories: ['node_modules', path.resolve('../../packages')],
    },
  },
});

runner

• Tipo: VitestRunnerConstructor
• Predefinito: node, quando si eseguono test, o benchmark, quando si eseguono benchmark

Specifica il percorso di un runner di test personalizzato. Questa è una funzionalità avanzata e va utilizzata con runner di librerie personalizzate. Puoi leggere di più a riguardo nella documentazione.

benchmark

• Tipo: { include?, exclude?, ... }

Opzioni usate quando si esegue vitest bench.

benchmark.include

• Tipo: string[]
• Predefinito: ['**/*.{bench,benchmark}.?(c|m)[jt]s?(x)']

Pattern glob da includere per i file di test di benchmark.

benchmark.exclude

• Tipo: string[]
• Predefinito: ['node_modules', 'dist', '.idea', '.git', '.cache']

Pattern glob da escludere per i file di test di benchmark.

benchmark.includeSource

• Tipo: string[]
• Predefinito: []

Includi glob per i file di test di benchmark in-source. Questa opzione è simile a includeSource.

Quando definito, Vitest eseguirà tutti i file corrispondenti con import.meta.vitest all'interno.

benchmark.reporters

• Tipo: Arrayable<BenchmarkBuiltinReporters | Reporter>
• Predefinito: 'default'

Reporter personalizzato per la generazione dell'output. Può contenere uno o più nomi di reporter integrati, istanze di reporter e/o percorsi a reporter personalizzati.

benchmark.outputFile

Deprecato, sostituito da benchmark.outputJson.

benchmark.outputJson

• Tipo: string | undefined
• Predefinito: undefined

Il percorso di un file in cui memorizzare il risultato del benchmark, utilizzabile in seguito con l'opzione --compare.

Ad esempio:

# salva il risultato del branch principale
git checkout main
vitest bench --outputJson main.json

# cambia branch e confronta con il principale
git checkout feature
vitest bench --compare main.json

benchmark.compare

• Tipo: string | undefined
• Predefinito: undefined

Il percorso di un file contenente un risultato di benchmark precedente da confrontare con le esecuzioni attuali.

alias

• Tipo: Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

Definisci alias personalizzati da utilizzare durante l'esecuzione dei test. Verranno uniti con gli alias da resolve.alias.

WARNING

Vitest usa le primitive Vite SSR per eseguire i test, il che comporta alcuni inconvenienti.

1. Gli alias si applicano solo ai moduli importati direttamente con una parola chiave import da un modulo inlined (tutto il codice sorgente è inlined per impostazione predefinita).
2. Vitest non supporta l'aliasing delle chiamate require.
3. Se stai creando un alias per una dipendenza esterna (ad esempio, react -> preact), potresti voler creare un alias per i pacchetti node_modules effettivi per farli funzionare correttamente con le dipendenze esternalizzate. Sia Yarn che pnpm supportano l'aliasing tramite il prefisso npm:.

globals

• Tipo: boolean
• Predefinito: false
• CLI: --globals, --globals=false

Per impostazione predefinita, vitest non fornisce API globali per chiarezza. Se preferisci usare le API globalmente come Jest, puoi fornire l'opzione --globals alla CLI o aggiungere globals: true nella configurazione.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
  },
});

Per abilitare il supporto TypeScript per le API globali, aggiungi vitest/globals al campo types nel tuo tsconfig.json

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Se hai ridefinito i tuoi typeRoots per includere più tipi nella tua compilazione, dovrai aggiungere nuovamente node_modules per rendere vitest/globals accessibile.

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types", "./node_modules"],
    "types": ["vitest/globals"]
  }
}

Se stai già usando unplugin-auto-import nel tuo progetto, puoi anche usarlo direttamente per l'auto-importazione di queste API.

import { defineConfig } from 'vitest/config';
import AutoImport from 'unplugin-auto-import/vite';

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // genera la dichiarazione TypeScript
    }),
  ],
});

environment

• Tipo: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string
• Predefinito: 'node'
• CLI: --environment=<env>

L'ambiente da utilizzare per i test. L'ambiente predefinito in Vitest è un ambiente Node.js. Se stai costruendo un'applicazione web, puoi usare un ambiente simile a un browser tramite jsdom o happy-dom.

Se stai costruendo funzioni serverless edge, puoi usare l'ambiente edge-runtime

TIP

Puoi anche usare la Modalità Browser per eseguire test di integrazione o unitari nel browser senza simulare l'ambiente.

Aggiungendo un docblock o un commento @vitest-environment all'inizio del file, puoi specificare un altro ambiente da utilizzare per tutti i test contenuti in quel file:

Stile Docblock:

/**
 * @vitest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Stile Commento:

// @vitest-environment happy-dom

test('use happy-dom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Per compatibilità con Jest, esiste anche un @jest-environment:

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Se stai eseguendo Vitest con il flag --isolate=false, i tuoi test verranno eseguiti in questo ordine: node, jsdom, happy-dom, edge-runtime, ambienti personalizzati. Ciò significa che i test con lo stesso ambiente sono raggruppati, ma vengono comunque eseguiti sequenzialmente.

A partire dalla versione 0.23.0, puoi anche definire un ambiente personalizzato. Quando viene utilizzato un ambiente non predefinito, Vitest cercherà di caricare il pacchetto vitest-environment-${name}. Quel pacchetto dovrebbe esportare un oggetto che rispetti l'interfaccia Environment:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // configurazione personalizzata
    return {
      teardown() {
        // chiamato dopo che tutti i test con questo ambiente sono stati eseguiti
      },
    };
  },
};

Vitest espone anche builtinEnvironments tramite l'entry vitest/environments, nel caso in cui tu voglia semplicemente estenderlo. Puoi leggere di più sull'estensione degli ambienti nella nostra guida.

TIP

L'ambiente jsdom espone la variabile globale jsdom che corrisponde all'istanza JSDOM corrente. Se vuoi che TypeScript la riconosca, puoi aggiungere vitest/jsdom al tuo tsconfig.json quando usi questo ambiente:

{
  "compilerOptions": {
    "types": ["vitest/jsdom"]
  }
}

environmentOptions

• Tipo: Record<'jsdom' | string, unknown>
• Predefinito: {}

Queste opzioni vengono passate al metodo setup dell'environment corrente. Per impostazione predefinita, puoi configurare solo le opzioni JSDOM, se lo stai usando come ambiente di test.

environmentMatchGlobs

• Tipo: [string, EnvironmentName][]
• Predefinito: []

DEPRECATO

Questa API è stata deprecata in Vitest 3. Usa i progetti per definire configurazioni diverse.

export default defineConfig({
  test: {
    environmentMatchGlobs: [ 
      ['./*.jsdom.test.ts', 'jsdom'], 
    ], 
    projects: [ 
      { 
        extends: true, 
        test: { 
          environment: 'jsdom', 
        }, 
      }, 
    ], 
  },
})

Assegna automaticamente l'ambiente in base ai pattern glob. Viene utilizzata la prima corrispondenza.

Ad esempio:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // tutti i test in tests/dom verranno eseguiti in jsdom
      ['tests/dom/**', 'jsdom'],
      // tutti i test in tests/ con .edge.test.ts verranno eseguiti in edge-runtime
      ['**/*.edge.test.ts', 'edge-runtime'],
      // ...
    ],
  },
});

poolMatchGlobs

• Tipo: [string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]
• Predefinito: []

DEPRECATO

Questa API è stata deprecata in Vitest 3. Usa i progetti per definire configurazioni diverse:

export default defineConfig({
  test: {
    poolMatchGlobs: [ 
      ['./*.threads.test.ts', 'threads'], 
    ], 
    projects: [ 
      { 
        test: { 
          extends: true, 
          pool: 'threads', 
        }, 
      }, 
    ], 
  },
})

Assegna automaticamente il pool in cui verranno eseguiti i test in base ai pattern glob. Verrà utilizzata la prima corrispondenza.

Ad esempio:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolMatchGlobs: [
      // tutti i test nella directory "worker-specific" verranno eseguiti all'interno di un worker come se avessi abilitato `--pool=threads` per essi,
      ['**/tests/worker-specific/**', 'threads'],
      // esegui tutti i test nella directory "browser" in un browser reale
      ['**/tests/browser/**', 'browser'],
      // tutti gli altri test verranno eseguiti in base alle opzioni "browser.enabled" e "threads", se non hai specificato altri glob
      // ...
    ],
  },
});

update*

• Tipo: boolean
• Predefinito: false
• CLI: -u, --update, --update=false

Aggiorna i file di snapshot. Questo aggiornerà tutti gli snapshot modificati ed eliminerà quelli non più necessari.

watch*

• Tipo: boolean
• Predefinito: !process.env.CI && process.stdin.isTTY
• CLI: -w, --watch, --watch=false

Attiva la modalità watch.

Negli ambienti interattivi, questo è il valore predefinito, a meno che non sia specificato esplicitamente --run.

In CI, o quando eseguito da una shell non interattiva, la modalità "watch" non è il valore predefinito, ma può essere abilitata esplicitamente con questo flag.

watchTriggerPatterns 3.2.0+ *

• Tipo: WatcherTriggerPattern[]

Vitest riesegue i test in base al grafo dei moduli, che è costruito dalle istruzioni import statiche e dinamiche. Tuttavia, se stai leggendo dal file system o recuperando da un proxy, Vitest non può rilevare tali dipendenze.

Per rieseguire correttamente tali test, puoi definire un pattern regex e una funzione che restituisce un elenco di file di test da eseguire.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    watchTriggerPatterns: [
      {
        pattern: /^src\/(mailers|templates)\/(.*)\.(ts|html|txt)$/,
        testToRun: (id, match) => {
          // relativo al valore root
          return `./api/tests/mailers/${match[2]}.test.ts`;
        },
      },
    ],
  },
});

WARNING

I file restituiti devono essere assoluti o relativi alla radice. Nota che questa è un'opzione globale e non può essere utilizzata all'interno delle configurazioni di progetto.

root

• Tipo: string
• CLI: -r <path>, --root=<path>

Radice del progetto.

dir

• Tipo: string
• CLI: --dir=<path>
• Predefinito: uguale a root

Directory di base da scansionare per i file di test. Puoi specificare questa opzione per velocizzare la scoperta dei test se la tua directory radice include l'intero progetto.

reporters*

• Tipo: Reporter | Reporter[]
• Predefinito: 'default'
• CLI: --reporter=<name>, --reporter=<name1> --reporter=<name2>

Reporter personalizzati per la generazione dell'output. I reporter possono essere un'istanza Reporter, una stringa per selezionare i reporter integrati, o il percorso di un'implementazione personalizzata (es. './path/to/reporter.ts', '@scope/reporter').

outputFile*

• Tipo: string | Record<string, string>
• CLI: --outputFile=<path>, --outputFile.json=./path

Scrive i risultati dei test in un file quando è specificata anche l'opzione --reporter=json, --reporter=html o --reporter=junit. Fornendo un oggetto invece di una stringa puoi definire output specifici per ciascun reporter quando ne usi più di uno.

pool*

• Tipo: 'threads' | 'forks' | 'vmThreads' | 'vmForks'
• Predefinito: 'forks'
• CLI: --pool=threads

Pool utilizzato per eseguire i test.

threads*

Abilita il multi-threading usando tinypool (un fork leggero di Piscina). Quando si usano i thread non è possibile utilizzare API relative ai processi come process.chdir(). Alcune librerie scritte in linguaggi nativi, come Prisma, bcrypt e canvas, hanno problemi quando vengono eseguite in più thread e possono causare errori di segmentazione (segfault). In questi casi è consigliabile usare il pool forks.

forks*

Simile al pool threads ma utilizza child_process invece di worker_threads tramite tinypool. La comunicazione tra i test e il processo principale non è altrettanto veloce come con il pool threads. Le API relative ai processi come process.chdir() sono disponibili nel pool forks.

vmThreads*

Esegue i test utilizzando il contesto VM (all'interno di un ambiente sandbox) in un pool di threads.

Questo rende i test più veloci, ma il modulo VM è instabile quando si esegue il codice ESM. I tuoi test potrebbero causare perdite di memoria - per ovviare a questo, considera di modificare manualmente il valore di poolOptions.vmThreads.memoryLimit.

WARNING

L'esecuzione di codice in una sandbox ha alcuni vantaggi (test più veloci), ma comporta anche una serie di svantaggi.

• Le variabili globali all'interno dei moduli nativi, come (fs, path, ecc.), differiscono dalle variabili globali presenti nel tuo ambiente di test. Di conseguenza, qualsiasi errore lanciato da questi moduli nativi farà riferimento a un costruttore di errori diverso rispetto a quello utilizzato nel tuo codice:

try {
  fs.writeFileSync('/doesnt exist');
} catch (err) {
  console.log(err instanceof Error); // false
}

• L'importazione di moduli ES li memorizza nella cache in modo indefinito, il che introduce perdite di memoria se si hanno molti contesti (file di test). Non esiste un'API in Node.js che permetta di svuotare quella cache.
• L'accesso alle variabili globali richiede più tempo in un ambiente sandbox.

Si prega di tenere presente questi problemi quando si utilizza questa opzione. Il team di Vitest non può risolvere nessuno di questi problemi autonomamente.

vmForks*

Simile al pool vmThreads ma utilizza child_process invece di worker_threads tramite tinypool. La comunicazione tra i test e il processo principale non è altrettanto veloce come con il pool vmThreads. Le API relative ai processi come process.chdir() sono disponibili nel pool vmForks. Si prega di notare che questo pool presenta gli stessi inconvenienti elencati in vmThreads.

poolOptions*

• Tipo: Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>
• Predefinito: {}

poolOptions.threads

Opzioni per il pool threads.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        // Opzioni relative ai thread qui
      },
    },
  },
});

poolOptions.threads.maxThreads*

• Tipo: number | string
• Predefinito: CPU disponibili

Numero massimo o percentuale di thread da utilizzare. Puoi anche usare la variabile d'ambiente VITEST_MAX_THREADS.

poolOptions.threads.minThreads*

• Tipo: number | string
• Predefinito: CPU disponibili

Numero minimo o percentuale di thread da utilizzare. Puoi anche usare la variabile d'ambiente VITEST_MIN_THREADS.

poolOptions.threads.singleThread

• Tipo: boolean
• Predefinito: false

Esegue tutti i test con lo stesso ambiente in un singolo thread worker. Questo disattiverà l'isolamento del modulo integrato (il tuo codice sorgente o il codice inlined verrà comunque rivalutato per ogni test), ma può migliorare le prestazioni dei test.

WARNING

Anche se questa opzione forzerà l'esecuzione sequenziale dei test, è diversa da --runInBand di Jest. Vitest utilizza i worker non solo per eseguire i test in parallelo, ma anche per fornire isolamento. Disabilitando questa opzione, i tuoi test verranno eseguiti sequenzialmente, ma nello stesso contesto globale, quindi dovrai gestire l'isolamento autonomamente.

Questo potrebbe causare diversi tipi di problemi, se ti affidi allo stato globale (come spesso accade nei framework frontend) o se il tuo codice richiede che l'ambiente sia definito separatamente per ogni test. Tuttavia, può accelerare i tuoi test (fino a 3 volte più veloci), specialmente quelli che non si basano necessariamente sullo stato globale o che possono facilmente aggirare tale dipendenza.

poolOptions.threads.useAtomics*

• Tipo: boolean
• Predefinito: false

Utilizza Atomics per sincronizzare i thread.

Questo può migliorare le prestazioni in alcuni casi, ma potrebbe causare errori di segmentazione (segfault) in versioni più vecchie di Node.

poolOptions.threads.isolate

• Type: boolean
• Default: true

Isola l'ambiente per ogni file di test.

poolOptions.threads.execArgv*

• Tipo: string[]
• Predefinito: []

Passa argomenti aggiuntivi a node nei thread. Vedi Command-line API | Node.js per maggiori informazioni.

WARNING

Fai attenzione quando lo usi, poiché alcune opzioni potrebbero causare il blocco del worker, ad esempio --prof, --title. Vedi https://github.com/nodejs/node/issues/41103.

poolOptions.forks

Opzioni per il pool forks.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      forks: {
        // Opzioni relative ai fork qui
      },
    },
  },
});

poolOptions.forks.maxForks*

• Tipo: number | string
• Predefinito: CPU disponibili

Numero massimo o percentuale di fork da utilizzare. Puoi anche usare la variabile d'ambiente VITEST_MAX_FORKS.

poolOptions.forks.minForks*

• Tipo: number | string
• Predefinito: CPU disponibili

Numero minimo o percentuale di fork da utilizzare. Puoi anche usare la variabile d'ambiente VITEST_MIN_FORKS.

poolOptions.forks.isolate

• Tipo: boolean
• Predefinito: true

Isola l'ambiente per ogni file di test.

poolOptions.forks.singleFork*

• Tipo: boolean
• Predefinito: false

Esegue tutti i test con lo stesso ambiente in un singolo processo figlio. Questo disattiverà l'isolamento del modulo integrato (il tuo codice sorgente o il codice inlined verrà comunque rivalutato per ogni test), ma può migliorare le prestazioni dei test.

WARNING

Anche se questa opzione forzerà l'esecuzione sequenziale dei test, è diversa da --runInBand di Jest. Vitest utilizza i processi figlio non solo per eseguire i test in parallelo, ma anche per fornire isolamento. Disabilitando questa opzione, i tuoi test verranno eseguiti sequenzialmente, ma nello stesso contesto globale, quindi dovrai gestire l'isolamento autonomamente.

Questo potrebbe causare diversi tipi di problemi, se ti affidi allo stato globale (come spesso accade nei framework frontend) o se il tuo codice richiede che l'ambiente sia definito separatamente per ogni test. Tuttavia, può accelerare i tuoi test (fino a 3 volte più veloci), specialmente quelli che non si basano necessariamente sullo stato globale o che possono facilmente aggirare tale dipendenza.

poolOptions.forks.execArgv*

• Tipo: string[]
• Predefinito: []

Passa argomenti aggiuntivi al processo node nei processi figlio. Vedi Command-line API | Node.js per maggiori informazioni.

WARNING

Fai attenzione quando lo usi, poiché alcune opzioni potrebbero causare il blocco del worker, ad esempio --prof, --title. Vedi https://github.com/nodejs/node/issues/41103.

poolOptions.vmThreads

Opzioni per il pool vmThreads.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmThreads: {
        // Opzioni relative ai thread VM qui
      },
    },
  },
});

poolOptions.vmThreads.maxThreads*

• Tipo: number | string
• Predefinito: CPU disponibili

Numero massimo o percentuale di thread da utilizzare. Puoi anche usare la variabile d'ambiente VITEST_MAX_THREADS.

poolOptions.vmThreads.minThreads*

• Tipo: number | string
• Predefinito: CPU disponibili

Numero minimo o percentuale di thread da utilizzare. Puoi anche usare la variabile d'ambiente VITEST_MIN_THREADS.

poolOptions.vmThreads.memoryLimit*

• Tipo: string | number
• Predefinito: 1 / CPU Cores

Specifica il limite di memoria per i worker prima che vengano riavviati. Questo valore dipende fortemente dal tuo ambiente, quindi è consigliabile specificarlo manualmente invece di affidarsi al valore predefinito.

TIP

L'implementazione si basa su workerIdleMemoryLimit di Jest.

Il limite può essere specificato in diversi modi. Indipendentemente dal formato, Math.floor viene utilizzato per trasformarlo in un valore intero:

• <= 1 - Il valore è interpretato come una percentuale della memoria di sistema. Quindi 0.5 imposta il limite di memoria del worker a metà della memoria totale del sistema.
• > 1 - Interpretato come un valore fisso in byte. A causa della regola precedente, se si volesse un valore di 1 byte (per ragioni non specificate) si potrebbe usare 1.1.
• Con unità
  • 50% - Come sopra, una percentuale della memoria totale del sistema.
  • 100KB, 65MB, ecc. - Con unità per indicare un limite di memoria fisso.
    • K / KB - Kilobyte (x1000)
    • KiB - Kibibyte (x1024)
    • M / MB - Megabyte - MiB - Mebibyte
    • G / GB - Gigabyte - GiB - Gibibyte

WARNING

Il limite di memoria basato sulla percentuale non funziona su Linux CircleCI a causa di una rilevazione errata della memoria di sistema.

poolOptions.vmThreads.useAtomics*

• Tipo: boolean
• Predefinito: false

Utilizza Atomics per sincronizzare i thread.

Questo può migliorare le prestazioni in alcuni casi, ma potrebbe causare errori di segmentazione (segfault) in versioni più vecchie di Node.

poolOptions.vmThreads.execArgv*

• Tipo: string[]
• Predefinito: []

Passa argomenti aggiuntivi al processo node nel contesto VM. Vedi Command-line API | Node.js per maggiori informazioni.

WARNING

Fai attenzione quando lo usi, poiché alcune opzioni potrebbero causare il blocco del worker, ad esempio --prof, --title. Vedi https://github.com/nodejs/node/issues/41103.

poolOptions.vmForks*

Opzioni per il pool vmForks.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmForks: {
        // Opzioni relative ai fork VM qui
      },
    },
  },
});

poolOptions.vmForks.maxForks*

• Tipo: number | string
• Predefinito: CPU disponibili

Numero massimo o percentuale di fork da utilizzare. Puoi anche usare la variabile d'ambiente VITEST_MAX_FORKS.

poolOptions.vmForks.minForks*

• Tipo: number | string
• Predefinito: CPU disponibili

Numero minimo o percentuale di fork da utilizzare. Puoi anche usare la variabile d'ambiente VITEST_MIN_FORKS.

poolOptions.vmForks.memoryLimit*

• Tipo: string | number
• Predefinito: 1 / CPU Cores

Specifica il limite di memoria per i worker prima che vengano riavviati. Questo valore dipende fortemente dal tuo ambiente, quindi è consigliabile specificarlo manualmente invece di affidarsi al valore predefinito. Il calcolo del valore è descritto in poolOptions.vmThreads.memoryLimit

poolOptions.vmForks.execArgv*

• Tipo: string[]
• Predefinito: []

Passa argomenti aggiuntivi al processo node nel contesto VM. Vedi Command-line API | Node.js per maggiori informazioni.

WARNING

Fai attenzione quando lo usi, poiché alcune opzioni potrebbero causare il blocco del worker, ad esempio --prof, --title. Vedi https://github.com/nodejs/node/issues/41103.

fileParallelism*

• Tipo: boolean
• Predefinito: true
• CLI: --no-file-parallelism, --fileParallelism=false

Indica se tutti i file di test devono essere eseguiti in parallelo. Impostando questo su false, le opzioni maxWorkers e minWorkers verranno sovrascritte a 1.

TIP

Questa opzione non influisce sui test eseguiti all'interno dello stesso file. Se vuoi eseguirli in parallelo, utilizza l'opzione concurrent su describe o tramite una configurazione.

maxWorkers*

• Tipo: number | string

Numero massimo o percentuale di worker da utilizzare per l'esecuzione dei test. poolOptions.{threads,vmThreads}.maxThreads/poolOptions.forks.maxForks ha priorità più alta.

minWorkers*

• Tipo: number | string

Numero minimo o percentuale di worker da utilizzare per l'esecuzione dei test. poolOptions.{threads,vmThreads}.minThreads/poolOptions.forks.minForks ha priorità più alta.

testTimeout

• Tipo: number
• Predefinito: 5_000 in Node.js, 15_000 se browser.enabled è true
• CLI: --test-timeout=5000, --testTimeout=5000

Timeout predefinito per un test in millisecondi. Utilizza 0 per disabilitare completamente il timeout.

hookTimeout

• Tipo: number
• Predefinito: 10_000 in Node.js, 30_000 se browser.enabled è true
• CLI: --hook-timeout=10000, --hookTimeout=10000

Timeout predefinito per un hook in millisecondi. Utilizza 0 per disabilitare completamente il timeout.

teardownTimeout*

• Tipo: number
• Predefinito: 10000
• CLI: --teardown-timeout=5000, --teardownTimeout=5000

Timeout predefinito in millisecondi per l'attesa della chiusura di Vitest durante lo spegnimento.

silent*

• Tipo: boolean | 'passed-only'
• Predefinito: false
• CLI: --silent, --silent=false

Sopprime l'output della console dai test.

Usa 'passed-only' per visualizzare i log solo dai test falliti. I log dai test falliti vengono stampati al termine del test.

setupFiles

• Tipo: string | string[]

Specifica il percorso dei file di setup. Questi verranno eseguiti prima di ogni file di test.

INFO

La modifica di un file di setup attiverà automaticamente una riesecuzione di tutti i test.

Puoi usare process.env.VITEST_POOL_ID (una stringa numerica) per distinguere tra i thread.

TIP

Nota che se stai eseguendo --isolate=false, questo file di setup verrà eseguito più volte nello stesso ambito globale. Ciò significa che stai accedendo allo stesso oggetto globale prima di ogni test, quindi assicurati di non ripetere operazioni non necessarie.

Ad esempio, potresti fare affidamento su una variabile globale:

import { config } from '@some-testing-lib';

if (!globalThis.defined) {
  config.plugins = [myCoolPlugin];
  computeHeavyThing();
  globalThis.defined = true;
}

// gli hook vengono resettati prima di ogni suite
afterEach(() => {
  cleanup();
});

globalThis.resetBeforeEachTest = true;

provide 2.1.0+

• Tipo: Partial<ProvidedContext>

Definisce i valori a cui è possibile accedere all'interno dei test utilizzando il metodo inject.

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    provide: {
      API_KEY: '123',
    },
  },
});

api.test.js

import { expect, inject, test } from 'vitest';

test('api key is defined', () => {
  expect(inject('API_KEY')).toBe('123');
});

WARNING

Le proprietà devono essere stringhe e i valori devono essere serializzabili perché questo oggetto verrà trasferito tra processi separati.

TIP

Se stai usando TypeScript, dovrai estendere il tipo ProvidedContext per un accesso tipizzato in modo sicuro:

declare module 'vitest' {
  export interface ProvidedContext {
    API_KEY: string;
  }
}

// contrassegna questo file come modulo in modo che l'estensione funzioni correttamente
export {};

globalSetup

• Tipo: string | string[]

Specifica il percorso dei file di setup globali, relativo alla radice del progetto.

Un file di setup globale può esportare le funzioni setup e teardown o una funzione default che restituisce una funzione di teardown (esempio).

INFO

Sono possibili più file globalSetup. setup e teardown vengono eseguiti sequenzialmente, con teardown in ordine inverso.

WARNING

Il setup globale viene eseguito solo se è presente almeno un test in esecuzione. Ciò significa che il setup globale potrebbe iniziare a essere eseguito in modalità watch dopo la modifica di un file di test (il file di test attenderà che il setup globale termini prima di essere eseguito).

Tieni presente che il setup globale viene eseguito in un ambito globale diverso, quindi i tuoi test non hanno accesso alle variabili definite qui. Tuttavia, puoi fornire dati serializzabili ai test tramite il metodo provide:

example.test.js

import { inject } from 'vitest';

inject('wsPort') === 3000;

globalSetup.ts 3.0.0+

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

export default function setup(project: TestProject) {
  project.provide('wsPort', 3000);
}

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

globalSetup.ts 2.0.0+

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

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

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

A partire da Vitest 3, puoi definire una funzione di callback personalizzata che verrà invocata quando Vitest riesegue i test. Se la funzione è asincrona, il runner attenderà il suo completamento prima di eseguire i test. Nota che non puoi destrutturare il project come { onTestsRerun } perché dipende dal contesto.

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

export default function setup(project: TestProject) {
  project.onTestsRerun(async () => {
    await restartDb();
  });
}

forceRerunTriggers*

• Tipo: string[]
• Predefinito: ['**/package.json/**', '**/vitest.config.*/**', '**/vite.config.*/**']

Pattern glob per i percorsi dei file che attiveranno la riesecuzione dell'intera suite. Quando combinato con l'argomento --changed, eseguirà l'intera suite di test se il trigger viene trovato nel diff di Git.

Utile se stai testando l'invocazione di comandi CLI, poiché Vite non può costruire un grafo di moduli:

test('execute a script', async () => {
  // Vitest non può rieseguire questo test se il contenuto di `dist/index.js` viene modificato
  await execa('node', ['dist/index.js']);
});

TIP

Assicurati che i tuoi file non siano ignorati da server.watch.ignored.

coverage*

Puoi usare v8, istanbul o una soluzione di copertura personalizzata per la raccolta dei dati di copertura.

Puoi fornire opzioni di copertura alla CLI utilizzando la notazione a punti:

npx vitest --coverage.enabled --coverage.provider=istanbul --coverage.all

WARNING

Se stai utilizzando le opzioni di copertura con la notazione a punti, non dimenticare di specificare --coverage.enabled. In tal caso, non fornire una singola opzione --coverage.

coverage.provider

• Tipo: 'v8' | 'istanbul' | 'custom'
• Predefinito: 'v8'
• CLI: --coverage.provider=<provider>

Utilizza provider per selezionare lo strumento per la raccolta della copertura.

coverage.enabled

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.enabled, --coverage.enabled=false

Attiva la raccolta della copertura. Può essere sovrascritto usando l'opzione CLI --coverage.

coverage.include

• Tipo: string[]
• Predefinito: ['**']
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.include=<path>, --coverage.include=<path1> --coverage.include=<path2>

Elenco di file da includere nella copertura come pattern glob.

coverage.extension

• Tipo: string | string[]
• Predefinito: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.tsx', '.jsx', '.vue', '.svelte', '.marko', '.astro']
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

coverage.exclude

• Tipo: string[]
• Predefinito:

[
  'coverage/**',
  'dist/**',
  '**/node_modules/**',
  '**/[.]**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec,bench,benchmark}?(-d).?(c|m)[jt]s?(x)',
  '**/__tests__/**',
  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*',
  '**/vitest.{workspace,projects}.[jt]s?(on)',
  '**/.{eslint,mocha,prettier}rc.{?(c|m)js,yml}',
];

• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

Elenco di file da escludere dalla copertura come pattern glob.

Questa opzione sovrascrive tutte le configurazioni predefinite. Estendi le configurazioni predefinite quando aggiungi nuovi pattern da ignorare:

import { coverageConfigDefaults, defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      exclude: ['**/custom-pattern/**', ...coverageConfigDefaults.exclude],
    },
  },
});

NOTA

Vitest aggiunge automaticamente i pattern include dei file di test a coverage.exclude. Non è possibile visualizzare la copertura dei file di test.

coverage.all

• Tipo: boolean
• Predefinito: true
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.all, --coverage.all=false

Indica se includere tutti i file, inclusi quelli non testati, nel report.

coverage.clean

• Tipo: boolean
• Predefinito: true
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.clean, --coverage.clean=false

Cancella i risultati della copertura prima di eseguire i test.

coverage.cleanOnRerun

• Tipo: boolean
• Predefinito: true
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

Cancella il report di copertura alla riesecuzione in modalità watch. Imposta su false per conservare i risultati della copertura dall'esecuzione precedente in modalità watch.

coverage.reportsDirectory

• Tipo: string
• Predefinito: './coverage'
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.reportsDirectory=<path>

WARNING

Vitest eliminerà questa directory prima di eseguire i test se coverage.clean è attivo (valore predefinito).

Directory di destinazione per il report di copertura.

Per visualizzare in anteprima il report di copertura nell'output del reporter HTML, questa opzione deve essere configurata come sottodirectory della directory del report HTML (ad esempio ./html/coverage).

coverage.reporter

• Tipo: string | string[] | [string, {}][]
• Predefinito: ['text', 'html', 'clover', 'json']
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.reporter=<reporter>, --coverage.reporter=<reporter1> --coverage.reporter=<reporter2>

Specifica i reporter di copertura da utilizzare. Consulta la documentazione di istanbul per un elenco dettagliato di tutti i reporter. Consulta @types/istanbul-reporter per i dettagli sulle opzioni specifiche del reporter.

Il reporter può essere configurato in tre modi diversi:

• Come singolo reporter: { reporter: 'html' }
• Come più reporter senza opzioni: { reporter: ['html', 'json'] }
• Come uno o più reporter con opzioni specifiche:

  {
    reporter: [
      ['lcov', { projectRoot: './src' }],
      ['json', { file: 'coverage.json' }],
      ['text'],
    ];
  }

Puoi anche passare reporter di copertura personalizzati. Vedi Guida - Reporter di Copertura Personalizzato per maggiori informazioni.

{
  reporter: [
    // Specifica il reporter usando il nome del pacchetto NPM
    '@vitest/custom-coverage-reporter',
    ['@vitest/custom-coverage-reporter', { someOption: true }],

    // Specifica il reporter usando il percorso locale
    '/absolute/path/to/custom-reporter.cjs',
    ['/absolute/path/to/custom-reporter.cjs', { someOption: true }],
  ];
}

Puoi visualizzare il tuo report di copertura nell'interfaccia utente di Vitest: consulta Vitest UI Coverage per maggiori dettagli.

coverage.reportOnFailure

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.reportOnFailure, --coverage.reportOnFailure=false

Genera il report di copertura anche in caso di fallimento dei test.

coverage.allowExternal

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.allowExternal, --coverage.allowExternal=false

Raccoglie la copertura dei file al di fuori della radice del progetto.

coverage.excludeAfterRemap 2.1.0+

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.excludeAfterRemap, --coverage.excludeAfterRemap=false

Applica nuovamente le esclusioni dopo che la copertura è stata rimappata ai file sorgente originali. Questo è utile quando i tuoi file sorgente sono transpilati e possono contenere mappe sorgente di file non originali.

Utilizza questa opzione quando noti file che compaiono nel report anche se corrispondono ai tuoi pattern coverage.exclude.

coverage.skipFull

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.skipFull, --coverage.skipFull=false

Non visualizza i file con copertura del 100% di istruzioni, rami e funzioni.

coverage.thresholds

Opzioni relative alle soglie di copertura.

Se una soglia è impostata su un numero positivo, viene interpretata come la percentuale minima di copertura richiesta. Ad esempio, impostare la soglia delle linee a 90 significa che il 90% delle linee deve essere coperto.

Se una soglia è impostata su un numero negativo, viene trattata come il numero massimo di elementi non coperti consentiti. Ad esempio, impostare la soglia delle linee a -10 significa che non più di 10 linee possono rimanere scoperte.

{
  coverage: {
    thresholds: {
      // Richiede il 90% di copertura delle funzioni
      functions: 90,

      // Richiede che non più di 10 linee siano scoperte
      lines: -10,
    }
  }
}

coverage.thresholds.lines

• Tipo: number
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.lines=<number>

Soglia globale per la copertura delle linee.

coverage.thresholds.functions

• Tipo: number
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.functions=<number>

Soglia globale per la copertura delle funzioni.

coverage.thresholds.branches

• Tipo: number
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.branches=<number>

Soglia globale per la copertura dei rami.

coverage.thresholds.statements

• Tipo: number
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.statements=<number>

Soglia globale per la copertura delle istruzioni.

coverage.thresholds.perFile

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.perFile, --coverage.thresholds.perFile=false

Verifica le soglie per file.

coverage.thresholds.autoUpdate

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.autoUpdate=<boolean>

Aggiorna tutti i valori di soglia lines, functions, branches e statements nel file di configurazione quando la copertura attuale supera le soglie configurate. Questa opzione aiuta a mantenere le soglie aggiornate quando la copertura migliora.

coverage.thresholds.100

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.100, --coverage.thresholds.100=false

Imposta le soglie globali al 100%. Abbreviazione per --coverage.thresholds.lines 100 --coverage.thresholds.functions 100 --coverage.thresholds.branches 100 --coverage.thresholds.statements 100.

coverage.thresholds[glob-pattern]

• Tipo: { statements?: number functions?: number branches?: number lines?: number }
• Predefinito: undefined
• Disponibile per i provider: 'v8' | 'istanbul'

Imposta le soglie per i file che corrispondono al pattern glob specificato.

NOTA

Vitest considera tutti i file, inclusi quelli coperti da pattern glob, nel calcolo delle soglie di copertura globali. Questo comportamento differisce da quello di Jest.

{
  coverage: {
    thresholds: {
      // Soglie per tutti i file
      functions: 95,
      branches: 70,

      // Soglie per il pattern glob corrispondente
      'src/utils/**.ts': {
        statements: 95,
        functions: 90,
        branches: 85,
        lines: 80,
      },

      // Per i file che corrispondono a questo pattern, verranno impostate solo le soglie delle linee.
      // Le soglie globali non vengono ereditate in questo caso.
      '**/math.ts': {
        lines: 100,
      }
    }
  }
}

coverage.thresholds[glob-pattern].100 2.1.0+

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8' | 'istanbul'

Imposta le soglie al 100% per i file che corrispondono al pattern glob.

{
  coverage: {
    thresholds: {
      // Soglie per tutti i file
      functions: 95,
      branches: 70,

      // Soglie per il pattern glob corrispondente
      'src/utils/**.ts': { 100: true },
      '**/math.ts': { 100: true }
    }
  }
}

coverage.ignoreEmptyLines

• Tipo: boolean
• Predefinito: true (false in v1)
• Disponibile per i provider: 'v8'
• CLI: --coverage.ignoreEmptyLines=<boolean>

Ignora le righe vuote, i commenti e altro codice non eseguibile, ad esempio i tipi Typescript. Richiede experimentalAstAwareRemapping: false.

Questa opzione funziona solo se il compilatore utilizzato rimuove i commenti e altro codice non eseguibile dal codice transpilato. Per impostazione predefinita, Vite utilizza ESBuild che rimuove i commenti e i tipi Typescript dai file .ts, .tsx e .jsx.

Se vuoi applicare ESBuild anche ad altri file, definiscili nelle opzioni esbuild:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  esbuild: {
    // Transpila tutti i file con ESBuild per rimuovere i commenti dalla copertura del codice.
    // Richiesto per il funzionamento di `test.coverage.ignoreEmptyLines`:
    include: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.ts', '**/*.tsx'],
  },
  test: {
    coverage: {
      provider: 'v8',
      ignoreEmptyLines: true,
    },
  },
});

coverage.experimentalAstAwareRemapping

• Tipo: boolean
• Predefinito: false
• Disponibile per i provider: 'v8'
• CLI: --coverage.experimentalAstAwareRemapping=<boolean>

Ricalcola la copertura con analisi sperimentale basata su AST. Offre risultati più accurati rispetto alla modalità predefinita.

coverage.ignoreClassMethods

• Tipo: string[]
• Predefinito: []
• Disponibile per i provider: 'istanbul'
• CLI: --coverage.ignoreClassMethods=<method>

Definisce un array di nomi di metodi di classe da ignorare per la copertura. Consulta la documentazione di istanbul per maggiori informazioni.

coverage.watermarks

• Tipo:

{
  statements?: [number, number],
  functions?: [number, number],
  branches?: [number, number],
  lines?: [number, number]
}

• Predefinito:

{
  statements: [50, 80],
  functions: [50, 80],
  branches: [50, 80],
  lines: [50, 80]
}

• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.watermarks.statements=50,80, --coverage.watermarks.branches=50,80

Definisce i watermark per istruzioni, linee, rami e funzioni. Consulta la documentazione di istanbul per maggiori informazioni.

coverage.processingConcurrency

• Tipo: boolean
• Predefinito: Math.min(20, os.availableParallelism?.() ?? os.cpus().length)
• Disponibile per i provider: 'v8' | 'istanbul'
• CLI: --coverage.processingConcurrency=<number>

Limite di concorrenza per l'elaborazione dei risultati della copertura.

coverage.customProviderModule

• Tipo: string
• Disponibile per i provider: 'custom'
• CLI: --coverage.customProviderModule=<path or module name>

Specifica il nome o il percorso del modulo per il provider di copertura personalizzato. Consulta Guida - Provider di Copertura Personalizzato per maggiori informazioni.

testNamePattern*

• Tipo string | RegExp
• CLI: -t <pattern>, --testNamePattern=<pattern>, --test-name-pattern=<pattern>

Esegue i test i cui nomi completi corrispondono al pattern. Se aggiungi OnlyRunThis a questa proprietà, i test che non contengono la parola OnlyRunThis nel loro nome verranno saltati.

import { expect, test } from 'vitest';

// esegui
test('OnlyRunThis', () => {
  expect(true).toBe(true);
});

// saltato
test('doNotRun', () => {
  expect(true).toBe(true);
});

open*

• Tipo: boolean
• Predefinito: !process.env.CI
• CLI: --open, --open=false

Apre l'interfaccia utente di Vitest (WIP).

api

• Tipo: boolean | number
• Predefinito: false
• CLI: --api, --api.port, --api.host, --api.strictPort

Ascolta la porta e fornisce l'API. Se impostato su true, la porta predefinita è 51204.

browser sperimentale

• Predefinito: { enabled: false }
• CLI: --browser=<name>, --browser.name=chrome --browser.headless

Configurazione per l'esecuzione dei test nel browser. Si prega di fare riferimento all'articolo "Riferimento Configurazione Browser".

WARNING

Questa è una funzionalità sperimentale. Le modifiche che causano interruzioni potrebbero non seguire SemVer; si consiglia di fissare la versione di Vitest quando la si utilizza.

clearMocks

• Tipo: boolean
• Predefinito: false

Invoca .mockClear() su tutti gli spy prima di ogni test. Questo cancellerà la cronologia dei mock senza alterare le implementazioni dei mock.

mockReset

• Tipo: boolean
• Predefinito: false

Invoca .mockReset() su tutti gli spy prima di ogni test. Questo cancellerà la cronologia dei mock e ripristinerà ogni implementazione al suo stato originale.

restoreMocks

• Tipo: boolean
• Predefinito: false

Invoca .mockRestore() su tutti gli spy prima di ogni test. Questo cancellerà la cronologia dei mock, ripristinerà ogni implementazione al suo stato originale e ripristinerà i descrittori originali degli oggetti spiati.

unstubEnvs

• Tipo: boolean
• Predefinito: false

Invoca vi.unstubAllEnvs prima di ogni test.

unstubGlobals

• Tipo: boolean
• Predefinito: false

Invoca vi.unstubAllGlobals prima di ogni test.

testTransformMode

• Tipo: { web?, ssr? }

Determina il metodo di trasformazione per tutti i moduli importati all'interno di un test che corrisponde al pattern glob. Per impostazione predefinita, si basa sull'ambiente di esecuzione. Ad esempio, i test con ambiente JSDOM elaboreranno tutti i file con il flag ssr: false, mentre i test con ambiente Node elaboreranno tutti i moduli con ssr: true.

testTransformMode.ssr

• Tipo: string[]
• Predefinito: []

Utilizza la pipeline di trasformazione SSR per tutti i moduli all'interno dei test specificati.
I plugin Vite riceveranno il flag ssr: true durante l'elaborazione di tali file.

testTransformMode.web

• Tipo: string[]
• Predefinito: []

Prima esegue una normale pipeline di trasformazione (mirata al browser), quindi esegue una riscrittura SSR per eseguire il codice in Node.
I plugin Vite riceveranno il flag ssr: false durante l'elaborazione di tali file.

snapshotFormat*

• Tipo: PrettyFormatOptions

Opzioni di formato per i test di snapshot. Queste opzioni sono passate a pretty-format.

TIP

Fai attenzione che il campo plugins di questo oggetto verrà ignorato.

Se hai bisogno di estendere il serializzatore di snapshot tramite plugin pretty-format, utilizza l'API expect.addSnapshotSerializer o l'opzione snapshotSerializers.

snapshotSerializers*

• Tipo: string[]
• Predefinito: []

Un elenco di percorsi a moduli serializzatori di snapshot per i test di snapshot, utile se si desidera aggiungere serializzatori di snapshot personalizzati. Consultare Serializzatore personalizzato per maggiori informazioni.

resolveSnapshotPath*

• Tipo: (testPath: string, snapExtension: string, context: { config: SerializedConfig }) => string
• Predefinito: memorizza i file snapshot nella directory __snapshots__

Sovrascrive il percorso predefinito dei file di snapshot. Ad esempio, per salvare gli snapshot accanto ai file di test:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension,
  },
});

allowOnly

• Tipo: boolean
• Predefinito: !process.env.CI
• CLI: --allowOnly, --allowOnly=false

Consente l'esecuzione di test e suite contrassegnati come "only".

dangerouslyIgnoreUnhandledErrors*

• Tipo: boolean
• Predefinito: false
• CLI: --dangerouslyIgnoreUnhandledErrors --dangerouslyIgnoreUnhandledErrors=false

Ignora eventuali errori non gestiti che si verificano durante l'esecuzione.

passWithNoTests*

• Tipo: boolean
• Predefinito: false
• CLI: --passWithNoTests, --passWithNoTests=false

Vitest non fallirà se non verranno trovati test.

logHeapUsage

• Tipo: boolean
• Predefinito: false
• CLI: --logHeapUsage, --logHeapUsage=false

Visualizza l'utilizzo dell'heap dopo ogni test. Utile per il debug di problemi di perdite di memoria.

css

• Tipo: boolean | { include?, exclude?, modules? }

Configura l'elaborazione dei file CSS. Quando esclusi, i file CSS verranno sostituiti con stringhe vuote per saltare la successiva elaborazione. I moduli CSS restituiranno un proxy per non influenzare il runtime.

css.include

• Tipo: RegExp | RegExp[]
• Predefinito: []

Pattern RegExp per i file che devono restituire CSS effettivo e che verranno elaborati dalla pipeline di Vite.

TIP

Per elaborare tutti i file CSS, utilizza /.+/.

css.exclude

• Tipo: RegExp | RegExp[]
• Predefinito: []

Pattern RegExp per i file che risulteranno in un file CSS vuoto.

css.modules

• Tipo: { classNameStrategy? }
• Predefinito: {}

css.modules.classNameStrategy

• Tipo: 'stable' | 'scoped' | 'non-scoped'
• Predefinito: 'stable'

Se decidi di elaborare i file CSS, puoi configurare se i nomi delle classi all'interno dei moduli CSS devono essere scopati. Puoi scegliere tra le seguenti opzioni:

• stable: i nomi delle classi verranno generati come _${name}_${hashedFilename}, il che implica che la classe generata rimarrà la stessa se il contenuto CSS viene modificato, ma cambierà se il nome del file viene modificato o il file viene spostato in un'altra cartella. Questa impostazione è utile se usi la funzionalità di snapshot.
• scoped: i nomi delle classi verranno generati come al solito, rispettando il metodo css.modules.generateScopedName, se presente e l'elaborazione CSS è abilitata. Per impostazione predefinita, il nome della classe verrà generato come _${name}_${hash}, dove l'hash include il nome del file e il contenuto del file.
• non-scoped: i nomi delle classi non verranno hassati.

WARNING

Per impostazione predefinita, Vitest esporta un proxy, saltando l'elaborazione dei moduli CSS. Se ti affidi alle proprietà CSS sulle tue classi, devi abilitare l'elaborazione CSS usando l'opzione include.

maxConcurrency

• Tipo: number
• Predefinito: 5
• CLI: --max-concurrency=10, --maxConcurrency=10

Il numero massimo di test che possono essere eseguiti contemporaneamente, contrassegnati con test.concurrent.

I test che superano questo limite verranno messi in coda per essere eseguiti quando sarà disponibile uno slot.

cache*

• Tipo: false
• CLI: --no-cache, --cache=false

Usa questa opzione se vuoi disabilitare la funzionalità di cache. Al momento Vitest memorizza i risultati dei test nella cache per eseguire prima i test più lunghi e falliti.

La directory della cache è definita dall'opzione cacheDir di Vite:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: 'custom-folder/.vitest',
});

Puoi limitare la directory solo per Vitest utilizzando process.env.VITEST:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: process.env.VITEST ? 'custom-folder/.vitest' : undefined,
});

sequence

• Tipo: { sequencer?, shuffle?, seed?, hooks?, setupFiles?, groupOrder }

Opzioni per l'ordinamento dei test.

Puoi fornire opzioni di sequenza alla CLI utilizzando la notazione a punti:

npx vitest --sequence.shuffle --sequence.seed=1000

sequence.sequencer*

• Tipo: TestSequencerConstructor
• Predefinito: BaseSequencer

Una classe personalizzata che implementa i metodi per lo sharding e l'ordinamento. Puoi estendere BaseSequencer da vitest/node se hai solo bisogno di ridefinire uno dei metodi sort e shard, ma entrambi devono essere presenti.

Lo sharding avviene prima dell'ordinamento, e solo se l'opzione --shard è fornita.

Se sequencer.groupOrder è specificato, il sequencer verrà chiamato una volta per ogni gruppo e pool.

groupOrder 3.2.0+

• Tipo: number
• Predefinito: 0

Controlla l'ordine di esecuzione dei test di questo progetto quando si utilizzano più progetti.

• I progetti con lo stesso numero di ordine di gruppo verranno eseguiti in parallelo, e i gruppi sono eseguiti in ordine crescente.
• Se questa opzione non è impostata, tutti i progetti vengono eseguiti in parallelo.
• Se più progetti utilizzano lo stesso ordine di gruppo, verranno eseguiti in parallelo.

Questa impostazione influisce solo sull'ordine di esecuzione dei progetti, non sull'ordine dei test all'interno di un singolo progetto. Per controllare l'isolamento dei test o l'ordine dei test all'interno di un progetto, utilizza le opzioni isolate e sequence.sequencer.

Esempio

Considera questo esempio:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'slow',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'fast',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'flaky',
          sequence: {
            groupOrder: 1,
          },
        },
      },
    ],
  },
});

I test in questi progetti verranno eseguiti in questo ordine:

 0. slow  |
          |> eseguiti in parallelo
 0. fast  |

 1. flaky |> viene eseguito dopo slow e fast, in modo indipendente

sequence.shuffle

• Tipo: boolean | { files?, tests? }
• Predefinito: false
• CLI: --sequence.shuffle, --sequence.shuffle=false

Se vuoi che i file e i test vengano eseguiti in modo casuale, puoi attivare questa opzione o utilizzare l'argomento CLI --sequence.shuffle.

Vitest di solito usa la cache per ordinare i test, in modo che i test a lunga esecuzione inizino prima, rendendo i test più veloci. Se i tuoi file e test verranno eseguiti in ordine casuale, perderai questo miglioramento delle prestazioni, ma potrebbe essere utile per identificare i test che dipendono accidentalmente da un'esecuzione precedente.

sequence.shuffle.files

• Tipo: boolean
• Predefinito: false
• CLI: --sequence.shuffle.files, --sequence.shuffle.files=false

Indica se randomizzare i file. Tieni presente che i test a lunga esecuzione non inizieranno prima se attivi questa opzione.

sequence.shuffle.tests

• Tipo: boolean
• Predefinito: false
• CLI: --sequence.shuffle.tests, --sequence.shuffle.tests=false

Indica se randomizzare i test.

sequence.concurrent

• Tipo: boolean
• Predefinito: false
• CLI: --sequence.concurrent, --sequence.concurrent=false

Se vuoi che i test vengano eseguiti in parallelo, puoi attivare questa opzione o utilizzare l'argomento CLI --sequence.concurrent.

sequence.seed*

• Tipo: number
• Predefinito: Date.now()
• CLI: --sequence.seed=1000

Imposta il seed di randomizzazione, se i test sono eseguiti in ordine casuale.

sequence.hooks

• Tipo: 'stack' | 'list' | 'parallel'
• Predefinito: 'stack'
• CLI: --sequence.hooks=<value>

Definisce l'ordine in cui vengono eseguiti gli hook.

• stack eseguirà gli hook "after" in ordine inverso, mentre gli hook "before" verranno eseguiti nell'ordine in cui sono stati definiti.
• list eseguirà tutti gli hook nell'ordine in cui sono definiti.
• parallel esegue gli hook in un singolo gruppo in parallelo (gli hook nelle suite genitore verranno comunque eseguiti prima degli hook della suite corrente).

TIP

Questa opzione non ha effetto su onTestFinished. È sempre chiamata in ordine inverso.

sequence.setupFiles

• Tipo: 'list' | 'parallel'
• Predefinito: 'parallel'
• CLI: --sequence.setupFiles=<value>

Definisce l'ordine in cui vengono eseguiti i file di setup.

• list esegue i file di setup nell'ordine in cui sono definiti.
• parallel esegue i file di setup in parallelo.

typecheck

Opzioni per la configurazione dell'ambiente di test per il controllo dei tipi.

typecheck.enabled

• Tipo: boolean
• Predefinito: false
• CLI: --typecheck, --typecheck.enabled

Abilita il controllo dei tipi insieme ai tuoi test regolari.

typecheck.only

• Tipo: boolean
• Predefinito: false
• CLI: --typecheck.only

Esegue solo i test di controllo dei tipi, quando il controllo dei tipi è abilitato. Quando si utilizza la CLI, questa opzione abiliterà automaticamente il controllo dei tipi.

typecheck.checker

• Tipo: 'tsc' | 'vue-tsc' | string
• Predefinito: tsc

Specifica quali strumenti utilizzare per il controllo dei tipi. Vitest avvierà un processo con determinati parametri per facilitare l'analisi, a seconda del tipo. Il checker deve implementare lo stesso formato di output di tsc.

È necessario avere un pacchetto installato per utilizzare il typechecker:

• tsc richiede il pacchetto typescript
• vue-tsc richiede il pacchetto vue-tsc

Puoi anche specificare un percorso a un binario personalizzato o un nome di comando che produce lo stesso output di tsc --noEmit --pretty false.

typecheck.include

• Tipo: string[]
• Predefinito: ['**/*.{test,spec}-d.?(c|m)[jt]s?(x)']

Pattern glob per i file da trattare come file di test.

typecheck.exclude

• Tipo: string[]
• Predefinito: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**']

Pattern glob per i file da non trattare come file di test.

typecheck.allowJs

• Tipo: boolean
• Predefinito: false

Verifica i file JS che contengono il commento @ts-check. Se lo hai abilitato in tsconfig, questa opzione non lo sovrascriverà.

typecheck.ignoreSourceErrors

• Tipo: boolean
• Predefinito: false

Non causa il fallimento se Vitest trova errori al di fuori dei file di test. Questo non visualizzerà affatto errori non correlati ai test.

Per impostazione predefinita, se Vitest trova un errore nel codice sorgente, la suite di test fallirà.

typecheck.tsconfig

• Tipo: string
• Predefinito: cerca di trovare il tsconfig.json più vicino

Percorso del tsconfig personalizzato, relativo alla radice del progetto.

typecheck.spawnTimeout

• Tipo: number
• Predefinito: 10_000

Tempo minimo in millisecondi richiesto per avviare il typechecker.

slowTestThreshold*

• Tipo: number
• Predefinito: 300
• CLI: --slow-test-threshold=<number>, --slowTestThreshold=<number>

Il numero di millisecondi dopo il quale un test o una suite è considerato lento e viene segnalato come tale nei risultati.

chaiConfig

• Tipo: { includeStack?, showDiff?, truncateThreshold? }
• Predefinito: { includeStack: false, showDiff: true, truncateThreshold: 40 }

Corrisponde alla configurazione di Chai.

chaiConfig.includeStack

• Tipo: boolean
• Predefinito: false

Determina se la traccia dello stack è inclusa nel messaggio di errore di asserzione. Il valore predefinito false sopprime la visualizzazione della traccia dello stack nel messaggio di errore.

chaiConfig.showDiff

• Tipo: boolean
• Predefinito: true

Determina se il flag showDiff deve essere incluso o meno negli AssertionErrors generati. false sarà sempre false; true sarà true quando l'asserzione ha richiesto che una differenza venga mostrata.

chaiConfig.truncateThreshold

• Tipo: number
• Predefinito: 40

Definisce la soglia di lunghezza per i valori effettivi e attesi negli errori di asserzione. Se questa soglia viene superata, ad esempio per grandi strutture di dati, il valore viene sostituito con una rappresentazione abbreviata come [ Array(3) ] o { Object (prop1, prop2) }. Impostalo su 0 per disabilitare completamente il troncamento.

Questa opzione di configurazione influisce sul troncamento dei valori nei titoli test.each e nel messaggio di errore di asserzione.

bail

• Tipo: number
• Predefinito: 0
• CLI: --bail=<value>

Interrompe l'esecuzione dei test quando un numero specificato di test è fallito.

Per impostazione predefinita, Vitest eseguirà tutti i casi di test anche se alcuni di essi falliscono. Questo potrebbe non essere desiderabile per le build CI, dove si è interessati solo a build con successo al 100% e si desidera interrompere l'esecuzione dei test il prima possibile in caso di errori. L'opzione bail può essere utilizzata per velocizzare le esecuzioni CI impedendo l'esecuzione di ulteriori test una volta che si sono verificati dei fallimenti.

retry

• Tipo: number
• Predefinito: 0
• CLI: --retry=<value>

Riprova il test un numero specifico di volte in caso di fallimento.

onConsoleLog*

• Tipo: (log: string, type: 'stdout' | 'stderr') => boolean | void

Gestore personalizzato per console.log durante i test. Se restituisci false, Vitest non visualizzerà il log sulla console.

Può essere utile per filtrare i log provenienti da librerie di terze parti.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onConsoleLog(log: string, type: 'stdout' | 'stderr'): boolean | void {
      return !(log === 'message from third party library' && type === 'stdout');
    },
  },
});

onStackTrace*

• Tipo: (error: Error, frame: ParsedStack) => boolean | void

Applica una funzione di filtro a ogni frame di ogni stack trace durante la gestione degli errori. Il primo argomento, error, è un oggetto con le stesse proprietà di un Error standard, ma non è un'istanza reale.

Può essere utile per filtrare i frame della stack trace provenienti da librerie di terze parti.

import type { ParsedStack } from 'vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onStackTrace(error: Error, { file }: ParsedStack): boolean | void {
      // Se abbiamo incontrato un ReferenceError, visualizza l'intera stack.
      if (error.name === 'ReferenceError') {
        return;
      }

      // Esclude tutti i frame dalle librerie di terze parti.
      if (file.includes('node_modules')) {
        return false;
      }
    },
  },
});

diff

• Tipo: string
• CLI: --diff=<path>

Oggetto DiffOptions o il percorso di un modulo che esporta DiffOptions. Utile per personalizzare la visualizzazione del diff.

Ad esempio, come oggetto di configurazione:

import { defineConfig } from 'vitest/config';
import c from 'picocolors';

export default defineConfig({
  test: {
    diff: {
      aIndicator: c.bold('--'),
      bIndicator: c.bold('++'),
      omitAnnotationLines: true,
    },
  },
});

O come modulo:

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    diff: './vitest.diff.ts',
  },
});

vitest.diff.ts

import type { DiffOptions } from 'vitest';
import c from 'picocolors';

export default {
  aIndicator: c.bold('--'),
  bIndicator: c.bold('++'),
  omitAnnotationLines: true,
} satisfies DiffOptions;

diff.expand

• Tipo: boolean
• Predefinito: true
• CLI: --diff.expand=false

Espande tutte le linee comuni.

diff.truncateThreshold

• Tipo: number
• Predefinito: 0
• CLI: --diff.truncateThreshold=<path>

La lunghezza massima del risultato del diff da visualizzare. I diff che superano questa soglia verranno troncati. Il troncamento non avrà effetto con il valore predefinito 0.

diff.truncateAnnotation

• Tipo: string
• Predefinito: '... Diff result is truncated'
• CLI: --diff.truncateAnnotation=<annotation>

Annotazione visualizzata alla fine del risultato del diff se troncato.

diff.truncateAnnotationColor

• Tipo: DiffOptionsColor = (arg: string) => string
• Predefinito: noColor = (string: string): string => string

Colore dell'annotazione di troncamento; il valore predefinito è senza colore.

diff.printBasicPrototype

• Tipo: boolean
• Predefinito: false

Stampa il prototipo di base Object e Array nell'output del diff.

diff.maxDepth

• Tipo: number
• Predefinito: 20 (o 8 quando si confrontano tipi diversi)

Limita la profondità di ricorsione durante la stampa di oggetti annidati.

fakeTimers

• Tipo: FakeTimerInstallOpts

Opzioni che Vitest passerà a @sinon/fake-timers quando si utilizza vi.useFakeTimers().

fakeTimers.now

• Tipo: number | Date
• Predefinito: Date.now()

Installa timer simulati con l'epoca Unix specificata.

fakeTimers.toFake

• Tipo: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]
• Predefinito: tutto ciò che è disponibile globalmente tranne nextTick e queueMicrotask

Un array con i nomi dei metodi globali e delle API da simulare.

Per simulare solo setTimeout() e nextTick(), specifica questa proprietà come ['setTimeout', 'nextTick'].

La simulazione di nextTick non è supportata quando si esegue Vitest all'interno di node:child_process usando --pool=forks. NodeJS utilizza process.nextTick internamente in node:child_process e si blocca quando viene simulato. La simulazione di nextTick è supportata quando si esegue Vitest con --pool=threads.

fakeTimers.loopLimit

• Tipo: number
• Predefinito: 10_000

Il numero massimo di timer che verranno eseguiti quando si invoca vi.runAllTimers().

fakeTimers.shouldAdvanceTime

• Tipo: boolean
• Predefinito: false

Indica a @sinonjs/fake-timers di incrementare automaticamente il tempo simulato in base alla variazione del tempo di sistema reale (ad esempio, il tempo simulato verrà incrementato di 20ms per ogni variazione di 20ms nel tempo di sistema reale).

fakeTimers.advanceTimeDelta

• Tipo: number
• Predefinito: 20

Rilevante solo se utilizzato con shouldAdvanceTime: true. Incrementa il tempo simulato di advanceTimeDelta ms ogni advanceTimeDelta ms di variazione nel tempo di sistema reale.

fakeTimers.shouldClearNativeTimers

• Tipo: boolean
• Predefinito: true

Indica ai timer simulati di cancellare i timer "nativi" (cioè non simulati) delegando ai rispettivi gestori. Quando disabilitato, può portare a un comportamento potenzialmente inaspettato se i timer esistevano prima di avviare la sessione dei timer simulati.

workspace*

DEPRECATO

Questa opzione è deprecata e verrà rimossa nella prossima versione major. Utilizzare projects invece.

• Tipo: string | TestProjectConfiguration[]
• CLI: --workspace=./file.js
• Predefinito: vitest.{workspace,projects}.{js,ts,json} vicino al file di configurazione o alla radice

Specifica il percorso di un file di configurazione workspace relativo a root.

A partire da Vitest 3, puoi anche definire l'array del workspace nella configurazione radice. Se il workspace è definito manualmente nella configurazione, Vitest ignorerà il file vitest.workspace nella directory radice.

projects*

• Tipo: TestProjectConfiguration[]
• Predefinito: []

Un array di configurazioni di progetti.

isolate

• Tipo: boolean
• Predefinito: true
• CLI: --no-isolate, --isolate=false

Esegue i test in un ambiente isolato. Questa opzione non ha alcun effetto sui pool vmThreads e vmForks.

Disabilitare questa opzione potrebbe migliorare le prestazioni se il tuo codice non dipende da effetti collaterali (il che è solitamente vero per i progetti con ambiente node).

TIP

Puoi disabilitare l'isolamento per pool specifici utilizzando la proprietà poolOptions.

includeTaskLocation

• Tipo: boolean
• Predefinito: false

La proprietà location deve essere inclusa quando l'API Vitest elabora i task nei reporter. Se hai molti test, questo potrebbe causare una leggera regressione delle prestazioni.

La proprietà location include i valori column e line che corrispondono alla posizione del test o describe nel file originale.

Questa opzione verrà abilitata automaticamente se non la disabiliti esplicitamente, e stai eseguendo Vitest con:

• Vitest UI
• o utilizzando la Modalità Browser senza modalità headless
• o usando HTML Reporter

TIP

Questa opzione non ha effetto se non utilizzi codice personalizzato che dipende da essa.

snapshotEnvironment

• Tipo: string

Specifica il percorso di un'implementazione personalizzata dell'ambiente snapshot. Questo è utile se stai eseguendo i test in un ambiente che non supporta le API di Node.js. Questa opzione non ha alcun effetto su un runner del browser.

Questo oggetto deve rispettare l'interfaccia SnapshotEnvironment ed è utilizzato per risolvere e leggere/scrivere i file di snapshot:

export interface SnapshotEnvironment {
  getVersion: () => string;
  getHeader: () => string;
  resolvePath: (filepath: string) => Promise<string>;
  resolveRawPath: (testPath: string, rawPath: string) => Promise<string>;
  saveSnapshotFile: (filepath: string, snapshot: string) => Promise<void>;
  readSnapshotFile: (filepath: string) => Promise<string | null>;
  removeSnapshotFile: (filepath: string) => Promise<void>;
}

Puoi estendere VitestSnapshotEnvironment predefinito dal punto di ingresso vitest/snapshot se hai bisogno di sovrascrivere solo una parte dell'API.

WARNING

Questa è un'opzione di basso livello e va utilizzata solo per casi avanzati in cui non si ha accesso alle API Node.js predefinite.

Se hai solo bisogno di configurare la funzionalità degli snapshot, utilizza le opzioni snapshotFormat o resolveSnapshotPath.

env

• Tipo: Partial<NodeJS.ProcessEnv>

Variabili d'ambiente disponibili tramite process.env e import.meta.env durante i test. Queste variabili non sono disponibili nel processo principale (in globalSetup, ad esempio).

expect

• Tipo: ExpectOptions

expect.requireAssertions

• Tipo: boolean
• Predefinito: false

Equivalente a chiamare expect.hasAssertions() all'inizio di ogni test. Questo assicura che nessun test passi in modo inatteso.

TIP

Questo funziona solo con l'oggetto expect di Vitest. Se usi asserzioni assert o .should, queste non verranno contate e il tuo test fallirà a causa della mancanza di asserzioni expect.

Puoi modificare il valore di questa opzione chiamando vi.setConfig({ expect: { requireAssertions: false } }). La configurazione verrà applicata a ogni successiva chiamata expect fino a quando vi.resetConfig non sarà chiamato manualmente.

expect.poll

Opzioni di configurazione globali per la funzionalità expect.poll. Queste sono le stesse opzioni che puoi fornire a expect.poll(condition, options).

expect.poll.interval

• Tipo: number
• Predefinito: 50

Intervallo di polling, in millisecondi.

expect.poll.timeout

• Tipo: number
• Predefinito: 1000

Timeout di polling, in millisecondi.

printConsoleTrace

• Tipo: boolean
• Predefinito: false

Stampa sempre le tracce della console quando viene chiamato qualsiasi metodo console. Questo è utile per le attività di debug.

attachmentsDir 3.2.0+

• Tipo: string
• Predefinito: '.vitest-attachments'

Percorso della directory per gli allegati creati da context.annotate, relativo alla radice del progetto.