Workspace

Progetto di esempio

GitHub - Prova Online

Vitest offre la possibilità di definire più configurazioni di progetto all'interno di un singolo processo Vitest. Questa funzionalità è particolarmente utile nelle configurazioni monorepo, ma può anche essere impiegata per eseguire test con diverse configurazioni, come resolve.alias, plugins, test.browser e altro ancora.

Definire un Workspace

Un workspace deve includere un file vitest.workspace o vitest.projects nella sua directory radice (situato nella stessa cartella del file di configurazione radice o nella directory di lavoro se non esiste). Vitest supporta le estensioni ts, js e json per questo file.

NOME

Si noti che questa funzionalità si chiama workspace, non workspaces (senza la "s" finale).

Il file di configurazione del workspace deve avere un'esportazione predefinita contenente un elenco di file o pattern glob che fanno riferimento ai progetti. Ad esempio, se si dispone di una cartella denominata packages che contiene i progetti, è possibile definire un workspace con questo file di configurazione:

vitest.workspace.ts

export default ['packages/*'];

Vitest tratterà ogni cartella in packages come un progetto separato, anche se non contiene un proprio file di configurazione. A partire da Vitest 2.1, se questo pattern glob corrisponde a un file, esso verrà considerato una configurazione Vitest anche se non include vitest nel suo nome.

WARNING

Vitest non considera il file vitest.config radice come un progetto del workspace, a meno che non sia esplicitamente specificato nella configurazione del workspace. Di conseguenza, la configurazione principale influenzerà solo le opzioni globali come reporters e coverage.

È anche possibile fare riferimento ai progetti tramite i loro file di configurazione:

vitest.workspace.ts

export default ['packages/*/vitest.config.{e2e,unit}.ts'];

Questo pattern includerà solo i progetti con un file vitest.config che contiene e2e o unit prima dell'estensione.

È inoltre possibile definire i progetti utilizzando la configurazione inline. Il file del workspace supporta entrambe le sintassi contemporaneamente.

vitest.workspace.ts

import { defineWorkspace } from 'vitest/config';

// defineWorkspace offre un'ottima esperienza di sviluppo (DX) per il suggerimento dei tipi
export default defineWorkspace([
  // corrisponde a ogni cartella e file all'interno della cartella `packages`
  'packages/*',
  {
    // aggiungi "extends" per unire due configurazioni
    extends: './vite.config.js',
    test: {
      include: ['tests/**/*.{browser}.test.{ts,js}'],
      // si raccomanda di definire un nome quando si usano configurazioni inline
      name: 'happy-dom',
      environment: 'happy-dom',
    },
  },
  {
    test: {
      include: ['tests/**/*.{node}.test.{ts,js}'],
      name: 'node',
      environment: 'node',
    },
  },
]);

WARNING

Tutti i progetti devono avere nomi univoci; in caso contrario, Vitest restituirà un errore. Se un nome non è fornito nella configurazione inline, Vitest assegnerà un numero. Per le configurazioni di progetto definite con la sintassi glob, Vitest userà per impostazione predefinita la proprietà "name" nel file package.json più vicino o, se non presente, il nome della cartella.

Se non si utilizzano configurazioni inline, è possibile creare un piccolo file JSON nella directory radice:

vitest.workspace.json

["packages/*"]

Non tutte le proprietà di configurazione sono supportate nei progetti del workspace. Per una maggiore sicurezza dei tipi, si consiglia di usare il metodo defineProject invece di defineConfig all'interno dei file di configurazione del progetto:

packages/a/vitest.config.ts

// @errors: 2769
import { defineProject } from 'vitest/config';

export default defineProject({
  test: {
    environment: 'jsdom',
    // "reporters" non è supportato in una configurazione di progetto,
    // quindi mostrerà un errore
    reporters: ['json'],
  },
});

Esecuzione dei test

Per eseguire i test all'interno del workspace, definire uno script nel file package.json radice:

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

Ora i test possono essere eseguiti utilizzando il gestore di pacchetti:

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

Se è necessario eseguire i test solo all'interno di un singolo progetto, utilizzare l'opzione CLI --project:

npm

npm run test --project e2e

yarn

yarn test --project e2e

pnpm

pnpm run test --project e2e

bun

bun test --project e2e

TIP

L'opzione CLI --project può essere usata più volte per filtrare diversi progetti:

npm

npm run test --project e2e --project unit

yarn

yarn test --project e2e --project unit

pnpm

pnpm run test --project e2e --project unit

bun

bun test --project e2e --project unit

Configurazione

Le opzioni di configurazione non vengono ereditate dal file di configurazione a livello radice. È possibile creare un file di configurazione condiviso e unirlo manualmente con la configurazione del progetto:

packages/a/vitest.config.ts

import { defineProject, mergeConfig } from 'vitest/config';
import configShared from '../vitest.shared.js';

export default mergeConfig(
  configShared,
  defineProject({
    test: {
      environment: 'jsdom',
    },
  })
);

A livello di defineWorkspace, è possibile usare l'opzione extends per ereditare dalla configurazione radice. Tutte le opzioni saranno unite.

vitest.workspace.ts

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  {
    extends: './vitest.config.ts',
    test: {
      name: 'unit',
      include: ['**/*.unit.test.ts'],
    },
  },
  {
    extends: './vitest.config.ts',
    test: {
      name: 'integration',
      include: ['**/*.integration.test.ts'],
    },
  },
]);

Alcune delle opzioni di configurazione non sono consentite in una configurazione di progetto. Nello specifico:

• coverage: la copertura si applica all'intero workspace
• reporters: sono supportati solo i reporter a livello radice
• resolveSnapshotPath: è valido solo il resolver a livello radice
• tutte le altre opzioni che non influenzano i test runner

TIP

Tutte le opzioni di configurazione non supportate all'interno di una configurazione di progetto sono indicate da un segno * nella guida "Config".