Vitest konfigurieren

Wenn Sie Vite verwenden und eine vite.config-Datei besitzen, liest Vitest diese, um die Plugins und das Setup Ihrer Vite-Anwendung zu übernehmen. Sollten Sie eine abweichende Konfiguration für Tests benötigen oder Ihre Hauptanwendung nicht explizit auf Vite angewiesen sein, stehen Ihnen folgende Optionen zur Verfügung:

• Erstellen Sie eine vitest.config.ts-Datei. Diese hat eine höhere Priorität und überschreibt die Konfiguration aus vite.config.ts. (Vitest unterstützt alle gängigen JS- und TS-Erweiterungen, jedoch keine JSON-Dateien.) Dies bedeutet, dass alle Optionen in Ihrer vite.config ignoriert werden.
• Übergeben Sie die Option --config an die CLI, z.B. vitest --config ./path/to/vitest.config.ts.
• Nutzen Sie process.env.VITEST oder die mode-Eigenschaft in defineConfig (wird auf test/benchmark gesetzt, sofern nicht mit --mode überschrieben), um bedingt eine andere Konfiguration in vite.config.ts anzuwenden.

Um Vitest selbst zu konfigurieren, fügen Sie die test-Eigenschaft zu Ihrer Vite-Konfiguration hinzu. Wenn Sie defineConfig direkt von Vite importieren, müssen Sie zusätzlich einen Verweis auf die Vitest-Typen am Anfang Ihrer Konfigurationsdatei mittels eines Triple-Slash-Befehls hinzufügen.

Konfigurationsbeispiele öffnen

Bei Verwendung von defineConfig aus vite gehen Sie wie folgt vor:

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

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

<reference types="vitest" /> wird in Vitest 4 nicht mehr funktionieren. Sie können jedoch bereits jetzt mit der Migration zu vitest/config beginnen:

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

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

Bei Verwendung von defineConfig aus vitest/config gehen Sie wie folgt vor:

import { defineConfig } from 'vitest/config';

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

Sie können die Standardoptionen von Vitest abrufen und bei Bedarf erweitern:

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

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

Wenn Sie eine separate vitest.config.js verwenden, können Sie bei Bedarf auch die Vite-Optionen aus einer anderen Konfigurationsdatei erweitern:

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

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

Wenn Ihre Vite-Konfiguration als Funktion definiert ist, können Sie die Konfiguration wie folgt definieren:

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

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

WARNING

Alle auf dieser Seite aufgeführten Optionen befinden sich innerhalb einer test-Eigenschaft in der Vite-Konfiguration:

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

Da Vitest die Vite-Konfiguration nutzt, können Sie auch jede Konfigurationsoption von Vite verwenden. Zum Beispiel define zum Definieren globaler Variablen oder resolve.alias zum Definieren von Aliassen – diese Optionen sollten auf der Hauptebene definiert werden, nicht innerhalb einer test-Eigenschaft.

Konfigurationsoptionen, die nicht innerhalb einer Projektkonfiguration unterstützt werden, sind mit einem *-Zeichen gekennzeichnet. Dies bedeutet, sie können nur in der Vitest-Root-Konfiguration festgelegt werden.

include

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

Eine Liste von Glob-Mustern, die Ihre Testdateien erfassen.

HINWEIS

Bei Verwendung der Code-Abdeckung fügt Vitest automatisch die include-Muster für Testdateien zu den Standard-exclude-Mustern der Code-Abdeckung hinzu. Siehe coverage.exclude.

exclude

