Plugin-API 3.1.0+

WARNING

Dies ist eine erweiterte API. Wenn Sie lediglich Tests ausführen möchten, benötigen Sie diese wahrscheinlich nicht. Sie wird hauptsächlich von Bibliotheksentwicklern verwendet.

Dieser Leitfaden setzt voraus, dass Sie mit Vite-Plugins vertraut sind.

Seit Version 3.1 unterstützt Vitest einen experimentellen configureVitest-Hook für Plugins. Feedback zu dieser API ist auf GitHub willkommen.

only vitest

import type { Vite, VitestPluginContext } from 'vitest/node';

export function plugin(): Vite.Plugin {
  return {
    name: 'vitest:my-plugin',
    configureVitest(context: VitestPluginContext) {
      // ...
    },
  };
}

vite and vitest

/// <reference types="vitest/config" />

import type { Plugin } from 'vite';

export function plugin(): Plugin {
  return {
    name: 'vitest:my-plugin',
    transform() {
      // ...
    },
    configureVitest(context) {
      // ...
    },
  };
}

TypeScript

Vitest re-exportiert alle Vite-Typendefinitionen über einen Vite-Namespace, den Sie verwenden können, um Ihre Typdefinitionen synchron zu halten. Wenn Sie jedoch ein Plugin sowohl für Vite als auch für Vitest schreiben, können Sie weiterhin den Plugin-Typ vom vite-Einstiegspunkt verwenden. Stellen Sie einfach sicher, dass vitest/config irgendwo referenziert ist, damit configureVitest korrekt erweitert wird:

/// <reference types="vitest/config" />

Im Gegensatz zu reporter.onInit wird dieser Hook früh im Vitest-Lebenszyklus ausgeführt, sodass Sie Änderungen an der Konfiguration wie coverage und reporters vornehmen können. Eine bemerkenswerte Änderung ist, dass Sie die globale Konfiguration von einem Testprojekt aus manipulieren können, sofern Ihr Plugin im Projekt und nicht in der globalen Konfiguration definiert ist.

Kontext

project

Das aktuelle Testprojekt, zu dem das Plugin gehört.

Browser-Modus

Beachten Sie, dass das Feld project.browser noch nicht gesetzt ist, wenn Sie sich auf eine Browserfunktion verlassen. Verwenden Sie stattdessen das Ereignis reporter.onBrowserInit.

vitest

Die globale Vitest-Instanz. Sie können die globale Konfiguration ändern, indem Sie die Eigenschaft vitest.config direkt modifizieren:

vitest.config.coverage.enabled = false;
vitest.config.reporters.push([['my-reporter', {}]]);

Konfiguration ist aufgelöst

Beachten Sie, dass Vitest die Konfiguration bereits aufgelöst hat, weshalb einige Typen möglicherweise von der üblichen Nutzerkonfiguration abweichen. Dies bedeutet auch, dass einige Eigenschaften, wie z. B. setupFile, nicht erneut aufgelöst werden. Wenn Sie neue Dateien hinzufügen, stellen Sie sicher, diese zuerst aufzulösen.

Zu diesem Zeitpunkt sind Reporter noch nicht initialisiert, daher hat das Ändern von vitest.reporters keine Auswirkung, da diese überschrieben werden. Wenn Sie stattdessen Ihren eigenen Reporter hinzufügen müssen, ändern Sie die Konfiguration.

injectTestProjects

function injectTestProjects(
  config: TestProjectConfiguration | TestProjectConfiguration[]
): Promise<TestProject[]>;

Diese Methode akzeptiert ein Konfigurations-Glob-Muster, einen Dateipfad zur Konfiguration oder eine Inline-Konfiguration. Sie gibt ein Array aufgelöster Testprojekte zurück.

// fügt ein einzelnes Projekt mit einem benutzerdefinierten Alias hinzu
const newProjects = await injectTestProjects({
  // Sie können die aktuelle Projektkonfiguration erben, indem Sie auf `extends` verweisen
  // Beachten Sie, dass kein Projekt mit einem bereits vorhandenen Namen existieren darf;
  // daher empfiehlt es sich, einen benutzerdefinierten Namen zu wählen
  extends: project.vite.config.configFile,
  test: {
    name: 'my-custom-alias',
    alias: {
      customAlias: resolve('./custom-path.js'),
    },
  },
});

Projekte werden gefiltert

Vitest filtert Projekte während der Konfigurationsauflösung. Wenn der Nutzer einen Filter definiert hat, wird das injizierte Projekt möglicherweise nur dann aufgelöst, wenn es dem Filter entspricht. Sie können den Filter über die Option vitest.config.project anpassen, um Ihr Testprojekt immer einzuschließen:

vitest.config.project.push('my-project-name');

Beachten Sie, dass dies nur Projekte betrifft, die mit der Methode injectTestProjects injiziert wurden.

Referenzierung der aktuellen Konfiguration

Wenn Sie die Nutzerkonfiguration beibehalten möchten, können Sie die Eigenschaft extends verwenden. Alle anderen Eigenschaften werden mit der vom Nutzer definierten Konfiguration zusammengeführt.

Die configFile des Projekts kann über die Vite-Konfiguration abgerufen werden: project.vite.config.configFile.

Beachten Sie, dass dies auch den Namen übernimmt. Da Vitest keine mehreren Projekte mit demselben Namen erlaubt, führt dies zu einem Fehler. Stellen Sie sicher, dass Sie einen anderen Namen angegeben haben. Sie können den aktuellen Namen über die Eigenschaft project.name abrufen, und alle verwendeten Namen sind im Array vitest.projects verfügbar.