TestProject 3.0.0+

WARNING

Diese Anleitung beschreibt die fortgeschrittene Node.js-API. Wenn Sie lediglich Projekte definieren möchten, folgen Sie bitte dem Leitfaden "Testprojekte".

name

Der Name ist ein eindeutiger String, der entweder vom Benutzer zugewiesen oder von Vitest automatisch ermittelt wird. Wenn ein Benutzer keinen Namen angegeben hat, versucht Vitest, eine package.json im Stammverzeichnis des Projekts zu laden und die name-Eigenschaft daraus zu übernehmen. Ist keine package.json vorhanden, verwendet Vitest standardmäßig den Namen des Projektordners. Inline-Projekte erhalten numerische Namen, die in Strings umgewandelt werden.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // enthält package.json mit "@pkg/server"
      './utils', // enthält keine package.json-Datei
      {
        // passt den Namen nicht an
        test: {
          pool: 'threads',
        },
      },
      {
        // hat den Namen angepasst
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Wenn das Stammprojekt nicht explizit Teil der Benutzerprojekte ist, wird sein name nicht aufgelöst.

vitest

vitest verweist auf die globale Vitest-Instanz.

serializedConfig

Dies ist die Konfiguration, die an die Testprozesse übergeben wird. Vitest serialisiert die Konfiguration manuell, indem alle nicht serialisierbaren Funktionen und Eigenschaften entfernt werden. Da dieser Wert sowohl in Tests als auch in Node verfügbar ist, wird sein Typ vom Haupteinstiegspunkt exportiert.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

Die serializedConfig-Eigenschaft ist ein Getter. Bei jedem Zugriff serialisiert Vitest die Konfiguration erneut, falls sie sich geändert hat. Dies bedeutet auch, dass sie immer eine andere Referenz zurückgibt:

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

Die Testkonfiguration, mit der Vitest gestartet wurde. Wenn dies das Stammprojekt ist, verweisen globalConfig und config auf dasselbe Objekt. Diese Konfiguration wird für Werte benötigt, die nicht auf Projektebene konfigurierbar sind, wie coverage oder reporters.

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

vitest.config === vitest.projects[0].globalConfig;

config

Dies ist die vollständig aufgelöste Testkonfiguration des Projekts.

hash 3.2.0+

Der eindeutige Hash dieses Projekts. Dieser Wert bleibt über mehrere Testläufe hinweg konstant.

Er basiert auf dem Stammverzeichnis des Projekts und seinem Namen. Beachten Sie, dass der Stammverzeichnispfad zwischen verschiedenen Betriebssystemen nicht konsistent ist, sodass der Hash ebenfalls unterschiedlich sein wird.

vite

Dies ist der ViteDevServer des Projekts. Jedes Projekt verfügt über einen eigenen Vite-Server.

browser

Dieser Wert wird nur gesetzt, wenn Tests im Browser ausgeführt werden. Wenn browser aktiviert ist, die Tests aber noch nicht gestartet wurden, ist dieser Wert undefined. Um zu überprüfen, ob das Projekt Browser-Tests unterstützt, verwenden Sie die Methode project.isBrowserEnabled().

WARNING

Die Browser-API befindet sich noch in einem experimentellen Stadium und folgt nicht SemVer. Die Browser-API wird separat vom Rest der APIs standardisiert.

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Eine Möglichkeit, Tests zusätzlich zum Feld config.provide benutzerdefinierte Werte bereitzustellen. Alle Werte werden mittels structuredClone validiert, bevor sie gespeichert werden, aber die Werte im providedContext selbst werden nicht geklont.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

Die Werte können dynamisch an Tests bereitgestellt werden. Der bereitgestellte Wert in Tests wird bei ihrer nächsten Ausführung aktualisiert.

TIP

Diese Methode ist auch für globale Setup-Dateien verfügbar, falls Sie die öffentliche API nicht direkt verwenden können:

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

getProvidedContext

function getProvidedContext(): ProvidedContext;

Diese Funktion gibt das Kontextobjekt zurück. Jedes Projekt erbt auch den globalen Kontext, der von vitest.provide gesetzt wurde.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

Projektkontextwerte überschreiben immer den Kontext des Stammprojekts.

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

Erstellt eine Testspezifikation, die in vitest.runTestSpecifications verwendet werden kann. Die Spezifikation ordnet die Testdatei einem bestimmten project und optionalen Test-locations zu. Test-Positionen sind die Codezeilen, in denen der Test im Quellcode definiert wurde. Wenn locations angegeben sind, führt Vitest nur Tests aus, die an diesen Zeilen definiert sind. Beachten Sie, dass, wenn testNamePattern definiert ist, dieses ebenfalls angewendet wird.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // optionale Testzeilen
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification erwartet eine aufgelöste Modul-ID. Es erfolgt keine automatische Auflösung des Dateipfads oder Prüfung der Dateiexistenz.

Beachten Sie auch, dass project.createSpecification immer eine neue Instanz zurückgibt.

isRootProject

function isRootProject(): boolean;

Überprüft, ob das aktuelle Projekt das Stammprojekt ist. Sie können das Stammprojekt auch durch Aufruf von vitest.getRootProject() erhalten.

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * Testdateien, die den Filtern entsprechen.
   */
  testFiles: string[];
  /**
   * Typecheck-Testdateien, die den Filtern entsprechen. Dies ist leer, es sei denn, `typecheck.enabled` ist `true`.
   */
  typecheckTestFiles: string[];
};