• Typ: string[]
• Standard: ['**/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"

Eine Liste von Glob-Mustern, die von den Testdateien ausgeschlossen werden sollen.

WARNING

Diese Option beeinflusst nicht die Code-Abdeckung. Wenn Sie bestimmte Dateien aus dem Code-Abdeckungsbericht entfernen müssen, verwenden Sie coverage.exclude.

Dies ist die einzige Option, die Ihre Konfiguration nicht überschreibt, wenn Sie sie über ein CLI-Flag bereitstellen. Alle über das --exclude-Flag hinzugefügten Glob-Muster werden zur exclude-Liste der Konfiguration hinzugefügt.

includeSource

• Typ: string[]
• Standard: []

Glob-Muster zum Einschließen von In-Source-Testdateien.

Wenn definiert, führt Vitest alle übereinstimmenden Dateien mit import.meta.vitest darin aus.

name

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

Vergeben Sie dem Testprojekt oder dem Vitest-Prozess einen benutzerdefinierten Namen. Der Name wird in der CLI und UI sichtbar sein und in der Node.js API über project.name zugänglich sein.

Die von CLI und UI verwendete Farbe kann durch Bereitstellung eines Objekts mit einer color-Eigenschaft geändert werden.

server

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

Vite-Node Server-Optionen.

server.sourcemap

• Typ: 'inline' | boolean
• Standard: 'inline'

Inline-Source-Map in Module einfügen.

server.debug

• Typ: { dumpModules?, loadDumppedModules? }

Vite-Node Debugger-Optionen.

server.debug.dumpModules

• Typ: boolean | string

Das transformierte Modul im Dateisystem ablegen. Wenn ein String übergeben wird, wird es im angegebenen Pfad abgelegt.

server.debug.loadDumppedModules

• Typ: boolean

Abgelegte Module aus dem Dateisystem lesen, falls vorhanden. Nützlich zum Debuggen durch Modifizieren des Dump-Ergebnisses aus dem Dateisystem.

server.deps

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

Behandlung der Abhängigkeitsauflösung.

server.deps.external

• Typ: (string | RegExp)[]
• Standard: [/\/node_modules\//]

Externalisieren bedeutet, dass Vite die Verarbeitung des Pakets an das native Node umgeht. Externalisierte Abhängigkeiten werden von Vites Transformern und Resolvern nicht verarbeitet, daher unterstützen sie kein HMR beim Neuladen. Standardmäßig sind alle Pakete innerhalb von node_modules externalisiert.

Diese Optionen unterstützen Paketnamen, wie sie in node_modules vorliegen oder in deps.moduleDirectories angegeben sind. Zum Beispiel sollte das Paket @company/some-name, das sich in packages/some-name befindet, als some-name angegeben werden, und packages sollte in deps.moduleDirectories enthalten sein. Vitest prüft grundsätzlich immer den Dateipfad, nicht den tatsächlichen Paketnamen.

Wenn ein regulärer Ausdruck verwendet wird, wendet Vitest ihn auf den Dateipfad an, nicht auf den Paketnamen.

server.deps.inline

• Typ: (string | RegExp)[] | true
• Standard: []

Vite verarbeitet direkt eingebundene Module. Dies kann hilfreich sein, um Pakete zu verwalten, die .js im ESM-Format liefern (das Node nicht verarbeiten kann).

Wenn true, wird jede Abhängigkeit direkt eingebunden. Alle Abhängigkeiten, die in ssr.noExternal angegeben sind, werden standardmäßig direkt eingebunden.

server.deps.fallbackCJS

• Typ boolean
• Standard: false

Wenn eine Abhängigkeit ein gültiges ESM-Paket ist, versucht Vitest, die CJS-Version basierend auf dem Pfad zu ermitteln. Dies kann hilfreich sein, wenn eine Abhängigkeit eine fehlerhafte ESM-Datei aufweist.

Dies könnte möglicherweise zu einer Fehlausrichtung führen, wenn ein Paket unterschiedliche Logik im ESM- und CJS-Modus aufweist.

server.deps.cacheDir

• Typ string
• Standard: 'node_modules/.vite'

Verzeichnis zum Speichern von Cache-Dateien.

deps

• Typ: { optimizer?, ... }

Behandlung der Abhängigkeitsauflösung.

deps.optimizer

• Typ: { ssr?, web? }
• Siehe auch: Dep Optimization Options

Abhängigkeitsoptimierung aktivieren. Wenn Sie viele Tests haben, kann dies die Leistung verbessern.

Wenn Vitest die in include aufgeführte externe Bibliothek findet, wird sie mit esbuild in eine einzige Datei gebündelt und als ganzes Modul importiert. Dies ist aus mehreren Gründen vorteilhaft:

• Das Importieren von Paketen mit vielen Importen ist aufwendig. Durch das Bündeln in eine Datei können wir viel Zeit sparen.
• Das Importieren von UI-Bibliotheken ist aufwendig, da sie nicht für die Ausführung in Node.js gedacht sind.
• Ihre alias-Konfiguration wird jetzt innerhalb gebündelter Pakete berücksichtigt.
• Code in Ihren Tests verhält sich ähnlicher wie im Browser.

Beachten Sie, dass nur Pakete in der Option deps.optimizer?.[mode].include gebündelt werden (einige Plugins (z.B. Svelte) füllen dies automatisch). Sie können mehr über die verfügbaren Optionen in der Vite-Dokumentation lesen (Vitest unterstützt die Optionen disable und noDiscovery nicht). Standardmäßig verwendet Vitest optimizer.web für jsdom- und happy-dom-Umgebungen und optimizer.ssr für node- und edge-Umgebungen, dies ist jedoch über transformMode konfigurierbar.

Diese Optionen erben auch Ihre optimizeDeps-Konfiguration (für Web erweitert Vitest optimizeDeps, für SSR - ssr.optimizeDeps). Wenn Sie die Option include/exclude in deps.optimizer neu definieren, wird dies Ihre optimizeDeps beim Ausführen von Tests erweitern. Vitest entfernt automatisch die gleichen Optionen aus include, wenn sie in exclude aufgeführt sind.

TIP

Sie können Ihren node_modules-Code nicht direkt zum Debuggen bearbeiten, da sich der Code tatsächlich in Ihrem cacheDir oder test.cache.dir-Verzeichnis befindet. Wenn Sie mit console.log-Anweisungen debuggen möchten, bearbeiten Sie den Code direkt oder erzwingen Sie ein erneutes Bündeln mit der Option deps.optimizer?.[mode].force.

deps.optimizer.{mode}.enabled

• Typ: boolean
• Standard: false

Abhängigkeitsoptimierung aktivieren.

deps.web

• Typ: { transformAssets?, ... }

Optionen, die auf externe Dateien angewendet werden, wenn der Transformationsmodus auf web gesetzt ist. Standardmäßig verwenden jsdom und happy-dom den web-Modus, während node- und edge-Umgebungen den ssr-Transformationsmodus verwenden, sodass diese Optionen keine Auswirkungen auf Dateien in diesen Umgebungen haben.

Normalerweise werden Dateien innerhalb von node_modules externalisiert, aber diese Optionen beeinflussen auch Dateien in server.deps.external.

deps.web.transformAssets

• Typ: boolean
• Standard: true

Soll Vitest Asset-Dateien (.png, .svg, .jpg, etc.) verarbeiten und sie wie Vite im Browser auflösen?

Dieses Modul exportiert standardmäßig den Pfad zum Asset, wenn keine Abfrage angegeben ist.

WARNING

Derzeit funktioniert diese Option nur mit vmThreads und vmForks Pools.

deps.web.transformCss

• Typ: boolean
• Standard: true

Soll Vitest CSS-Dateien (.css, .scss, .sass, etc.) verarbeiten und sie wie Vite im Browser auflösen?

Wenn CSS-Dateien mit den css-Optionen deaktiviert sind, unterdrückt diese Option lediglich ERR_UNKNOWN_FILE_EXTENSION-Fehler.

WARNING

Derzeit funktioniert diese Option nur mit vmThreads und vmForks Pools.

deps.web.transformGlobPattern

• Typ: RegExp | RegExp[]
• Standard: []

Regulärer Ausdruck zum Erfassen externer Dateien, die transformiert werden sollen.

Standardmäßig werden Dateien innerhalb von node_modules externalisiert und nicht transformiert, es sei denn, es handelt sich um CSS oder ein Asset, und die entsprechende Option ist nicht deaktiviert.

WARNING

Derzeit funktioniert diese Option nur mit vmThreads und vmForks Pools.

deps.interopDefault

• Typ: boolean
• Standard: true

Behandelt den Standardexport eines CJS-Moduls als benannte Exporte. Einige Abhängigkeiten bündeln nur CJS-Module und verwenden keine benannten Exporte, die Node.js bei einem Import mit der import-Syntax (anstelle von require) statisch analysieren könnte. Beim Importieren solcher Abhängigkeiten in einer Node-Umgebung mit benannten Exporten wird dieser Fehler angezeigt:

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 führt keine statische Analyse durch und kann Fehler erst während der Codeausführung erkennen, daher werden Sie diesen Fehler höchstwahrscheinlich beim Ausführen von Tests sehen, wenn diese Funktion deaktiviert ist:

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

Standardmäßig geht Vitest davon aus, dass Sie einen Bundler verwenden, um dies zu umgehen, und führt nicht zu einem Fehler. Sie können dieses Verhalten jedoch manuell deaktivieren, wenn Ihr Code nicht verarbeitet wird.

deps.moduleDirectories

• Typ: string[]
• Standard: ['node_modules']

Eine Liste von Verzeichnissen, die als Modulverzeichnisse gelten sollen. Diese Konfigurationsoption beeinflusst das Verhalten von vi.mock: Wenn keine Factory bereitgestellt wird und der Pfad des zu mockenden Moduls mit einem der moduleDirectories-Werte übereinstimmt, versucht Vitest, den Mock zu finden, indem es nach einem __mocks__-Ordner im Stammverzeichnis des Projekts sucht.

Diese Option beeinflusst auch, ob eine Datei beim Externalisieren von Abhängigkeiten als Modul behandelt werden soll. Standardmäßig importiert Vitest externe Module mit nativem Node.js und umgeht dabei den Vite-Transformationsschritt.

Das Setzen dieser Option überschreibt den Standardwert. Wenn Sie node_modules weiterhin nach Paketen durchsuchen möchten, fügen Sie es zusammen mit allen anderen Optionen hinzu:

import { defineConfig } from 'vitest/config';

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

runner

• Typ: VitestRunnerConstructor
• Standard: node, beim Ausführen von Tests, oder benchmark, beim Ausführen von Benchmarks

Pfad zu einem benutzerdefinierten Test-Runner. Dies ist eine erweiterte Funktion und sollte mit benutzerdefinierten Runnern für Bibliotheken verwendet werden. Mehr dazu erfahren Sie in der Dokumentation.

benchmark

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

Optionen, die beim Ausführen von vitest bench verwendet werden.

benchmark.include

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

Glob-Muster zum Einschließen von Benchmark-Testdateien.

benchmark.exclude

• Typ: string[]
• Standard: ['node_modules', 'dist', '.idea', '.git', '.cache']

Glob-Muster zum Ausschließen von Benchmark-Testdateien.

benchmark.includeSource

• Typ: string[]
• Standard: []

Glob-Muster für In-Source-Benchmark-Testdateien. Diese Option ähnelt includeSource.

Wenn definiert, führt Vitest alle übereinstimmenden Dateien mit import.meta.vitest darin aus.

benchmark.reporters

• Typ: Arrayable<BenchmarkBuiltinReporters | Reporter>
• Standard: 'default'

Benutzerdefinierter Reporter für die Testergebnisse. Kann einen oder mehrere integrierte Berichtsformate, Reporterinstanzen und/oder Pfade zu benutzerdefinierten Reportern enthalten.

benchmark.outputFile

Veraltet zugunsten von benchmark.outputJson.

benchmark.outputJson

• Typ: string | undefined
• Standard: undefined

Ein Dateipfad, um das Benchmark-Ergebnis zu speichern, das später für die Option --compare verwendet werden kann.

Zum Beispiel:

# Ergebnis des Hauptzweigs speichern
git checkout main
vitest bench --outputJson main.json

# Zweig wechseln und mit Hauptzweig vergleichen
git checkout feature
vitest bench --compare main.json

benchmark.compare

• Typ: string | undefined
• Standard: undefined

Ein Dateipfad zu einem früheren Benchmark-Ergebnis, mit dem die aktuellen Läufe verglichen werden sollen.

alias

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

Definieren Sie benutzerdefinierte Aliase für die Testausführung. Sie werden mit Aliassen aus resolve.alias zusammengeführt.

WARNING

Vitest verwendet Vite SSR-Primitive, um Tests auszuführen, was bestimmte Fallstricke hat.

1. Aliase betreffen nur Module, die direkt mit einem import-Schlüsselwort von einem direkt eingebundenen-Modul importiert werden (der gesamte Quellcode ist standardmäßig direkt eingebunden).
2. Vitest unterstützt keine Aliase für require-Aufrufe.
3. Wenn Sie eine externe Abhängigkeit aliasieren (z.B. react -> preact), sollten Sie möglicherweise stattdessen die tatsächlichen node_modules-Pakete aliasieren, damit dies auch für externalisierte Abhängigkeiten funktioniert. Sowohl Yarn als auch pnpm unterstützen Aliasing über das Präfix npm:.

globals

• Typ: boolean
• Standard: false
• CLI: --globals, --globals=false

Standardmäßig stellt Vitest keine globalen APIs zur Verfügung, um die Explizitheit zu fördern. Wenn Sie die APIs global wie Jest verwenden möchten, können Sie die Option --globals über die CLI übergeben oder globals: true in der Konfiguration hinzufügen.

import { defineConfig } from 'vitest/config';

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

Um TypeScript mit den globalen APIs zu verwenden, fügen Sie vitest/globals zum Feld types in Ihrer tsconfig.json hinzu:

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

Wenn Sie Ihre typeRoots neu definiert haben, um weitere Typen in Ihre Kompilierung aufzunehmen, müssen Sie die node_modules erneut hinzufügen, damit vitest/globals gefunden werden kann.

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

Wenn Sie bereits unplugin-auto-import in Ihrem Projekt verwenden, können Sie es auch direkt für den automatischen Import dieser APIs nutzen.

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

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // TypeScript-Deklaration generieren
    }),
  ],
});

environment

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

Die Umgebung, die zum Testen verwendet wird. Die Standardumgebung in Vitest ist eine Node.js-Umgebung. Wenn Sie eine Webanwendung entwickeln, können Sie stattdessen eine browserähnliche Umgebung über jsdom oder happy-dom verwenden.

Wenn Sie Edge-Funktionen entwickeln, können Sie die edge-runtime-Umgebung nutzen.

TIP

Sie können auch den Browser-Modus verwenden, um Integrations- oder Unit-Tests im Browser ohne Mocking der Umgebung auszuführen.

Durch Hinzufügen eines @vitest-environment-Docblocks oder -Kommentars am Anfang der Datei können Sie eine andere Umgebung für alle Tests in dieser Datei festlegen:

Docblock-Stil:

/**
 * @vitest-environment jsdom
 */

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

Kommentar-Stil:

// @vitest-environment happy-dom

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

Zur Kompatibilität mit Jest gibt es auch ein @jest-environment:

/**
 * @jest-environment jsdom
 */

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

Wenn Sie Vitest mit dem Flag --isolate=false ausführen, werden Ihre Tests in dieser Reihenfolge ausgeführt: node, jsdom, happy-dom, edge-runtime, gefolgt von benutzerdefinierten Umgebungen. Das bedeutet, dass Tests mit derselben Umgebung gruppiert, aber dennoch sequenziell ausgeführt werden.

Ab Version 0.23.0 können Sie auch eine benutzerdefinierte Umgebung definieren. Wenn eine benutzerdefinierte Umgebung verwendet wird, versucht Vitest, das Paket vitest-environment-${name} zu laden. Dieses Paket sollte ein Objekt exportieren, das der Form von Environment entspricht:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // benutzerdefiniertes Setup
    return {
      teardown() {
        // wird aufgerufen, nachdem alle Tests mit dieser Umgebung ausgeführt wurden
      },
    };
  },
};

Vitest stellt auch builtinEnvironments über den Eintrag vitest/environments bereit, falls Sie diese nur erweitern möchten. Mehr über das Erweitern von Umgebungen erfahren Sie in unserem Leitfaden.

TIP

Die jsdom-Umgebung macht die globale Variable jsdom verfügbar, die der aktuellen JSDOM-Instanz entspricht. Wenn Sie möchten, dass TypeScript dies erkennt, können Sie vitest/jsdom zu Ihrer tsconfig.json hinzufügen, wenn Sie diese Umgebung verwenden:

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

environmentOptions

• Typ: Record<'jsdom' | string, unknown>
• Standard: {}

Diese Optionen werden an die setup-Methode der aktuellen environment übergeben. Standardmäßig können Sie nur JSDOM-Optionen konfigurieren, sofern Sie es als Testumgebung verwenden.

environmentMatchGlobs

• Typ: [string, EnvironmentName][]
• Standard: []

VERALTET

Diese API wurde in Vitest 3 veraltet. Verwenden Sie stattdessen Projekte, um verschiedene Konfigurationen zu definieren.

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

Umgebung automatisch basierend auf Globs festlegen. Die erste Übereinstimmung findet Anwendung.

