Pool personnalisé

WARNING

Il s'agit d'une API avancée et de très bas niveau. Si votre objectif est simplement d'exécuter des tests, vous n'en avez probablement pas besoin. Elle est principalement destinée aux auteurs de bibliothèques.

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

• threads pour exécuter les tests en utilisant node:worker_threads (l'isolation est fournie par un nouveau contexte de worker)
• forks pour exécuter les tests en utilisant node:child_process (l'isolation est fournie par un nouveau processus child_process.fork)
• vmThreads pour exécuter les tests en utilisant node:worker_threads (mais l'isolation est assurée par le module vm plutôt que par un nouveau contexte de worker)
• browser pour exécuter les tests en utilisant des fournisseurs de navigateur
• typescript pour effectuer la vérification de type des tests

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

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // exécutera par défaut chaque fichier avec un pool personnalisé
    pool: './my-custom-pool.ts',
    // vous pouvez fournir des options en utilisant l'objet `poolOptions`
    poolOptions: {
      myCustomPool: {
        customProperty: true,
      },
    },
  },
});

Si vous avez besoin d'exécuter des tests dans différents pools, utilisez la fonctionnalité projects :

export default defineConfig({
  test: {
    projects: [
      {
        extends: true,
        test: {
          pool: 'threads',
        },
      },
    ],
  },
});

API

Le fichier spécifié dans l'option pool doit exporter une fonction (qui peut être asynchrone) acceptant l'interface Vitest comme premier argument. Cette fonction doit retourner un objet correspondant à l'interface ProcessPool :

import type { ProcessPool, TestSpecification } from 'vitest/node';

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

La fonction est appelée une seule fois (sauf si la configuration du serveur a été modifiée). Il est généralement recommandé d'initialiser tout ce dont vous avez besoin pour les tests à l'intérieur de cette fonction et de le réutiliser lorsque runTests est appelé.

Vitest appelle runTests lorsque de nouveaux tests sont planifiés. Cette fonction ne sera pas appelée si files est vide. Le premier argument est un tableau de TestSpecifications. Les fichiers sont triés en utilisant sequencer avant l'appel de runTests. Il est possible (mais peu probable) que le même fichier apparaisse deux fois, mais il appartiendra toujours à un projet différent – ceci est mis en œuvre via la configuration projects.

Vitest attendra l'exécution de runTests avant de finaliser une exécution (c'est-à-dire qu'il n'émettra onFinished qu'une fois runTests résolu).

Si vous utilisez un pool personnalisé, vous devrez fournir les fichiers de test et leurs résultats vous-même – vous pouvez consulter vitest.state pour cela (les fonctions les plus importantes étant collectFiles et updateTasks). Vitest utilise la fonction startTests du package @vitest/runner pour ce faire.

Vitest appellera collectTests si vitest.collect est appelé ou si vitest list est invoqué via une commande CLI. Son fonctionnement est similaire à runTests, mais vous n'avez pas à exécuter les callbacks de test ; il suffit de rapporter leurs tâches en appelant vitest.state.collectFiles(files).

Pour communiquer entre différents processus, vous pouvez créer un objet de méthodes en utilisant createMethodsRPC de vitest/node, et utiliser la forme 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 { createMethodsRPC, TestProject } from 'vitest/node';

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

Vous pouvez voir un exemple simple de pool implémenté à partir de zéro qui n'exécute pas de tests mais les marque comme collectés dans pool/custom-pool.ts.