API des plugins 3.1.0+

WARNING

C'est une API avancée. Si vous souhaitez simplement exécuter des tests, vous n'en avez probablement pas besoin. Elle est principalement utilisée par les auteurs de bibliothèques.

Ce guide suppose que vous savez comment travailler avec les plugins Vite.

Vitest prend en charge un hook de plugin expérimental configureVitest depuis la version 3.1. Tout commentaire concernant cette API est bienvenu sur GitHub.

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 réexporte toutes les importations de types Vite via un espace de noms Vite, que vous pouvez utiliser pour maintenir vos versions synchronisées. Cependant, si vous écrivez un plugin pour Vite et Vitest, vous pouvez continuer à utiliser le type Plugin du point d'entrée vite. Assurez-vous simplement que vitest/config est référencé quelque part afin que configureVitest soit correctement augmenté :

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

Contrairement à reporter.onInit, ce hook s'exécute tôt dans le cycle de vie de Vitest, permettant d'apporter des modifications à la configuration comme coverage et reporters. Un aspect particulièrement notable est que vous pouvez manipuler la configuration globale à partir d'un projet de test si votre plugin est défini dans ce projet et non dans la configuration globale.

Contexte

project

C'est le projet de test actuel auquel le plugin appartient.

Mode Navigateur

Notez que si vous dépendez d'une fonctionnalité de navigateur, le champ project.browser n'est pas encore défini. Utilisez plutôt l'événement reporter.onBrowserInit.

vitest

C'est l'instance globale de Vitest. Vous pouvez modifier la configuration globale en modifiant directement la propriété vitest.config :

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

La configuration est résolue

Notez que Vitest a déjà résolu la configuration, ce qui signifie que certains types peuvent différer de la configuration utilisateur habituelle. Cela signifie également que certaines propriétés ne seront pas résolues à nouveau, comme setupFiles. Si vous ajoutez de nouveaux fichiers, assurez-vous de les résoudre d'abord.

À ce stade, les rapporteurs ne sont pas encore créés, donc la modification de vitest.reporters n'aura aucun effet car elle sera écrasée. Si vous devez injecter votre propre rapporteur, préférez modifier la configuration.

injectTestProjects

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

Cette méthode accepte un modèle de glob de configuration, un chemin de fichier vers la configuration ou une configuration en ligne. Elle renvoie un tableau de projets de test résolus.

// injecte un seul projet avec un alias personnalisé
const newProjects = await injectTestProjects({
  // vous pouvez hériter de la configuration du projet actuel en référençant `extends`
  // notez que vous ne pouvez pas avoir un projet avec un nom qui existe déjà,
  // il est donc préférable de définir un nom personnalisé
  extends: project.vite.config.configFile,
  test: {
    name: 'my-custom-alias',
    alias: {
      customAlias: resolve('./custom-path.js'),
    },
  },
});

Les projets sont filtrés

Vitest filtre les projets pendant la résolution de la configuration. Par conséquent, si l'utilisateur a défini un filtre, le projet injecté pourrait ne pas être résolu à moins qu'il ne corresponde au filtre. Vous pouvez mettre à jour le filtre via l'option vitest.config.project pour toujours inclure votre projet de test :

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

Notez que cela n'affectera que les projets injectés avec la méthode injectTestProjects.

Référencer la configuration actuelle

Si vous souhaitez conserver la configuration utilisateur, vous pouvez spécifier la propriété extends. Toutes les autres propriétés seront fusionnées avec la configuration définie par l'utilisateur.

Le configFile du projet est accessible dans la configuration de Vite : project.vite.config.configFile.

Notez que cela héritera également du name - Vitest n'autorise pas plusieurs projets avec le même nom, ce qui entraînera une erreur. Assurez-vous de spécifier un nom différent. Vous pouvez accéder au nom actuel via la propriété project.name et tous les noms utilisés sont disponibles dans le tableau vitest.projects.