Zum Beispiel:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // alle Tests in tests/dom werden mit jsdom ausgeführt
      ['tests/dom/**', 'jsdom'],
      // alle Tests in tests/ mit .edge.test.ts werden mit edge-runtime ausgeführt
      ['**/*.edge.test.ts', 'edge-runtime'],
      // ...
    ],
  },
});

poolMatchGlobs

• Typ: [string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]
• Standard: []

VERALTET

Diese API wurde in Vitest 3 veraltet. Verwenden Sie stattdessen Projekte, um verschiedene Konfigurationen zu definieren:

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

Legt automatisch den Pool fest, in dem Tests ausgeführt werden, basierend auf Globs. Die erste Übereinstimmung wird verwendet.

Zum Beispiel:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolMatchGlobs: [
      // alle Tests im Verzeichnis "worker-specific" werden in einem Worker ausgeführt, so als ob Sie `--pool=threads` dafür aktiviert hätten,
      ['**/tests/worker-specific/**', 'threads'],
      // alle Tests im Verzeichnis "browser" in einem tatsächlichen Browser ausführen
      ['**/tests/browser/**', 'browser'],
      // alle anderen Tests werden basierend auf den Optionen "browser.enabled" und "threads" ausgeführt, sofern Sie keine anderen Globs angegeben haben
      // ...
    ],
  },
});

update*

• Typ: boolean
• Standard: false
• CLI: -u, --update, --update=false

Die Snapshot-Dateien aktualisieren. Dies aktualisiert alle geänderten Snapshots und löscht überflüssige.

watch*

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

Den Watch-Modus aktivieren.

In interaktiven Umgebungen ist dies der Standard, es sei denn, --run wird explizit festgelegt.

In CI oder bei Ausführung über eine nicht-interaktive Shell ist der "Watch"-Modus nicht der Standard, kann aber explizit mit diesem Flag aktiviert werden.

watchTriggerPatterns 3.2.0+ *

• Typ: WatcherTriggerPattern[]

Vitest führt Tests basierend auf dem Modulgraphen erneut aus, der durch statische und dynamische import-Anweisungen erstellt wird. Wenn Sie jedoch aus dem Dateisystem lesen oder Daten von einem Proxy abrufen, kann Vitest diese Abhängigkeiten nicht erkennen.

Um diese Tests korrekt erneut auszuführen, können Sie ein Regex-Muster und eine Funktion definieren, die eine Liste der auszuführenden Testdateien zurückgibt.

import { defineConfig } from 'vitest/config';

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

WARNING

Zurückgegebene Dateien sollten entweder absolut oder relativ zum Root-Verzeichnis sein. Beachten Sie, dass dies eine globale Option ist und nicht innerhalb von Projekt-Konfigurationen verwendet werden kann.

root

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

Projekt-Root

dir

• Typ: string
• CLI: --dir=<path>
• Standard: wie root

Basisverzeichnis, in dem nach Testdateien gesucht wird. Sie können diese Option angeben, um das Auffinden von Tests zu beschleunigen, wenn Ihr Root das gesamte Projekt abdeckt.

reporters*

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

Benutzerdefinierte Reporter für die Testergebnisse. Reporter können eine Reporter-Instanz, ein String zur Auswahl integrierter Reporter oder ein Pfad zu einer benutzerdefinierten Implementierung sein (z.B. './path/to/reporter.ts', '@scope/reporter').

outputFile*

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

Schreibt Testergebnisse in eine Datei, wenn die Option --reporter=json, --reporter=html oder --reporter=junit ebenfalls verwendet wird. Durch die Bereitstellung eines Objekts anstelle eines Strings können Sie individuelle Ausgaben definieren, wenn Sie mehrere Reporter verwenden.

pool*

• Typ: 'threads' | 'forks' | 'vmThreads' | 'vmForks'
• Standard: 'forks'
• CLI: --pool=threads

Pool, der für die Testausführung verwendet wird.

threads*

Aktiviert Multi-Threading mit tinypool (einem leichtgewichtigen Fork von Piscina). Bei Verwendung von Threads ist es nicht möglich, prozessbezogene APIs wie process.chdir() zu verwenden. Einige in nativen Sprachen geschriebene Bibliotheken, wie Prisma, bcrypt und canvas, haben Probleme beim Ausführen in mehreren Threads und verursachen Segmentierungsfehler. In diesen Fällen ist es ratsam, stattdessen den forks-Pool zu verwenden.

forks*

Ähnlich wie der threads-Pool, verwendet jedoch child_process anstelle von worker_threads über tinypool. Die Kommunikation zwischen Tests und dem Hauptprozess ist nicht so schnell wie mit dem threads-Pool. Prozessbezogene APIs wie process.chdir() sind im forks-Pool nutzbar.

vmThreads*

Führt Tests unter Verwendung des VM-Kontexts (innerhalb einer Sandbox-Umgebung) in einem threads-Pool aus.

Dies führt zu schnelleren Tests, aber das VM-Modul ist instabil, wenn ESM-Code ausgeführt wird. Ihre Tests werden Speicherlecks verursachen – um dies zu vermeiden, sollten Sie den Wert von poolOptions.vmThreads.memoryLimit manuell anpassen.

WARNING

Das Ausführen von Code in einer Sandbox hat einige Vorteile (schnellere Tests), aber auch eine Reihe von Nachteilen.

• Die globalen Variablen innerhalb nativer Module (z.B. fs, path usw.) unterscheiden sich von den globalen Variablen, die in Ihrer Testumgebung vorhanden sind. Infolgedessen verweist jeder Fehler, der von diesen nativen Modulen ausgelöst wird, auf einen anderen Fehlerkonstruktor als den, der in Ihrem Code verwendet wird:

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

• Das Importieren von ES-Modulen führt zu einer unbegrenzten Zwischenspeicherung, was zu Speicherlecks führt, wenn Sie viele Kontexte (Testdateien) haben. Es gibt keine API in Node.js zum Löschen dieses Caches.
• Der Zugriff auf globale Variablen ist in einer Sandbox-Umgebung langsamer.

Bitte seien Sie sich dieser Probleme bewusst, wenn Sie diese Option verwenden. Das Vitest-Team kann keines dieser Probleme von unserer Seite aus beheben.

vmForks*

Ähnlich wie der vmThreads-Pool, verwendet jedoch child_process anstelle von worker_threads über tinypool. Die Kommunikation zwischen Tests und dem Hauptprozess ist nicht so schnell wie mit dem vmThreads-Pool. Prozessbezogene APIs wie process.chdir() sind im vmForks-Pool nutzbar. Bitte beachten Sie, dass dieser Pool die gleichen Fallstricke wie der vmThreads-Pool aufweist.

poolOptions*

• Typ: Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>
• Standard: {}

poolOptions.threads

Optionen für den threads-Pool.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        // Threads-bezogene Optionen hier
      },
    },
  },
});

poolOptions.threads.maxThreads*

• Typ: number | string
• Standard: verfügbare CPUs

Maximale Anzahl oder prozentualer Anteil der Threads. Sie können auch die Umgebungsvariable VITEST_MAX_THREADS nutzen.

poolOptions.threads.minThreads*

• Typ: number | string
• Standard: verfügbare CPUs

Minimale Anzahl oder prozentualer Anteil der Threads. Sie können auch die Umgebungsvariable VITEST_MIN_THREADS nutzen.

poolOptions.threads.singleThread

• Typ: boolean
• Standard: false

Führt alle Tests mit derselben Umgebung innerhalb eines einzigen Worker-Threads aus. Dies deaktiviert die integrierte Modulisolierung (Ihr Quellcode oder direkt eingebundener Code wird weiterhin für jeden Test neu evaluiert), kann aber die Testleistung verbessern.

WARNING

Obwohl diese Option Tests dazu zwingt, nacheinander ausgeführt zu werden, unterscheidet sich diese Option von Jests --runInBand. Vitest verwendet Worker nicht nur zum parallelen Ausführen von Tests, sondern auch um Isolation zu gewährleisten. Durch Deaktivieren dieser Option werden Ihre Tests sequenziell ausgeführt, aber im selben globalen Kontext, sodass Sie die Isolation selbst sicherstellen müssen.

Dies kann zu allen möglichen Problemen führen, wenn Sie sich auf den globalen Zustand verlassen (Frontend-Frameworks tun dies normalerweise) oder Ihr Code darauf angewiesen ist, dass die Umgebung für jeden Test separat definiert wird. Kann aber die Tests erheblich beschleunigen (bis zu 3-mal schneller), insbesondere solche, die nicht unbedingt auf den globalen Zustand angewiesen sind oder dies leicht umgehen können.

poolOptions.threads.useAtomics*

• Typ: boolean
• Standard: false

Verwenden Sie Atomics, um Threads zu synchronisieren.

Dies kann in einigen Fällen die Leistung verbessern, könnte aber in älteren Node-Versionen Segmentierungsfehler verursachen.

poolOptions.threads.isolate

• Type: boolean
• Default: true

Isoliert die Umgebung für jede Testdatei.

poolOptions.threads.execArgv*

• Typ: string[]
• Standard: []

Zusätzliche Argumente an node in den Worker-Threads übergeben. Weitere Informationen finden Sie unter Command-line API | Node.js.

WARNING

Seien Sie vorsichtig bei der Verwendung, da einige Optionen den Worker zum Absturz bringen können, z.B. --prof, --title. Siehe https://github.com/nodejs/node/issues/41103.

poolOptions.forks

Optionen für den forks-Pool.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      forks: {
        // Forks-bezogene Optionen hier
      },
    },
  },
});

poolOptions.forks.maxForks*

• Typ: number | string
• Standard: verfügbare CPUs

Maximale Anzahl oder prozentualer Anteil der Forks. Sie können auch die Umgebungsvariable VITEST_MAX_FORKS nutzen.

poolOptions.forks.minForks*

• Typ: number | string
• Standard: verfügbare CPUs

Minimale Anzahl oder prozentualer Anteil der Forks. Sie können auch die Umgebungsvariable VITEST_MIN_FORKS nutzen.

poolOptions.forks.isolate

• Typ: boolean
• Standard: true

Umgebung für jede Testdatei isolieren.

poolOptions.forks.singleFork

• Typ: boolean
• Standard: false

Führt alle Tests mit derselben Umgebung in einem einzigen Child-Prozess aus. Dies deaktiviert die integrierte Modulisolierung (Ihr Quellcode oder direkt eingebundener Code wird weiterhin für jeden Test neu evaluiert), kann aber die Testleistung verbessern.

WARNING

