Workspace

Beispielprojekt

GitHub - Online ausprobieren

Vitest bietet die Möglichkeit, mehrere Projektkonfigurationen innerhalb eines einzigen Vitest-Prozesses zu definieren. Diese Funktion ist besonders nützlich für Monorepo-Setups, kann aber auch verwendet werden, um Tests mit verschiedenen Konfigurationen auszuführen, wie z. B. resolve.alias, plugins oder test.browser und weitere.

Einen Workspace definieren

Ein Workspace muss eine vitest.workspace- oder vitest.projects-Datei in seinem Stammverzeichnis enthalten (im selben Ordner wie Ihre Hauptkonfigurationsdatei oder, falls diese nicht existiert, in Ihrem Arbeitsverzeichnis). Vitest unterstützt ts, js und json als Dateierweiterungen für diese Datei.

NAMENSGEBUNG

Bitte beachten Sie, dass diese Funktion workspace genannt wird, nicht workspaces (ohne "s" am Ende).

Die Workspace-Konfigurationsdatei muss einen Standardexport mit einer Liste von Dateien oder Glob-Mustern enthalten, die auf Ihre Projekte verweisen. Wenn Sie beispielsweise einen Ordner namens packages haben, der Ihre Projekte enthält, können Sie einen Workspace mit dieser Konfigurationsdatei definieren:

vitest.workspace.ts

export default ['packages/*'];

Vitest behandelt jeden Ordner in packages als separates Projekt, auch wenn dieser keine Konfigurationsdatei enthält. Seit Vitest 2.1 wird jede Datei, die diesem Glob-Muster entspricht, als Vitest-Konfiguration betrachtet, auch wenn sie kein vitest im Namen hat.

WARNING

Vitest behandelt die Stammdatei vitest.config nicht als Workspace-Projekt, es sei denn, sie ist explizit in der Workspace-Konfiguration angegeben. Folglich beeinflusst die Stammkonfiguration nur globale Optionen wie reporters und coverage.

Sie können Projekte auch mit ihren Konfigurationsdateien referenzieren:

vitest.workspace.ts

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

Dieses Muster schließt nur Projekte mit einer vitest.config-Datei ein, die e2e oder unit vor der Dateierweiterung enthält.

Sie können Projekte auch mithilfe von Inline-Konfiguration definieren. Die Workspace-Datei unterstützt beide Syntaxen gleichzeitig.

vitest.workspace.ts

import { defineWorkspace } from 'vitest/config';

// defineWorkspace bietet eine gute Entwicklererfahrung durch Typ-Hinweise
export default defineWorkspace([
  // entspricht jedem Ordner und jeder Datei im Ordner `packages`
  'packages/*',
  {
    // fügt "extends" hinzu, um zwei Konfigurationen zu vereinen
    extends: './vite.config.js',
    test: {
      include: ['tests/**/*.{browser}.test.{ts,js}'],
      // Es wird empfohlen, bei der Verwendung von Inline-Konfigurationen einen Namen zu definieren.
      name: 'happy-dom',
      environment: 'happy-dom',
    },
  },
  {
    test: {
      include: ['tests/**/*.{node}.test.{ts,js}'],
      name: 'node',
      environment: 'node',
    },
  },
]);

WARNING

Alle Projekte müssen eindeutige Namen haben; andernfalls wirft Vitest einen Fehler. Wenn in der Inline-Konfiguration kein Name angegeben wird, weist Vitest eine Nummer zu. Für Projektkonfigurationen, die mit Glob-Syntax definiert sind, verwendet Vitest standardmäßig die Eigenschaft "name" in der nächstgelegenen package.json-Datei oder, falls keine vorhanden ist, den Ordnernamen.

Wenn Sie keine Inline-Konfigurationen verwenden, können Sie eine kleine JSON-Datei in Ihrem Stammverzeichnis erstellen:

vitest.workspace.json

["packages/*"]

Workspace-Projekte unterstützen nicht alle Konfigurationseigenschaften. Für eine bessere Typsicherheit verwenden Sie die Methode defineProject anstelle von defineConfig in Projektkonfigurationsdateien:

packages/a/vitest.config.ts

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

export default defineProject({
  test: {
    environment: 'jsdom',
    // Die Option "reporters" wird in einer Projektkonfiguration nicht unterstützt,
    // daher wird ein Fehler angezeigt.
    reporters: ['json'],
  },
});

Tests ausführen

Um Tests innerhalb des Workspaces auszuführen, definieren Sie ein Skript in Ihrer Haupt-package.json:

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

Jetzt können Tests mit Ihrem Paketmanager ausgeführt werden:

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

Wenn Sie Tests nur innerhalb eines einzelnen Projekts ausführen möchten, verwenden Sie die CLI-Option --project:

npm

npm run test --project e2e

yarn

yarn test --project e2e

pnpm

pnpm run test --project e2e

bun

bun test --project e2e

TIP

Die CLI-Option --project kann mehrfach verwendet werden, um mehrere Projekte herauszufiltern:

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

Konfiguration

Keine der Konfigurationsoptionen wird von der Konfigurationsdatei auf Root-Ebene geerbt. Sie können eine gemeinsame Konfigurationsdatei erstellen und diese selbst mit der Projektkonfiguration zusammenführen:

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',
    },
  })
);

Auf der defineWorkspace-Ebene können Sie die Option extends verwenden, um von Ihrer Root-Level-Konfiguration zu erben. Alle Optionen werden dabei zusammengeführt.

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'],
    },
  },
]);

Einige der Konfigurationsoptionen sind in einer Projektkonfiguration nicht zulässig. Die bemerkenswertesten sind:

• coverage: Die Codeabdeckung erfolgt für den gesamten Workspace
• reporters: Es werden nur Reporter auf Root-Ebene unterstützt
• resolveSnapshotPath: Es wird nur der Resolver auf Root-Ebene berücksichtigt
• alle anderen Optionen, die sich nicht auf Test-Runner auswirken.

TIP

Alle Konfigurationsoptionen, die innerhalb einer Projektkonfiguration nicht unterstützt werden, sind im Leitfaden "Config" mit dem Zeichen * gekennzeichnet.