Pool personnalisé

WARNING

Ceci est une API avancée. Si vous exécutez simplement des tests, vous n'en aurez probablement pas besoin. Elle est principalement destinée aux développeurs de bibliothèques.

Vitest exécute les tests dans des pools. Par défaut, plusieurs pools sont disponibles :

• threads pour exécuter les tests à l'aide de node:worker_threads (isolation assurée par un nouveau contexte de worker)
• forks pour exécuter les tests à l'aide de node:child_process (isolation assurée par un nouveau processus child_process.fork)
• vmThreads pour exécuter les tests à l'aide de node:worker_threads (isolation assurée par le module vm au lieu d'un nouveau contexte de worker)
• browser pour exécuter les tests à l'aide de navigateurs
• typescript pour effectuer une vérification de type sur les tests.

Vous pouvez fournir votre propre pool en spécifiant un chemin de fichier :

import { defineConfig } from 'vitest/config';
// ---cut---
export default defineConfig({
  test: {
    // exécutera chaque fichier avec un pool personnalisé par défaut
    pool: './my-custom-pool.ts',
    // vous pouvez fournir des options en utilisant l'objet `poolOptions`
    poolOptions: {
      myCustomPool: {
        customProperty: true,
      },
    },
    // vous pouvez également spécifier un pool pour un sous-ensemble de fichiers
    poolMatchGlobs: [['**/*.custom.test.ts', './my-custom-pool.ts']],
  },
});

API

Le fichier spécifié dans l'option pool doit exporter une fonction (éventuellement asynchrone) qui accepte l'interface Vitest comme premier argument. Cette fonction doit renvoyer un objet conforme à l'interface ProcessPool :

import { ProcessPool, WorkspaceProject } from 'vitest/node';

export interface ProcessPool {
  name: string;
  runTests: (
    files: [project: WorkspaceProject, testFile: string][],
    invalidates?: string[]
  ) => Promise<void>;
  close?: () => Promise<void>;
}

La fonction est appelée une seule fois (sauf si la configuration du serveur a été mise à jour). Il est généralement conseillé d'initialiser tout ce dont vous avez besoin pour les tests dans cette fonction et de le réutiliser lors des appels à runTests.

Vitest appelle runTests lorsque de nouveaux tests sont planifiés. Il ne l'appellera pas si files est vide. Le premier argument est un tableau de couples : le premier élément est une référence à un projet d'espace de travail et le second est un chemin absolu vers un fichier de test. Les fichiers sont ordonnés à l'aide de sequencer avant l'appel à runTests. Il est rare de retrouver le même fichier en double, mais il aura toujours un projet différent. Ceci est géré par la configuration vitest.workspace.ts.

Vitest attend que runTests se termine avant de terminer une exécution, et n'émettra onFinished qu'une fois runTests terminé.

Si vous utilisez un pool personnalisé, vous devrez fournir les fichiers de test et leurs résultats. Vous pouvez vous référer à vitest.state pour cela (les plus importants étant collectFiles et updateTasks). Vitest utilise la fonction startTests du package @vitest/runner pour ce faire.

Pour communiquer entre différents processus, vous pouvez créer un objet de méthodes en utilisant createMethodsRPC de vitest/node, et utiliser la méthode de communication de votre choix. Par exemple, pour utiliser WebSockets avec birpc, vous pouvez écrire quelque chose comme ceci :

import { createBirpc } from 'birpc';
import { parse, stringify } from 'flatted';
import { WorkspaceProject, createMethodsRPC } from 'vitest/node';

function createRpc(project: WorkspaceProject, wss: WebSocketServer) {
  return createBirpc(createMethodsRPC(project), {
    post: msg => wss.send(msg),
    on: fn => wss.on('message', fn),
    serialize: stringify,
    deserialize: parse,
  });
}

Pour vous assurer que chaque test est collecté, vous devez appeler ctx.state.collectFiles et en informer les reporters Vitest :

async function runTests(project: WorkspaceProject, tests: string[]) {
  // ... exécution des tests, placés dans "files" et "tasks"
  const methods = createMethodsRPC(project);
  await methods.onCollected(files);
  // la plupart des reporters dépendent de la mise à jour des résultats dans "onTaskUpdate"
  await methods.onTaskUpdate(tasks);
}

Un exemple simple est disponible dans pool/custom-pool.ts.