Obwohl diese Option Tests dazu zwingt, nacheinander ausgeführt zu werden, unterscheidet sich diese Option von Jests --runInBand. Vitest verwendet Child-Prozesse nicht nur zum parallelen Ausführen von Tests, sondern auch um Isolation zu gewährleisten. Durch Deaktivieren dieser Option werden Ihre Tests sequenziell ausgeführt, aber im selben globalen Kontext, sodass Sie die Isolation selbst sicherstellen müssen.

Dies kann zu allen möglichen Problemen führen, wenn Sie sich auf den globalen Zustand verlassen (Frontend-Frameworks tun dies normalerweise) oder Ihr Code darauf angewiesen ist, dass die Umgebung für jeden Test separat definiert wird. Kann aber die Tests erheblich beschleunigen (bis zu 3-mal schneller), insbesondere solche, die nicht unbedingt auf den globalen Zustand angewiesen sind oder dies leicht umgehen können.

poolOptions.forks.execArgv*

• Typ: string[]
• Standard: []

Zusätzliche Argumente an den node-Prozess in den Kindprozessen übergeben. Weitere Informationen finden Sie unter Command-line API | Node.js.

WARNING

Seien Sie vorsichtig bei der Verwendung, da einige Optionen den Worker zum Absturz bringen können, z.B. --prof, --title. Siehe https://github.com/nodejs/node/issues/41103.

poolOptions.vmThreads

Optionen für den vmThreads-Pool.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmThreads: {
        // VM-Threads-bezogene Optionen hier
      },
    },
  },
});

poolOptions.vmThreads.maxThreads*

• Typ: number | string
• Standard: verfügbare CPUs

Maximale Anzahl oder prozentualer Anteil der Threads. Sie können auch die Umgebungsvariable VITEST_MAX_THREADS nutzen.

poolOptions.vmThreads.minThreads*

• Typ: number | string
• Standard: verfügbare CPUs

Minimale Anzahl oder prozentualer Anteil der Threads. Sie können auch die Umgebungsvariable VITEST_MIN_THREADS nutzen.

poolOptions.vmThreads.memoryLimit*

• Typ: string | number
• Standard: 1 / CPU Cores

Gibt das Speicherlimit für Worker an, bevor sie wiederverwendet werden. Dieser Wert hängt stark von Ihrer Umgebung ab, daher ist es besser, ihn manuell festzulegen, anstatt sich auf den Standardwert zu verlassen.

TIP

Die Implementierung basiert auf Jests workerIdleMemoryLimit.

Das Limit kann auf verschiedene Arten angegeben werden, wobei das Ergebnis stets mit Math.floor in einen Ganzzahlwert umgewandelt wird:

• <= 1 - Der Wert wird als Prozentsatz des Systemspeichers angenommen. So setzt 0.5 das Speicherlimit des Workers auf die Hälfte des gesamten Systemspeichers.
• \> 1 - Gilt als fester Byte-Wert. Aufgrund der vorherigen Regel könnten Sie, wenn Sie einen Wert von 1 Byte (warum auch immer) wünschen, 1.1 verwenden.
• Mit Einheiten
  • 50% - Wie oben, ein Prozentsatz des gesamten Systemspeichers
  • 100KB, 65MB, etc. - Mit Einheiten zur Angabe eines festen Speicherlimits.
    • K / KB - Kilobytes (x1000)
    • KiB - Kibibytes (x1024)
    • M / MB - Megabytes - MiB - Mebibytes
    • G / GB - Gigabytes - GiB - Gibibytes

WARNING

Die prozentuale Speicherbegrenzung funktioniert auf Linux CircleCI Workern nicht, da der System-Speicher dort falsch gemeldet wird.

poolOptions.vmThreads.useAtomics*

• Typ: boolean
• Standard: false

Verwenden Sie Atomics, um Threads zu synchronisieren.

Dies kann in einigen Fällen die Leistung verbessern, könnte aber in älteren Node-Versionen Segmentierungsfehler verursachen.

poolOptions.vmThreads.execArgv*

• Typ: string[]
• Standard: []

Zusätzliche Argumente an den node-Prozess im VM-Kontext übergeben. Weitere Informationen finden Sie unter Command-line API | Node.js.

WARNING

Seien Sie vorsichtig bei der Verwendung, da einige Optionen den Worker zum Absturz bringen können, z.B. --prof, --title. Siehe https://github.com/nodejs/node/issues/41103.

poolOptions.vmForks*

Optionen für den vmForks-Pool.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmForks: {
        // VM-Forks-bezogene Optionen hier
      },
    },
  },
});

poolOptions.vmForks.maxForks*

• Typ: number | string
• Standard: verfügbare CPUs

Maximale Anzahl oder prozentualer Anteil der Forks. Sie können auch die Umgebungsvariable VITEST_MAX_FORKS nutzen.

poolOptions.vmForks.minForks*

• Typ: number | string
• Standard: verfügbare CPUs

Minimale Anzahl oder prozentualer Anteil der Forks. Sie können auch die Umgebungsvariable VITEST_MIN_FORKS nutzen.

poolOptions.vmForks.memoryLimit*

• Typ: string | number
• Standard: 1 / CPU Cores

Gibt das Speicherlimit für Worker an, bevor sie wiederverwendet werden. Dieser Wert hängt stark von Ihrer Umgebung ab, daher ist es besser, ihn manuell festzulegen, anstatt sich auf den Standardwert zu verlassen. Die Berechnung des Wertes wird unter poolOptions.vmThreads.memoryLimit beschrieben.

poolOptions.vmForks.execArgv*

• Typ: string[]
• Standard: []

Zusätzliche Argumente an den node-Prozess im VM-Kontext übergeben. Weitere Informationen finden Sie unter Command-line API | Node.js.

WARNING

Seien Sie vorsichtig bei der Verwendung, da einige Optionen den Worker zum Absturz bringen können, z.B. --prof, --title. Siehe https://github.com/nodejs/node/issues/41103.

fileParallelism*

• Typ: boolean
• Standard: true
• CLI: --no-file-parallelism, --fileParallelism=false

Sollen alle Testdateien parallel ausgeführt werden? Wenn diese Option auf false gesetzt wird, werden die Optionen maxWorkers und minWorkers auf 1 gesetzt.

TIP

Diese Option wirkt sich nicht auf Tests aus, die in derselben Datei ausgeführt werden. Wenn Sie diese parallel ausführen möchten, verwenden Sie die Option concurrent für describe oder über eine Konfiguration.

maxWorkers*

• Typ: number | string

Maximale Anzahl oder prozentualer Anteil der Worker, in denen Tests ausgeführt werden sollen. poolOptions.{threads,vmThreads}.maxThreads/poolOptions.forks.maxForks besitzt eine höhere Priorität.

minWorkers*

• Typ: number | string

Minimale Anzahl oder prozentualer Anteil der Worker, in denen Tests ausgeführt werden sollen. poolOptions.{threads,vmThreads}.minThreads/poolOptions.forks.minForks besitzt eine höhere Priorität.

testTimeout

• Typ: number
• Standard: 5_000 in Node.js, 15_000 wenn browser.enabled true ist
• CLI: --test-timeout=5000, --testTimeout=5000

Standard-Timeout für einen Test in Millisekunden. Verwenden Sie 0, um die Timeout-Funktion vollständig zu deaktivieren.

hookTimeout

• Typ: number
• Standard: 10_000 in Node.js, 30_000 wenn browser.enabled true ist
• CLI: --hook-timeout=10000, --hookTimeout=10000

Standard-Timeout für einen Hook in Millisekunden. Verwenden Sie 0, um das Timeout vollständig zu deaktivieren.

teardownTimeout*

• Typ: number
• Standard: 10000
• CLI: --teardown-timeout=5000, --teardownTimeout=5000

Standard-Timeout in Millisekunden, das Vitest beim Herunterfahren auf das Beenden wartet.

silent*

• Typ: boolean | 'passed-only'
• Standard: false
• CLI: --silent, --silent=false

Konsolenausgabe von Tests unterdrücken.

Verwenden Sie 'passed-only', um nur die Protokolle fehlgeschlagener Tests anzuzeigen. Protokolle von fehlgeschlagenen Tests werden ausgegeben, nachdem ein Test abgeschlossen ist.

setupFiles

• Typ: string | string[]

Pfad zu Setup-Dateien. Sie werden vor jeder Testdatei geladen und ausgeführt.

INFO

Das Bearbeiten einer Setup-Datei führt automatisch zu einer erneuten Ausführung aller Tests.

Sie können process.env.VITEST_POOL_ID (einen String, der einer Ganzzahl ähnelt) verwenden, um zwischen Threads zu unterscheiden.

TIP

Beachten Sie, dass diese Setup-Datei mehrmals im selben globalen Bereich ausgeführt wird, wenn Sie --isolate=false verwenden. Das bedeutet, dass Sie vor jedem Test auf dasselbe globale Objekt zugreifen. Stellen Sie daher sicher, dass Sie keine unnötigen Wiederholungen durchführen.

Zum Beispiel könnten Sie eine globale Variable verwenden:

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

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

// Hooks werden vor jeder Suite auf ihren Ursprungszustand zurückgesetzt
afterEach(() => {
  cleanup();
});

globalThis.resetBeforeEachTest = true;

provide 2.1.0+

• Typ: Partial<ProvidedContext>

Definieren Sie Werte, auf die in Ihren Tests mit der inject-Methode zugegriffen werden können.

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

Eigenschaften müssen vom Typ String sein und Werte müssen serialisierbar sein, da dieses Objekt zwischen verschiedenen Prozessen übertragen wird.

TIP

Wenn Sie TypeScript verwenden, müssen Sie den Typ ProvidedContext für den typsicheren Zugriff ergänzen:

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

// Diese Datei als Modul markieren, damit die Erweiterung korrekt funktioniert
export {};

globalSetup

• Typ: string | string[]

Pfad zu globalen Setup-Dateien, relativ zum Projekt-Stammverzeichnis.

Eine globale Setup-Datei kann entweder die benannten Funktionen setup und teardown exportieren oder eine default-Funktion, die eine Teardown-Funktion zurückgibt (Beispiel).

INFO

Mehrere globalSetup-Dateien können verwendet werden. Setup und Teardown werden sequenziell ausgeführt, wobei Teardown in umgekehrter Reihenfolge ausgeführt wird.

WARNING

Das globale Setup wird nur ausgeführt, wenn mindestens ein Test aktiv ist. Das bedeutet, dass das globale Setup im Watch-Modus nach dem Ändern einer Testdatei beginnen kann (die Testdatei wartet, bis das globale Setup abgeschlossen ist, bevor sie ausgeführt wird).

