Per Iniziare

Panoramica

Vitest (pronunciato "veetest") è un framework di testing di nuova generazione basato su Vite.

Per maggiori dettagli sulle motivazioni del progetto, consulta la sezione Perché Vitest.

Provare Vitest Online

Puoi provare Vitest online su StackBlitz. Esegue Vitest direttamente nel browser, offrendo un'esperienza quasi identica a una configurazione locale, senza la necessità di installare nulla sulla tua macchina.

Aggiungere Vitest al Tuo Progetto

Scopri come installare Vitest con un video tutorial

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

TIP

Vitest richiede Vite >=v5.0.0 e Node >=v18.0.0.

Si consiglia di installare vitest come dipendenza di sviluppo nel tuo package.json, utilizzando uno dei metodi elencati sopra. Tuttavia, se preferisci eseguire vitest direttamente, puoi usare npx vitest (lo strumento npx è incluso con npm e Node.js).

Lo strumento npx esegue il comando specificato. Per impostazione predefinita, npx verifica prima se il comando esiste tra i binari locali del progetto. Se non viene trovato, npx cerca nel $PATH del sistema e lo esegue se presente. Se il comando non viene trovato in nessuna delle due posizioni, npx lo installa temporaneamente prima dell'esecuzione.

Scrivere Test

Come esempio, scriveremo un semplice test che verifica l'output di una funzione che addiziona due numeri.

export function sum(a, b) {
  return a + b;
}

import { expect, test } from 'vitest';
import { sum } from './sum.js';

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

TIP

Per impostazione predefinita, i file di test devono contenere .test. o .spec. nel loro nome.

Successivamente, per eseguire il test, aggiungi la seguente sezione al tuo package.json:

{
  "scripts": {
    "test": "vitest"
  }
}

Infine, esegui npm run test, yarn test o pnpm test, a seconda del tuo gestore di pacchetti, e Vitest visualizzerà il seguente messaggio:

✓ sum.test.js (1)
  ✓ adds 1 + 2 to equal 3

Test Files  1 passed (1)
     Tests  1 passed (1)
  Start at  02:15:44
  Duration  311ms

WARNING

Se stai usando Bun come gestore di pacchetti, assicurati di usare il comando bun run test invece di bun test, altrimenti Bun eseguirà il proprio test runner.

Per saperne di più sull'utilizzo di Vitest, consulta la sezione API.

Configurare Vitest

Uno dei principali vantaggi di Vitest è la sua configurazione unificata con quella di Vite. Se presente, vitest leggerà il tuo file vite.config.ts principale per allinearsi ai plugin e alla configurazione della tua app Vite. Ad esempio, le configurazioni resolve.alias e plugins di Vite funzioneranno senza problemi. Se desideri una configurazione diversa durante il testing, puoi:

• Creare vitest.config.ts, che avrà la priorità più alta.
• Passare l'opzione --config alla CLI, ad esempio vitest --config ./path/to/vitest.config.ts.
• Usare process.env.VITEST o la proprietà mode all'interno di defineConfig (verrà impostata su test se non viene sovrascritta) per applicare condizionalmente una configurazione diversa in vite.config.ts.

Vitest supporta le stesse estensioni di file di configurazione di Vite: .js, .mjs, .cjs, .ts, .cts, .mts. Vitest non supporta l'estensione .json.

Se non usi Vite come strumento di build, puoi configurare Vitest utilizzando la proprietà test nel tuo file di configurazione:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ...
  },
});

TIP

Anche se non usi Vite direttamente, Vitest si basa pesantemente su di esso per la sua pipeline di trasformazione. Per questo motivo, puoi anche configurare qualsiasi proprietà descritta nella documentazione di Vite.

Se stai già usando Vite, aggiungi la proprietà test nella tua configurazione Vite. Dovrai anche aggiungere un riferimento ai tipi Vitest usando una direttiva a tripla barra all'inizio del file di configurazione.

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

export default defineConfig({
  test: {
    // ...
  },
});

Il <reference types="vitest" /> non funzionerà più nel prossimo aggiornamento maggiore, ma puoi iniziare a migrare a vitest/config in Vitest 2.1:

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

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

Consulta l'elenco delle opzioni di configurazione nel Riferimento Configurazione

WARNING

