Ejecutor de Pruebas (Test Runner)

WARNING

Esta es una API avanzada. Si solo estás ejecutando pruebas, probablemente no necesites esto. Se utiliza principalmente por autores de bibliotecas.

Puedes especificar la ruta a tu ejecutor de pruebas con la opción runner en tu archivo de configuración. Este archivo debe tener una exportación por defecto con una clase que implemente los siguientes métodos:

export interface VitestRunner {
  /**
   * Se invoca primero, antes de recopilar y ejecutar las pruebas.
   */
  onBeforeCollect?(paths: string[]): unknown;
  /**
   * Se llama después de recopilar las pruebas y antes de "onBeforeRun".
   */
  onCollected?(files: File[]): unknown;

  /**
   * Se invoca cuando el ejecutor de pruebas debe cancelar las próximas ejecuciones.
   * El ejecutor debe estar atento a este método y marcar las pruebas y suites como omitidas en
   * "onBeforeRunSuite" y "onBeforeRunTest" cuando se le llama.
   */
  onCancel?(reason: CancelReason): unknown;

  /**
   * Se invoca antes de ejecutar una prueba individual. Aún no tiene un "resultado".
   */
  onBeforeRunTest?(test: Test): unknown;
  /**
   * Se invoca antes de ejecutar la función de prueba propiamente dicha. Ya tiene un "resultado" con "estado" y "horaDeInicio".
   */
  onBeforeTryTest?(test: Test, retryCount: number): unknown;
  /**
   * Se llama después de establecer el resultado y el estado.
   */
  onAfterRunTest?(test: Test): unknown;
  /**
   * Se invoca inmediatamente después de ejecutar la función de prueba. Aún no tiene un estado actualizado. No se llamará si la función de prueba lanza un error.
   */
  onAfterTryTest?(test: Test, retryCount: number): unknown;

  /**
   * Se llama antes de ejecutar una sola suite. Aún no tiene "result".
   */
  onBeforeRunSuite?(suite: Suite): unknown;
  /**
   * Se llama después de ejecutar una sola suite. Tiene estado y resultado.
   */
  onAfterRunSuite?(suite: Suite): unknown;

  /**
   * Si se define, se llamará en lugar de la partición y el manejo habituales de la suite de Vitest.
   * Los hooks 'before' y 'after' no se ignorarán.
   */
  runSuite?(suite: Suite): Promise<void>;
  /**
   * Si se define, se llamará en lugar del manejo habitual de Vitest. Útil si tienes tu propia función de prueba personalizada.
   * Los hooks 'before' y 'after' no se ignorarán.
   */
  runTest?(test: Test): Promise<void>;

  /**
   * Se llama cuando se actualiza una tarea. Es lo mismo que "onTaskUpdate" en un reportero, pero esto se ejecuta en el mismo hilo que las pruebas.
   */
  onTaskUpdate?(task: [string, TaskResult | undefined][]): Promise<void>;

  /**
   * Se llama antes de ejecutar todas las pruebas en las rutas recopiladas.
   */
  onBeforeRun?(files: File[]): unknown;
  /**
   * Se llama justo después de ejecutar todas las pruebas en las rutas recopiladas.
   */
  onAfterRun?(files: File[]): unknown;
  /**
   * Se invoca cuando se define un nuevo contexto para una prueba. Útil si deseas añadir propiedades personalizadas al contexto.
   * Si solo deseas definir un contexto personalizado con un ejecutor, considera usar 'beforeAll' en 'setupFiles' en su lugar.
   */
  extendTestContext?(context: TestContext): TestContext;
  /**
   * Se invoca cuando se importan ciertos archivos. Se puede llamar en dos situaciones: al recopilar pruebas y al importar archivos de configuración.
   */
  importFile(filepath: string, source: VitestRunnerImportSource): unknown;
  /**
   * Configuración de acceso público.
   */
  config: VitestRunnerConfig;
}

Al instanciar esta clase, Vitest pasa su configuración, la cual debes exponer como una propiedad config.

WARNING

Vitest también inyecta una instancia de ViteNodeRunner como propiedad __vitest_executor. Puedes usarla para procesar archivos en el método importFile (este es el comportamiento predeterminado de TestRunner y BenchmarkRunner).

ViteNodeRunner expone el método executeId, que se utiliza para importar archivos de prueba en un entorno compatible con Vite. Es decir, resolverá las importaciones y transformará el contenido del archivo en tiempo real para que Node pueda interpretarlo.

TIP

Para no perder esta funcionalidad, puedes extender tu ejecutor a partir de VitestTestRunner, que se importa desde vitest/runners. También expone BenchmarkNodeRunner, si quieres extender la funcionalidad de benchmark.

Tu función de tarea

Puedes extender el sistema de tareas de Vitest con tus propias tareas. Una tarea es un objeto que forma parte de una suite. Se añade automáticamente a la suite actual mediante el método suite.custom:

// ./utils/custom.js
import { getCurrentSuite, setFn } from 'vitest/suite';

export { describe, beforeAll, afterAll } from 'vitest';

// Esta función se llamará cuando Vitest recopile tareas
export const myCustomTask = function (name, fn) {
  const task = getCurrentSuite().custom(name);
  task.meta = {
    customPropertyToDifferentiateTask: true,
  };
  setFn(task, fn || (() => {}));
};

// ./garden/tasks.test.js
import {
  afterAll,
  beforeAll,
  describe,
  myCustomTask,
} from '../utils/custom.js';
import { gardener } from './gardener.js';

describe('take care of the garden', () => {
  beforeAll(() => {
    gardener.putWorkingClothes();
  });

  myCustomTask('weed the grass', () => {
    gardener.weedTheGrass();
  });
  myCustomTask('water flowers', () => {
    gardener.waterFlowers();
  });

  afterAll(() => {
    gardener.goHome();
  });
});

vitest ./garden/tasks.test.js

WARNING

Si no tienes un ejecutor personalizado o no has definido el método runTest, Vitest intentará recuperar una tarea automáticamente. Si no has añadido una función usando setFn, la ejecución fallará.

TIP

El sistema de tareas personalizadas admite hooks y contextos. Si deseas habilitar el encadenamiento de propiedades (como only, skip y las que definas), puedes importar createChainable desde vitest/suite y aplicarlo a tu función. Si optas por esta opción, deberás invocar custom utilizando custom.call(this) si decides hacerlo.