Seien Sie sich bewusst, dass das globale Setup in einem anderen globalen Bereich ausgeführt wird, sodass Ihre Tests keinen Zugriff auf hier definierte Variablen haben. Sie können jedoch serialisierbare Daten über die provide-Methode an Tests übergeben:

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;
  }
}

Seit Vitest 3 können Sie eine benutzerdefinierte Callback-Funktion definieren, die bei der erneuten Ausführung von Tests durch Vitest aufgerufen wird. Wenn die Funktion asynchron ist, wartet der Runner, bis sie beendet ist, bevor er Tests ausführt. Beachten Sie, dass Sie das project nicht wie { onTestsRerun } destrukturieren können, da es vom Kontext abhängt.

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

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

forceRerunTriggers*

• Typ: string[]
• Standard: ['**/package.json/**', '**/vitest.config.*/**', '**/vite.config.*/**']

Glob-Muster für Dateipfade, die eine erneute Ausführung der gesamten Suite auslösen. In Verbindung mit dem Argument --changed wird die gesamte Testsuite ausgeführt, wenn der Trigger im Git-Diff gefunden wird.

Nützlich, wenn Sie das Aufrufen von CLI-Befehlen testen, da Vite keinen Modulgraphen erstellen kann:

test('execute a script', async () => {
  // Vitest kann diesen Test nicht erneut ausführen, falls sich der Inhalt von `dist/index.js` ändert
  await execa('node', ['dist/index.js']);
});

TIP

Stellen Sie sicher, dass Ihre Dateien nicht von server.watch.ignored ausgeschlossen werden.

coverage*

Sie können v8, istanbul oder eine benutzerdefinierte Code-Abdeckungslösung für die Code-Abdeckungserfassung verwenden.

Sie können Coverage-Optionen an die CLI im Punktnotation-Format übergeben:

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

WARNING

Wenn Sie Coverage-Optionen mit Punktnotation verwenden, vergessen Sie nicht, --coverage.enabled festzulegen. Verwenden Sie in diesem Fall keine einzelne --coverage-Option.

coverage.provider

• Typ: 'v8' | 'istanbul' | 'custom'
• Standard: 'v8'
• CLI: --coverage.provider=<provider>

Verwenden Sie provider, um das Tool für die Code-Abdeckungserfassung auszuwählen.

coverage.enabled

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.enabled, --coverage.enabled=false

Aktiviert die Code-Abdeckungserfassung. Kann durch die CLI-Option --coverage überschrieben werden.

coverage.include

• Typ: string[]
• Standard: ['**']
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.include=<path>, --coverage.include=<path1> --coverage.include=<path2>

Liste der Dateien, die in die Code-Abdeckung eingeschlossen werden sollen, als Glob-Muster.

coverage.extension

• Typ: string | string[]
• Standard: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.tsx', '.jsx', '.vue', '.svelte', '.marko', '.astro']
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

coverage.exclude

• Typ: string[]
• Standard:

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

• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

Liste der Dateien, die als Glob-Muster von der Code-Abdeckung ausgeschlossen werden.

Diese Option setzt alle Standardoptionen außer Kraft. Erweitern Sie die Standardoptionen, wenn Sie neue Muster zum Ignorieren hinzufügen:

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

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

HINWEIS

Vitest fügt automatisch die include-Muster für Testdateien zu coverage.exclude hinzu. Es ist nicht möglich, die Code-Abdeckung von Testdateien anzuzeigen.

coverage.all

• Typ: boolean
• Standard: true
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.all, --coverage.all=false

Ob alle Dateien, einschließlich der ungetesteten, in den Bericht einbezogen werden sollen.

coverage.clean

• Typ: boolean
• Standard: true
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.clean, --coverage.clean=false

Code-Abdeckungsergebnisse vor dem Ausführen von Tests bereinigen.

coverage.cleanOnRerun

• Typ: boolean
• Standard: true
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

Code-Abdeckungsbericht bei erneuter Ausführung im Watch-Modus bereinigen. Auf false setzen, um Code-Abdeckungsergebnisse aus dem vorherigen Lauf im Watch-Modus beizubehalten.

coverage.reportsDirectory

• Typ: string
• Standard: './coverage'
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.reportsDirectory=<path>

WARNING

Vitest löscht dieses Verzeichnis vor dem Ausführen von Tests, sofern coverage.clean aktiviert ist (Standardwert).

Verzeichnis, in das der Code-Abdeckungsbericht geschrieben werden soll.

Um den Code-Abdeckungsbericht in der Ausgabe des HTML-Reporters anzuzeigen, muss diese Option als Unterverzeichnis des HTML-Berichtsverzeichnisses festgelegt werden (z.B. ./html/coverage).

coverage.reporter

• Typ: string | string[] | [string, {}][]
• Standard: ['text', 'html', 'clover', 'json']
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.reporter=<reporter>, --coverage.reporter=<reporter1> --coverage.reporter=<reporter2>

Zu verwendende Code-Abdeckungsreporter. Eine detaillierte Liste aller Reporter ist in der Istanbul-Dokumentation zu finden. Details zu reporterspezifischen Optionen sind unter @types/istanbul-reporter zu finden.

Der Reporter kann in drei verschiedenen Typen vorliegen:

• Als einzelner Reporter: { reporter: 'html' }
• Mehrere Reporter ohne zusätzliche Optionen: { reporter: ['html', 'json'] }
• Ein einzelner oder mehrere Reporter mit spezifischen Optionen:

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

Sie können auch benutzerdefinierte Code-Abdeckungsreporter übergeben. Weitere Informationen finden Sie unter Guide - Custom Coverage Reporter.

{
  reporter: [
    // Reporter über den Namen des NPM-Pakets festlegen
    '@vitest/custom-coverage-reporter',
    ['@vitest/custom-coverage-reporter', { someOption: true }],

    // Reporter über lokalen Pfad festlegen
    '/absolute/path/to/custom-reporter.cjs',
    ['/absolute/path/to/custom-reporter.cjs', { someOption: true }],
  ];
}

Sie können Ihren Code-Abdeckungsbericht in der Vitest UI überprüfen: Weitere Details finden Sie unter Vitest UI Coverage.

coverage.reportOnFailure

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.reportOnFailure, --coverage.reportOnFailure=false

Code-Abdeckungsbericht auch bei fehlgeschlagenen Tests generieren.

coverage.allowExternal

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.allowExternal, --coverage.allowExternal=false

Code-Abdeckung von Dateien außerhalb des Projekt-Stammverzeichnisses erfassen.

coverage.excludeAfterRemap 2.1.0+

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.excludeAfterRemap, --coverage.excludeAfterRemap=false

Ausschlüsse erneut anwenden, nachdem die Code-Abdeckung auf die ursprünglichen Quellen zurückgeführt wurde. Dies ist nützlich, wenn Ihre Quelldateien transpiliert werden und möglicherweise Quellzuordnungen von Nicht-Quelldateien enthalten.

Verwenden Sie diese Option, wenn Sie Dateien im Bericht sehen, obwohl sie Ihren coverage.exclude-Mustern entsprechen.

coverage.skipFull

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.skipFull, --coverage.skipFull=false

Dateien mit 100% Anweisungs-, Branch- und Funktions-Code-Abdeckung nicht anzeigen.

coverage.thresholds

Optionen für Coverage-Schwellenwerte.

Wenn ein Schwellenwert auf eine positive Zahl gesetzt wird, wird er als der erforderliche Mindestprozentsatz der Code-Abdeckung interpretiert. Zum Beispiel bedeutet das Setzen des Zeilenschwellenwerts auf 90, dass 90% der Zeilen abgedeckt werden müssen.

Wenn ein Schwellenwert auf eine negative Zahl gesetzt wird, wird er als die maximal zulässige Anzahl ungedeckter Elemente interpretiert. Zum Beispiel bedeutet das Setzen des Zeilenschwellenwerts auf -10, dass nicht mehr als 10 Zeilen ungedeckt bleiben dürfen.

{
  coverage: {
    thresholds: {
      // Erfordert 90% Funktions-Coverage
      functions: 90,

      // Erfordert, dass nicht mehr als 10 Zeilen ungedeckt sind
      lines: -10,
    }
  }
}

coverage.thresholds.lines

• Typ: number
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.lines=<number>

Globaler Schwellenwert für die Zeilen-Coverage.

coverage.thresholds.functions

• Typ: number
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.functions=<number>

Globaler Schwellenwert für die Funktions-Coverage.

coverage.thresholds.branches

• Typ: number
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.branches=<number>

Globaler Schwellenwert für die Branch-Coverage.

coverage.thresholds.statements

• Typ: number
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.statements=<number>

Globaler Schwellenwert für die Anweisungs-Coverage.

coverage.thresholds.perFile

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.perFile, --coverage.thresholds.perFile=false

Schwellenwerte pro Datei überprüfen.

coverage.thresholds.autoUpdate

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.autoUpdate=<boolean>

Alle Schwellenwerte für Zeilen, Funktionen, Branches und Anweisungen in der Konfigurationsdatei aktualisieren, sofern die aktuelle Code-Abdeckung besser ist als die konfigurierten Schwellenwerte. Diese Option hilft, die Schwellenwerte beizubehalten, wenn die Code-Abdeckung verbessert wird.

coverage.thresholds.100

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.100, --coverage.thresholds.100=false

Setzt die globalen Schwellenwerte auf 100%. Kurzform für --coverage.thresholds.lines 100 --coverage.thresholds.functions 100 --coverage.thresholds.branches 100 --coverage.thresholds.statements 100.

coverage.thresholds[glob-pattern]

• Typ: { statements?: number functions?: number branches?: number lines?: number }
• Standard: undefined
• Verfügbar für Provider: 'v8' | 'istanbul'

Setzt Schwellenwerte für Dateien, die dem Glob-Muster übereinstimmen.

HINWEIS

Vitest zählt alle Dateien, einschließlich derer, die von Glob-Mustern abgedeckt werden, zu den globalen Code-Abdeckungs-Schwellenwerten. Dies weicht vom Jest-Verhalten ab.

{
  coverage: {
    thresholds: {
      // Schwellenwerte für die gesamte Codebasis
      functions: 95,
      branches: 70,

      // Schwellenwerte für übereinstimmende Glob-Muster
      'src/utils/**.ts': {
        statements: 95,
        functions: 90,
        branches: 85,
        lines: 80,
      },

      // Dateien, die diesem Muster entsprechen, erhalten nur Zeilenschwellenwerte.
      // Globale Schwellenwerte werden nicht übernommen.
      '**/math.ts': {
        lines: 100,
      }
    }
  }
}

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

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8' | 'istanbul'