Se decidi di avere due file di configurazione separati per Vite e Vitest, assicurati di definire le stesse opzioni Vite nel tuo file di configurazione Vitest, poiché questo sovrascriverà le opzioni del tuo file Vite, anziché estenderle. Puoi anche usare il metodo mergeConfig importandolo da vite o vitest/config per unire la configurazione Vite con la configurazione Vitest:

vitest.config.mjs

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

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // ...
    },
  })
);

vite.config.mjs

import { defineConfig } from 'vite';
import Vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [Vue()],
});

Tuttavia, consigliamo di usare lo stesso file sia per Vite che per Vitest, invece di creare due file separati.

Supporto Progetti

Esegui diverse configurazioni di progetto all'interno dello stesso progetto con Test Projects. Puoi definire un elenco di file e cartelle per i tuoi progetti nel file vitest.config.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      // puoi usare un elenco di pattern glob per definire i tuoi progetti
      // Vitest si aspetta un elenco di file di configurazione
      // o directory contenenti un file di configurazione
      'packages/*',
      'tests/*/vitest.config.{e2e,unit}.ts',
      // puoi anche eseguire gli stessi test,
      // ma con configurazioni diverse nello stesso processo di Vitest
      {
        test: {
          name: 'happy-dom',
          root: './shared_tests',
          environment: 'happy-dom',
          setupFiles: ['./setup.happy-dom.ts'],
        },
      },
      {
        test: {
          name: 'node',
          root: './shared_tests',
          environment: 'node',
          setupFiles: ['./setup.node.ts'],
        },
      },
    ],
  },
});

Interfaccia a Riga di Comando

In un progetto in cui Vitest è installato, puoi usare il binario vitest negli script npm, o eseguirlo direttamente con npx vitest. Ecco gli script npm predefiniti in un progetto Vitest preconfigurato:

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

Per eseguire i test una volta senza monitorare le modifiche ai file, usa vitest run. Puoi anche specificare opzioni CLI aggiuntive, come --port o --https. Per un elenco completo delle opzioni CLI, esegui npx vitest --help all'interno del tuo progetto.

Scopri di più sull'Interfaccia a Riga di Comando

Installazione Automatica delle Dipendenze

Vitest ti inviterà a installare determinate dipendenze se non sono già installate. Puoi disabilitare questo comportamento definendo la variabile d'ambiente VITEST_SKIP_INSTALL_CHECKS=1.

Integrazioni IDE

Abbiamo anche fornito un'estensione ufficiale per Visual Studio Code per migliorare l'esperienza di testing con Vitest.

Installa dal VS Code Marketplace

Scopri di più sulle Integrazioni IDE

Esempi

Esempio	Sorgente	Playground
basic	GitHub	Provalo Online
fastify	GitHub	Provalo Online
in-source-test	GitHub	Provalo Online
lit	GitHub	Provalo Online
vue	GitHub	Provalo Online
marko	GitHub	Provalo Online
preact	GitHub	Provalo Online
react	GitHub	Provalo Online
solid	GitHub	Provalo Online
svelte	GitHub	Provalo Online
sveltekit	GitHub	Provalo Online
profiling	GitHub	Non Disponibile
typecheck	GitHub	Provalo Online
projects	GitHub	Provalo Online

Progetti che usano Vitest

• unocss
• unplugin-auto-import
• unplugin-vue-components
• vue
• vite
• vitesse
• vitesse-lite
• fluent-vue
• vueuse
• milkdown
• gridjs-svelte
• spring-easing
• bytemd
• faker
• million
• Vitamin
• neodrag
• svelte-multiselect
• iconify
• tdesign-vue-next
• cz-git

Utilizzo di Commit Non Rilasciati

Ogni commit sul ramo principale e ogni PR con l'etichetta cr-tracked vengono pubblicati su pkg.pr.new. Puoi installarli tramite npm i https://pkg.pr.new/vitest@{commit}.

Se vuoi testare la tua modifica localmente, puoi compilarla e collegarla autonomamente (è richiesto pnpm):

git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # puoi utilizzare il tuo gestore di pacchetti preferito per questo passaggio

Quindi vai al progetto in cui stai usando Vitest ed esegui pnpm link --global vitest (o il gestore di pacchetti che hai utilizzato per collegare vitest a livello globale).

Comunità

Se hai domande o hai bisogno di aiuto, rivolgiti alla community su Discord e GitHub Discussions.