Durchsucht alle Testdateien. Diese Funktion gibt ein Objekt zurück, das reguläre Tests und Typecheck-Tests enthält.

Diese Methode akzeptiert Filter. Filter können nur ein Teil des Dateipfads sein, im Gegensatz zu anderen Methoden auf der Vitest-Instanz:

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest verwendet fast-glob, um Testdateien zu finden. test.dir, test.root, root oder process.cwd() legen die cwd-Option fest.

Diese Methode evaluiert mehrere Konfigurationsoptionen:

• test.include, test.exclude zum Finden regulärer Testdateien
• test.includeSource, test.exclude zum Finden von In-Source-Tests
• test.typecheck.include, test.typecheck.exclude zum Finden von Typecheck-Tests

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

Diese Methode überprüft, ob die Datei eine reguläre Testdatei ist. Sie verwendet dieselben Konfigurationseigenschaften, die globTestFiles zur Validierung verwendet.

Diese Methode akzeptiert auch einen zweiten Parameter, nämlich den Quellcode. Dieser wird verwendet, um zu validieren, ob die Datei ein In-Source-Test ist. Bei mehrmaligem Aufruf dieser Methode für verschiedene Projekte wird empfohlen, die Datei einmal zu lesen und direkt weiterzugeben. Wenn die Datei keine Testdatei ist, aber dem includeSource-Glob entspricht, liest Vitest die Datei synchron, es sei denn, source wird bereitgestellt.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // true, wenn `includeSource` gesetzt ist

import

function import<T>(moduleId: string): Promise<T>

Importiert eine Datei über den Vite-Modul-Runner. Die Datei wird von Vite mit der bereitgestellten Projektkonfiguration transformiert und in einem separaten Kontext ausgeführt. Beachten Sie, dass moduleId relativ zu config.root sein wird.

DANGER

project.import wiederverwendet den Modulgraphen von Vite, sodass das Importieren desselben Moduls mit einem regulären Import ein anderes Modul zurückgibt:

import * as staticExample from './example.js';
const dynamicExample = await project.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

Intern verwendet Vitest diese Methode, um globale Setups, benutzerdefinierte Coverage-Provider und benutzerdefinierte Reporter zu importieren, was bedeutet, dass sie alle denselben Modulgraphen teilen, solange sie zum selben Vite-Server gehören.

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

Dies ist eine Kurzform für project.vitest.onTestsRerun. Es akzeptiert einen Callback, dessen Ausführung abgewartet wird, wenn die Tests zur erneuten Ausführung geplant wurden (normalerweise aufgrund einer Dateiänderung).

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

Gibt true zurück, wenn dieses Projekt Tests im Browser ausführt.

close

function close(): Promise<void>;

Schließt das Projekt und alle zugehörigen Ressourcen. Dies kann nur einmal aufgerufen werden; das Promise für den Schließvorgang wird zwischengespeichert, bis der Server neu startet. Wenn die Ressourcen erneut benötigt werden, muss ein neues Projekt erstellt werden.

Im Detail schließt diese Methode den Vite-Server, stoppt den Typechecker-Dienst, schließt den Browser, falls er läuft, löscht das temporäre Verzeichnis, in dem der Quellcode gespeichert ist, und setzt den bereitgestellten Kontext zurück.