Setzt Schwellenwerte auf 100% für Dateien, die dem Glob-Muster übereinstimmen.

{
  coverage: {
    thresholds: {
      // Schwellenwerte für die gesamte Codebasis
      functions: 95,
      branches: 70,

      // Schwellenwerte für übereinstimmende Glob-Muster
      'src/utils/**.ts': { 100: true },
      '**/math.ts': { 100: true }
    }
  }
}

coverage.ignoreEmptyLines

• Typ: boolean
• Standard: true (false in v1)
• Verfügbar für Provider: 'v8'
• CLI: --coverage.ignoreEmptyLines=<boolean>

Leere Zeilen, Kommentare und anderen Nicht-Laufzeit-Code, z.B. Typescript-Typen, werden ignoriert. Dies erfordert experimentalAstAwareRemapping: false.

Diese Option ist nur wirksam, wenn der verwendete Compiler Kommentare und anderen Nicht-Laufzeit-Code aus dem transpilierten Code entfernt. Standardmäßig verwendet Vite ESBuild, welches Kommentare und Typescript-Typen aus .ts-, .tsx- und .jsx-Dateien entfernt.

Wenn Sie ESBuild auch auf andere Dateien verwenden möchten, definieren Sie diese in den esbuild-Optionen:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  esbuild: {
    // Transpilieren Sie alle Dateien mit ESBuild, um Kommentare aus der Code-Coverage zu entfernen.
    // Erforderlich, damit `test.coverage.ignoreEmptyLines` funktioniert:
    include: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.ts', '**/*.tsx'],
  },
  test: {
    coverage: {
      provider: 'v8',
      ignoreEmptyLines: true,
    },
  },
});

coverage.experimentalAstAwareRemapping

• Typ: boolean
• Standard: false
• Verfügbar für Provider: 'v8'
• CLI: --coverage.experimentalAstAwareRemapping=<boolean>

Code-Abdeckung mit experimenteller AST-basierter Analyse neu zuordnen. Bietet genauere Ergebnisse im Vergleich zum Standardmodus.

coverage.ignoreClassMethods

• Typ: string[]
• Standard: []
• Verfügbar für Provider: 'istanbul'
• CLI: --coverage.ignoreClassMethods=<method>

Setzen Sie ein Array von Klassenmethodennamen, die für die Code-Abdeckung ignoriert werden sollen. Weitere Informationen finden Sie in der Istanbul-Dokumentation.

coverage.watermarks

• Typ:

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

• Standard:

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

• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.watermarks.statements=50,80, --coverage.watermarks.branches=50,80

Wasserzeichen für Anweisungen, Zeilen, Branches und Funktionen-Coverage. Weitere Informationen finden Sie in der Istanbul-Dokumentation.

coverage.processingConcurrency

• Typ: boolean
• Standard: Math.min(20, os.availableParallelism?.() ?? os.cpus().length)
• Verfügbar für Provider: 'v8' | 'istanbul'
• CLI: --coverage.processingConcurrency=<number>

Parallelitätslimit, das beim Verarbeiten der Code-Abdeckungsergebnisse verwendet wird.

coverage.customProviderModule

• Typ: string
• Verfügbar für Provider: 'custom'
• CLI: --coverage.customProviderModule=<path or module name>

Gibt den Modulnamen oder Pfad für das benutzerdefinierte Code-Abdeckungs-Provider-Modul an. Weitere Informationen finden Sie unter Guide - Custom Coverage Provider.

testNamePattern*

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

Führt Tests aus, deren vollständige Namen dem Muster übereinstimmen. Wenn Sie OnlyRunThis dieser Eigenschaft hinzufügen, werden Tests, die das Wort OnlyRunThis nicht im Testnamen enthalten, übersprungen.

import { expect, test } from 'vitest';

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

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

open*

• Typ: boolean
• Standard: !process.env.CI
• CLI: --open, --open=false

Die Vitest UI öffnen (WIP)

api

• Typ: boolean | number
• Standard: false
• CLI: --api, --api.port, --api.host, --api.strictPort

An einem Port lauschen und API bereitstellen. Bei Aktivierung ist der Standardport 51204.

browser experimentell

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

Konfiguration für Browser-Tests. Bitte schlagen Sie im Artikel "Browser Config Reference" nach.

WARNING

Dies ist eine experimentelle Funktion. Breaking Changes folgen möglicherweise nicht SemVer, bitte fixieren Sie die Vitest-Version, wenn Sie sie verwenden.

clearMocks

• Typ: boolean
• Standard: false

Ruft vor jedem Test mockClear() auf alle Spies auf. Dies löscht den Mock-Verlauf, ohne die Mock-Implementierungen zu beeinträchtigen.

mockReset

• Typ: boolean
• Standard: false

Ruft vor jedem Test mockReset() auf alle Spies auf. Dies löscht den Mock-Verlauf und setzt jede Implementierung auf ihren ursprünglichen Zustand zurück.

restoreMocks

• Typ: boolean
• Standard: false

Ruft vor jedem Test mockRestore() auf alle Spies auf. Dies löscht den Mock-Verlauf, stellt jede Implementierung auf ihren ursprünglichen Zustand zurück und stellt die ursprünglichen Deskriptoren der überwachten Objekte wieder her.

unstubEnvs

• Typ: boolean
• Standard: false

Ruft vor jedem Test vi.unstubAllEnvs auf.

unstubGlobals

• Typ: boolean
• Standard: false

Ruft vor jedem Test vi.unstubAllGlobals auf.

testTransformMode

• Typ: { web?, ssr? }

Bestimmt die Transformationsmethode für alle Module, die innerhalb eines Tests importiert werden und dem Glob-Muster übereinstimmen. Standardmäßig ist dies von der Umgebung abhängig. Zum Beispiel verarbeiten Tests mit JSDOM-Umgebung alle Dateien mit dem Flag ssr: false, während Tests mit Node-Umgebung alle Module mit ssr: true verarbeiten.

testTransformMode.ssr

• Typ: string[]
• Standard: []

Verwenden Sie die SSR-Transformationspipeline für alle Module in den angegebenen Tests.
Vite-Plugins erhalten das Flag ssr: true während der Verarbeitung dieser Dateien.

testTransformMode.web

• Typ: string[]
• Standard: []

Zuerst wird eine normale Transformationspipeline (auf den Browser ausgerichtet) durchgeführt, gefolgt von einer SSR-Umschreibung, um den Code in Node auszuführen.
Vite-Plugins erhalten das Flag ssr: false beim Verarbeiten dieser Dateien.

snapshotFormat*

• Typ: PrettyFormatOptions

Formatierungsoptionen für das Snapshot-Testing. Diese Optionen werden an pretty-format übergeben.

TIP

Beachten Sie, dass das Feld plugins in diesem Objekt ignoriert wird.

Wenn Sie den Snapshot-Serialisierer über pretty-format-Plugins anpassen müssen, verwenden Sie bitte die API expect.addSnapshotSerializer oder die Option snapshotSerializers.

snapshotSerializers*

• Typ: string[]
• Standard: []

Eine Liste von Pfaden zu Snapshot-Serialisierer-Modulen für das Snapshot-Testing, nützlich, wenn Sie benutzerdefinierte Snapshot-Serialisierer hinzufügen möchten. Weitere Informationen finden Sie unter Custom Serializer.

resolveSnapshotPath*

• Typ: (testPath: string, snapExtension: string, context: { config: SerializedConfig }) => string
• Standard: speichert Snapshot-Dateien im Verzeichnis __snapshots__

Setzt den Standard-Snapshot-Pfad außer Kraft. Zum Beispiel, um Snapshots neben den Testdateien abzulegen:

import { defineConfig } from 'vitest/config';

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

allowOnly

• Typ: boolean
• Standard: !process.env.CI
• CLI: --allowOnly, --allowOnly=false

Erlaubt Tests und Suiten, die als "only" gekennzeichnet sind.

dangerouslyIgnoreUnhandledErrors*

• Typ: boolean
• Standard: false
• CLI: --dangerouslyIgnoreUnhandledErrors --dangerouslyIgnoreUnhandledErrors=false

Alle unbehandelten Fehler, die auftreten, werden ignoriert.

passWithNoTests*

• Typ: boolean
• Standardतः: false
• CLI: --passWithNoTests, --passWithNoTests=false

Vitest wird nicht fehlschlagen, falls keine Tests gefunden werden.

logHeapUsage

• Typ: boolean
• Standard: false
• CLI: --logHeapUsage, --logHeapUsage=false

Die Heap-Nutzung wird nach jedem Test angezeigt. Nützlich für das Debugging von Speicherlecks.

css

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

Konfiguriert die Verarbeitung von CSS. Wenn ausgeschlossen, werden CSS-Dateien durch leere Strings ersetzt, um die nachfolgende Verarbeitung zu umgehen. CSS-Module geben einen Proxy zurück, damit die Laufzeit nicht beeinflusst wird.

css.include

• Typ: RegExp | RegExp[]
• Standard: []

Regulärer Ausdruck für Dateien, die tatsächliches CSS zurückgeben und von der Vite-Pipeline verarbeitet werden.

TIP

Um alle CSS-Dateien zu verarbeiten, nutzen Sie /.+/.

css.exclude

• Typ: RegExp | RegExp[]
• Standard: []

Regulärer Ausdruck für Dateien, die eine leere CSS-Datei zurückliefern.

css.modules

• Typ: { classNameStrategy? }
• Standard: {}

css.modules.classNameStrategy

• Typ: 'stable' | 'scoped' | 'non-scoped'
• Standard: 'stable'

Wenn Sie sich entscheiden, CSS-Dateien zu verarbeiten, können Sie konfigurieren, ob Klassennamen in CSS-Modulen als scoped behandelt werden sollen. Sie können eine der Optionen auswählen:

• stable: Klassennamen werden als _${name}_${hashedFilename} generiert. Dies bedeutet, dass die generierte Klasse gleich bleibt, wenn der CSS-Inhalt geändert wird, sich aber ändert, wenn der Dateiname modifiziert oder die Datei in einen anderen Ordner verschoben wird. Diese Einstellung ist nützlich, sofern Sie die Snapshot-Funktion verwenden.
• scoped: Klassennamen werden wie üblich generiert, unter Berücksichtigung der Methode css.modules.generateScopedName, sofern diese vorhanden und die CSS-Verarbeitung aktiviert ist. Standardmäßig wird der Dateiname als _${name}_${hash} generiert, wobei der Hash Dateinamen und Dateiinhalt umfasst.
• non-scoped: Klassennamen werden nicht gehasht.

WARNING

Standardmäßig exportiert Vitest einen Proxy und umgeht dabei die CSS-Modulverarbeitung. Wenn Sie von CSS-Eigenschaften Ihrer Klassen abhängig sind, müssen Sie die CSS-Verarbeitung mit der Option include aktivieren.

maxConcurrency

• Typ: number
• Standard: 5
• CLI: --max-concurrency=10, --maxConcurrency=10

Die Anzahl der Tests, die gleichzeitig mit test.concurrent ausgeführt werden dürfen.

Tests über diesem Limit werden in eine Warteschlange gestellt, um ausgeführt zu werden, sobald ein verfügbarer Slot frei wird.

cache*

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

Verwenden Sie diese Option, wenn Sie die Caching-Funktion deaktivieren möchten. Derzeit speichert Vitest Testergebnisse im Cache, um die längeren und fehlgeschlagenen Tests zuerst auszuführen.

Das Cache-Verzeichnis wird von der Vite-Option cacheDir gesteuert:

import { defineConfig } from 'vitest/config';

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

Sie können das Verzeichnis nur auf Vitest beschränken, indem Sie process.env.VITEST verwenden:

import { defineConfig } from 'vitest/config';

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

sequence

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

Optionen zur Sortierung von Tests.

Sie können Sequenzoptionen an die CLI im Punktnotation-Format übergeben:

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

sequence.sequencer*

• Typ: TestSequencerConstructor
• Standard: BaseSequencer

Eine benutzerdefinierte Klasse, die Methoden für Sharding und Sortierung definiert. Sie können BaseSequencer von vitest/node erweitern, sofern Sie nur eine der Methoden sort und shard neu definieren müssen, aber beide sollten existieren.

Sharding wird vor dem Sortieren durchgeführt und nur, wenn die Option --shard angegeben ist.

Wenn sequencer.groupOrder festgelegt ist, wird der Sequenzer einmal für jede Gruppe und jeden Pool aufgerufen.

groupOrder 3.2.0+

• Typ: number
• Standard: 0

Steuert die Reihenfolge, in der dieses Projekt seine Tests bei Verwendung mehrerer Projekte ausführt.

• Projekte mit derselben Gruppenordnungsnummer werden gemeinsam ausgeführt, und Gruppen werden von der niedrigsten zur höchsten ausgeführt.
• Wenn Sie diese Option nicht setzen, werden alle Projekte parallel ausgeführt.
• Wenn mehrere Projekte dieselbe Gruppenordnung verwenden, laufen sie gleichzeitig.

Diese Einstellung wirkt sich nur auf die Reihenfolge aus, in der Projekte ausgeführt werden, nicht auf die Reihenfolge der Tests innerhalb eines Projekts. Um die Testisolation oder die Reihenfolge der Tests innerhalb eines Projekts zu kontrollieren, verwenden Sie die Optionen isolate und sequence.sequencer.

Beispiel

Betrachten Sie dieses Beispiel:

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

Tests in diesen Projekten werden in dieser Reihenfolge ausgeführt:

 0. slow  |
          |> werden gemeinsam ausgeführt
 0. fast  |

 1. flaky |> wird nach slow und fast allein ausgeführt

sequence.shuffle

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

Wenn Sie möchten, dass Dateien und Tests zufällig ausgeführt werden, können Sie dies mit dieser Option oder dem CLI-Argument --sequence.shuffle ermöglichen.

Vitest verwendet normalerweise den Cache, um Tests zu sortieren, wodurch lang laufende Tests früher beginnen – dies beschleunigt die Testausführung. Wenn Ihre Dateien und Tests in zufälliger Reihenfolge ausgeführt werden, geht diese Leistungsverbesserung verloren. Es kann jedoch nützlich sein, Tests zu verfolgen, die versehentlich von einem zuvor ausgeführten Test abhängen.

sequence.shuffle.files

• Typ: boolean
• Standard: false
• CLI: --sequence.shuffle.files, --sequence.shuffle.files=false

Sollen Dateien zufällig angeordnet werden? Beachten Sie, dass lang laufende Tests nicht früher starten, wenn Sie diese Option aktivieren.

sequence.shuffle.tests

• Typ: boolean
• Standard: false
• CLI: --sequence.shuffle.tests, --sequence.shuffle.tests=false

Sollen Tests zufällig angeordnet werden?

sequence.concurrent

• Typ: boolean
• Standard: false
• CLI: --sequence.concurrent, --sequence.concurrent=false

Wenn Sie möchten, dass Tests parallel ausgeführt werden, können Sie dies mit dieser Option oder dem CLI-Argument --sequence.concurrent ermöglichen.

sequence.seed*

• Typ: number
• Standard: Date.now()
• CLI: --sequence.seed=1000

Setzt den Randomisierungs-Seed, falls Tests in zufälliger Reihenfolge ausgeführt werden.

sequence.hooks

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

Ändert die Reihenfolge der Ausführung von Hooks.

• stack sortiert "after"-Hooks in umgekehrter Reihenfolge, "before"-Hooks werden in der Reihenfolge ausgeführt, in der sie definiert wurden.
• list sortiert alle Hooks in der Reihenfolge, in der sie definiert sind.
• parallel führt Hooks in einer einzelnen Gruppe parallel aus (Hooks in übergeordneten Suiten werden weiterhin vor den Hooks der aktuellen Suite ausgeführt).

TIP

Diese Option wirkt sich nicht auf onTestFinished aus. Der Aufruf erfolgt immer in umgekehrter Reihenfolge.

sequence.setupFiles

• Typ: 'list' | 'parallel'
• Standard: 'parallel'
• CLI: --sequence.setupFiles=<value>

Ändert die Reihenfolge der Ausführung von Setup-Dateien.

• list führt Setup-Dateien in der Reihenfolge aus, in der sie definiert sind.
• parallel führt Setup-Dateien parallel aus.

typecheck

Optionen zur Konfiguration der Testumgebung für die Typüberprüfung.

typecheck.enabled

• Typ: boolean
• Standard: false
• CLI: --typecheck, --typecheck.enabled

Aktiviert die Typüberprüfung zusätzlich zu Ihren regulären Tests.

typecheck.only

• Typ: boolean
• Standard: false
• CLI: --typecheck.only

Führt nur Typüberprüfungstests aus, sofern die Typüberprüfung aktiviert ist. Bei Verwendung der CLI führt diese Option automatisch zur Aktivierung der Typüberprüfung.

typecheck.checker

• Typ: 'tsc' | 'vue-tsc' | string
• Standard: tsc

Welche Tools für die Typüberprüfung zum Einsatz kommen sollen. Vitest erzeugt einen Prozess mit bestimmten Parametern zur einfacheren Analyse, abhängig vom Typ. Der Checker sollte das gleiche Ausgabeformat wie tsc liefern.

Sie müssen ein Paket installiert haben, um den Typechecker zu verwenden:

• tsc erfordert das Paket typescript
• vue-tsc erfordert das Paket vue-tsc

Sie können auch einen Pfad zu einem benutzerdefinierten Binärprogramm oder einen Befehlsnamen übergeben, der dieselbe Ausgabe wie tsc --noEmit --pretty false erzeugt.

typecheck.include

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

Glob-Muster für Dateien, die als Testdateien gelten sollen.

typecheck.exclude

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

Glob-Muster für Dateien, die nicht als Testdateien gelten sollen.

typecheck.allowJs

• Typ: boolean
• Standard: false

JS-Dateien prüfen, die einen @ts-check-Kommentar enthalten. Wenn Sie dies in tsconfig aktiviert haben, wird dies nicht überschrieben.

typecheck.ignoreSourceErrors

• Typ: boolean
• Standard: false

Es wird kein Fehler ausgelöst, falls Vitest Fehler außerhalb der Testdateien findet. Dies zeigt Ihnen überhaupt keine Fehler außerhalb der Tests an.

Standardmäßig schlägt Vitest die Testsuite fehl, falls es einen Quellfehler findet.

typecheck.tsconfig

• Typ: string
• Standard: versucht, die nächstgelegene tsconfig.json zu finden

Pfad zu einer benutzerdefinierten tsconfig, relativ zum Projekt-Stammverzeichnis.

typecheck.spawnTimeout

• Typ: number
• Standard: 10_000

Mindestzeit in Millisekunden, die für das Starten des Typecheckers benötigt wird.

slowTestThreshold*

• Typ: number
• Standard: 300
• CLI: --slow-test-threshold=<number>, --slowTestThreshold=<number>

Die Anzahl der Millisekunden, ab der ein Test oder eine Suite als langsam gilt und entsprechend in den Ergebnissen gemeldet wird.

chaiConfig

• Typ: { includeStack?, showDiff?, truncateThreshold? }
• Standard: { includeStack: false, showDiff: true, truncateThreshold: 40 }

Ist äquivalent zu Chai config.

chaiConfig.includeStack

• Typ: boolean
• Standard: false

Beeinflusst, ob der Stack-Trace in der Assertion-Fehlermeldung angezeigt wird. Der Standardwert false bewirkt, dass der Stack-Trace in der Fehlermeldung unterdrückt wird.

chaiConfig.showDiff

• Typ: boolean
• Standard: true

Beeinflusst, ob das showDiff-Flag in den ausgelösten AssertionErrors enthalten sein soll. false bleibt immer false; true wird gesetzt, wenn die Assertion eine Diff-Anzeige angefordert hat.

chaiConfig.truncateThreshold

• Typ: number
• Standard: 40

Legt den Längenschwellenwert für tatsächliche und erwartete Werte in Assertionsfehlern fest. Wird dieser Schwellenwert überschritten, z.B. bei großen Datenstrukturen, wird der Wert durch etwas wie [ Array(3) ] oder { Object (prop1, prop2) } ersetzt. Setzen Sie ihn auf 0, wenn Sie das Kürzen vollständig deaktivieren möchten.

Diese Konfigurationsoption beeinflusst das Kürzen von Werten in test.each-Titeln und innerhalb der Assertionsfehlermeldung.

bail

• Typ: number
• Standard: 0
• CLI: --bail=<value>

Testausführung stoppen, sobald die angegebene Anzahl von Tests fehlgeschlagen ist.

Standardmäßig führt Vitest alle Ihre Testfälle aus, selbst wenn einige davon fehlschlagen. Dies ist möglicherweise nicht für CI-Builds erwünscht, bei denen Sie nur an 100% erfolgreichen Builds interessiert sind und die Testausführung so früh wie möglich stoppen möchten, sobald Testfehler auftreten. Die bail-Option kann verwendet werden, um CI-Läufe zu beschleunigen, indem verhindert wird, dass weitere Tests ausgeführt werden, sobald Fehler aufgetreten sind.

retry

• Typ: number
• Standard: 0
• CLI: --retry=<value>

Den Test eine bestimmte Anzahl von Malen wiederholen, falls er fehlschlägt.

onConsoleLog*

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

Benutzerdefinierter Handler für console.log-Ausgaben in Tests. Wenn Sie false zurückgeben, wird das Protokoll nicht auf der Konsole ausgegeben.

Kann nützlich sein, um Protokolle von Drittanbieterbibliotheken zu filtern.

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*

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

Wendet eine Filterfunktion auf jeden Frame jedes Stack-Traces während der Fehlerbehandlung an. Das erste Argument, error, ist ein Objekt, das dieselben Eigenschaften wie eine Standard-Error-Instanz besitzt, aber es ist keine tatsächliche Instanz.

Kann nützlich sein, um Stack-Trace-Frames von Drittanbieterbibliotheken zu filtern.

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

export default defineConfig({
  test: {
    onStackTrace(error: Error, { file }: ParsedStack): boolean | void {
      // Wenn wir einen ReferenceError gefunden haben, soll der gesamte Stack angezeigt werden.
      if (error.name === 'ReferenceError') {
        return;
      }

      // Alle Frames von Drittanbieterbibliotheken ignorieren.
      if (file.includes('node_modules')) {
        return false;
      }
    },
  },
});

diff

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

DiffOptions-Objekt oder ein Pfad zu einem Modul, welches DiffOptions exportiert. Nützlich, wenn Sie die Anzeige der Unterschiede anpassen möchten.

Zum Beispiel als Konfigurationsobjekt:

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

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

Oder als Modul:

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

• Typ: boolean
• Standard: true
• CLI: --diff.expand=false

Alle gemeinsamen Zeilen werden erweitert.

diff.truncateThreshold

• Typ: number
• Standard: 0
• CLI: --diff.truncateThreshold=<path>

Die maximale Länge des Diff-Ergebnisses für die Anzeige. Diffs über diesem Schwellenwert werden gekürzt. Das Kürzen wird bei Standardwert 0 nicht wirksam.

diff.truncateAnnotation

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

Anmerkung, die am Ende des Diff-Ergebnisses ausgegeben wird, falls es gekürzt wird.

diff.truncateAnnotationColor

• Typ: DiffOptionsColor = (arg: string) => string
• Standard: noColor = (string: string): string => string

Farbe der Truncate-Anmerkung; standardmäßig erfolgt die Ausgabe ohne Farbe.

diff.printBasicPrototype

• Typ: boolean
• Standard: false

Grundlegende Prototypen Object und Array in der Diff-Ausgabe drucken.

diff.maxDepth

• Typ: number
• Standard: 20 (oder 8 beim Vergleichen verschiedener Typen)

Begrenzt die Rekursionstiefe beim Drucken verschachtelter Objekte.

fakeTimers

• Typ: FakeTimerInstallOpts

Optionen, die Vitest an @sinon/fake-timers übergibt, wenn vi.useFakeTimers() verwendet wird.

fakeTimers.now

• Typ: number | Date
• Standard: Date.now()

Installiert simulierte Timer mit der angegebenen Unix-Epoche.

fakeTimers.toFake

• Typ: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]
• Standard: alles global Verfügbare außer nextTick und queueMicrotask

Ein Array mit Namen globaler Methoden und APIs, die simuliert werden sollen.

Um nur setTimeout() und nextTick() zu mocken, legen Sie diese Eigenschaft als ['setTimeout', 'nextTick'] fest.

Das Mocken von nextTick wird nicht unterstützt, falls Vitest innerhalb von node:child_process mit --pool=forks ausgeführt wird. NodeJS verwendet process.nextTick intern in node:child_process und bleibt hängen, wenn es gemockt wird. Das Mocken von nextTick wird unterstützt, falls Vitest mit --pool=threads ausgeführt wird.

fakeTimers.loopLimit

• Typ: number
• Standard: 10_000

Die maximale Anzahl von Timern, die beim Aufruf von vi.runAllTimers() gestartet werden.

fakeTimers.shouldAdvanceTime

• Typ: boolean
• Standard: false

Weist @sinonjs/fake-timers an, die simulierte Zeit automatisch basierend auf der realen Systemzeitverschiebung zu inkrementieren (z.B. wird die simulierte Zeit um 20ms für jede 20ms-Änderung in der realen Systemzeit inkrementiert).

fakeTimers.advanceTimeDelta

• Typ: number
• Standard: 20

Relevant nur bei Verwendung mit shouldAdvanceTime: true. Die simulierte Zeit wird um advanceTimeDelta ms bei jeder advanceTimeDelta ms Änderung in der realen Systemzeit erhöht.

fakeTimers.shouldClearNativeTimers

• Typ: boolean
• Standard: true

Weist simulierte Timer an, "native" (d.h. nicht simulierte) Timer zu löschen, indem sie an ihre jeweiligen Handler delegiert werden. Wenn deaktiviert, kann dies zu potenziell unerwartetem Verhalten führen, falls Timer vor dem Start der simulierten Timer-Sitzung existierten.

workspace*

VERALTET

Diese Option wird als veraltet eingestuft und in der nächsten Hauptversion entfernt. Bitte nutzen Sie stattdessen projects.

• Typ: string | TestProjectConfiguration[]
• CLI: --workspace=./file.js
• Standard: vitest.{workspace,projects}.{js,ts,json} nahe der Konfigurationsdatei oder dem Root

Pfad zu einer Workspace-Konfigurationsdatei relativ zum Stammverzeichnis.

Seit Vitest 3 können Sie das Workspace-Array auch in der Stammkonfiguration definieren. Wenn der workspace manuell in der Konfiguration definiert ist, ignoriert Vitest die Datei vitest.workspace im Stammverzeichnis.

projects*

• Typ: TestProjectConfiguration[]
• Standard: []

Eine Liste von Projekten.

isolate

• Typ: boolean
• Standard: true
• CLI: --no-isolate, --isolate=false

Tests werden in einer isolierten Umgebung ausgeführt. Diese Option hat keine Auswirkung auf vmThreads und vmForks Pools.

Das Deaktivieren dieser Option kann die Leistung verbessern, sofern Ihr Code nicht auf Seiteneffekte angewiesen ist (was normalerweise für Projekte mit node-Umgebung zutrifft).

TIP

Sie können die Isolation für bestimmte Pools mithilfe der Eigenschaft poolOptions deaktivieren.

includeTaskLocation

• Typ: boolean
• Standard: false

Soll die Eigenschaft location mitgeliefert werden, wenn die Vitest API Aufgaben in Reportern empfängt? Wenn Sie viele Tests haben, könnte dies zu einer geringen Leistungseinbuße führen.

Die Eigenschaft location enthält column- und line-Werte, die der test- oder describe-Position in der Originaldatei entsprechen.

Diese Option wird automatisch aktiviert, sofern Sie sie nicht explizit deaktivieren und Vitest mit:

• Vitest UI
• oder im Browser-Modus ohne Headless-Modus
• oder mit dem HTML-Reporter

TIP

Diese Option hat keine Auswirkung, wenn Sie keinen benutzerdefinierten Code verwenden, der darauf angewiesen ist.

snapshotEnvironment

• Typ: string

Pfad zu einer benutzerdefinierten Implementierung der Snapshot-Umgebung. Dies ist nützlich, wenn Sie Ihre Tests in einer Umgebung ausführen, die keine Unterstützung für Node.js-APIs bietet. Diese Option hat keine Auswirkung auf einen Browser-Runner.

Dieses Objekt sollte der Form von SnapshotEnvironment entsprechen und wird zum Auflösen sowie zum Lesen und Schreiben von Snapshot-Dateien verwendet:

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>;
}

Sie können die Standard-VitestSnapshotEnvironment vom vitest/snapshot-Einstiegspunkt erweitern, sofern Sie nur einen Teil der API überschreiben müssen.

WARNING

Dies ist eine Option auf niedriger Ebene und sollte nur für fortgeschrittene Fälle verwendet werden, in denen Sie keinen Zugriff auf die Standard-Node.js-APIs haben.

Wenn Sie nur die Snapshot-Funktionalität konfigurieren müssen, verwenden Sie die Optionen snapshotFormat oder resolveSnapshotPath.

env

• Typ: Partial<NodeJS.ProcessEnv>

Umgebungsvariablen, die während der Tests unter process.env und import.meta.env zugänglich sind. Diese Variablen sind im Hauptprozess (z.B. in globalSetup) nicht zugänglich.

expect

• Typ: ExpectOptions

expect.requireAssertions

• Typ: boolean
• Standard: false

Ist äquivalent zum Aufruf von expect.hasAssertions() am Anfang jedes Tests. Dies stellt sicher, dass kein Test versehentlich erfolgreich ist.

TIP

Dies funktioniert nur mit der expect-Funktion von Vitest. Wenn Sie assert oder .should-Assertions verwenden, werden diese nicht gezählt, und Ihr Test schlägt aufgrund mangelnder expect-Assertions fehl.

Sie können den Wert dieser Option ändern, indem Sie vi.setConfig({ expect: { requireAssertions: false } }) aufrufen. Die Konfiguration wird auf jeden nachfolgenden expect-Aufruf übernommen, bis vi.resetConfig manuell aufgerufen wird.

expect.poll

Globale Konfigurationsoptionen für die expect.poll-Funktion. Es handelt sich um dieselben Optionen, die Sie an expect.poll(condition, options) übergeben können.

expect.poll.interval

• Typ: number
• Standard: 50

Intervall für die Abfrage in Millisekunden.

expect.poll.timeout

• Typ: number
• Standard: 1000

Timeout für die Abfrage in Millisekunden.

printConsoleTrace

• Typ: boolean
• Standard: false

Immer Konsolen-Traces ausgeben bei jedem Aufruf einer console-Methode. Dies ist nützlich für das Debugging.

attachmentsDir 3.2.0+

• Typ: string
• Standard: '.vitest-attachments'

Verzeichnispfad zum Speichern von Anhängen, die mit context.annotate erstellt wurden, relativ zum Projekt-Stammverzeichnis.