Test Runner

WARNING

Questa è un'API avanzata. Se stai solo eseguendo test, probabilmente non ne hai bisogno. È utilizzata principalmente dagli autori di librerie.

Puoi specificare un percorso per il tuo test runner con l'opzione runner nel file di configurazione. Questo file deve esportare una classe con un'esportazione predefinita che implementa questi metodi:

export interface VitestRunner {
  /**
   * Prima operazione eseguita prima di raccogliere ed eseguire i test.
   */
  onBeforeCollect?: (paths: string[]) => unknown;
  /**
   * Chiamato dopo aver raccolto i test e prima di "onBeforeRun".
   */
  onCollected?: (files: File[]) => unknown;

  /**
   * Chiamato quando il test runner deve annullare le successive esecuzioni di test.
   * Il runner dovrebbe intercettare questo metodo e contrassegnare i test e le suite come saltati in
   * "onBeforeRunSuite" e "onBeforeRunTask" quando viene chiamato.
   */
  onCancel?: (reason: CancelReason) => unknown;

  /**
   * Chiamato prima dell'esecuzione di un singolo test. Non ha ancora un 'result'.
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Chiamato prima di eseguire la funzione di test. Ha già "result" con "state" e "startTime".
   */
  onBeforeTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;
  /**
   * Chiamato dopo che result e state sono stati impostati.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Chiamato immediatamente dopo l'esecuzione della funzione di test. Non ha ancora un nuovo 'state'. Non verrà invocato se la funzione di test genera un'eccezione.
   */
  onAfterTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;

  /**
   * Chiamato prima dell'esecuzione di una singola suite. Non ha ancora un 'result'.
   */
  onBeforeRunSuite?: (suite: Suite) => unknown;
  /**
   * Chiamato dopo l'esecuzione di una singola suite. Ha state e result.
   */
  onAfterRunSuite?: (suite: Suite) => unknown;

  /**
   * Se definito, verrà chiamato al posto della consueta partizione e gestione della suite di Vitest.
   * Gli hook 'before' e 'after' non saranno ignorati.
   */
  runSuite?: (suite: Suite) => Promise<void>;
  /**
   * Se definito, verrà chiamato al posto della consueta gestione dei test di Vitest. Utile se hai una funzione di test personalizzata.
   * Gli hook 'before' e 'after' non saranno ignorati.
   */
  runTask?: (test: TaskPopulated) => Promise<void>;

  /**
   * Chiamato quando un task viene aggiornato. Come "onTaskUpdate" in un reporter, ma questo viene eseguito nello stesso thread dei test.
   */
  onTaskUpdate?: (task: [string, TaskResult | undefined][]) => Promise<void>;

  /**
   * Chiamato prima di eseguire tutti i test nei percorsi raccolti.
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * Chiamato immediatamente dopo aver eseguito tutti i test nei percorsi raccolti.
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * Chiamato quando viene definito un nuovo contesto per un test. Utile se si desidera aggiungere proprietà personalizzate al contesto.
   * Se si desidera solo definire un contesto personalizzato con un runner, si consiglia di utilizzare "beforeAll" in "setupFiles".
   *
   * Questo metodo viene chiamato sia per i gestori "test" che per quelli "custom".
   *
   * @see https://www.getbook.com/it/book/vitest-1/advanced/runner#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(
    context: TaskContext<T>
  ) => TaskContext<T>;
  /**
   * Chiamato quando vengono importati determinati file. Può essere chiamato in due situazioni: durante la raccolta dei test e durante l'importazione dei file di setup.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
  /**
   * Configurazione disponibile pubblicamente.
   */
  config: VitestRunnerConfig;
}

Quando si crea un'istanza di questa classe, Vitest passa la configurazione di Vitest; dovresti esporla come proprietà config.

WARNING

Vitest inietta anche un'istanza di ViteNodeRunner nella proprietà __vitest_executor. Puoi utilizzarla per elaborare i file con il metodo importFile (questo è il comportamento predefinito di TestRunner e BenchmarkRunner).

ViteNodeRunner espone il metodo executeId, che viene utilizzato per importare i file di test in un ambiente compatibile con Vite. Ciò significa che risolverà gli import e trasformerà il contenuto dei file in fase di esecuzione, in modo che Node possa interpretarli.

TIP

Il supporto degli snapshot e altre funzionalità dipendono dal runner. Se non vuoi perderlo, puoi estendere il tuo runner a partire da VitestTestRunner, importato da vitest/runners. Espone anche BenchmarkNodeRunner, se desideri estendere le funzionalità di benchmark.

La tua funzione task

Puoi estendere il sistema di task di Vitest con task personalizzati. Un task è un oggetto che fa parte di una suite. Viene automaticamente aggiunto alla suite corrente tramite il metodo suite.task:

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

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

// questa funzione verrà chiamata durante la fase di raccolta:
// non chiamare qui il gestore di funzioni, aggiungilo alle attività della suite
// con il metodo "getCurrentSuite().task()"
// nota: createTaskCollector fornisce supporto per "todo"/"each"/...
export const myCustomTask = createTaskCollector(function (name, fn, timeout) {
  getCurrentSuite().task(name, {
    ...this, // so "todo"/"skip"/... is tracked correctly
    meta: {
      customPropertyToDifferentiateTask: true,
    },
    handler: fn,
    timeout,
  });
});

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

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

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

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

vitest ./garden/tasks.test.js

WARNING

Se non disponi di un runner personalizzato o non hai definito il metodo runTest, Vitest proverà a recuperare automaticamente un task specifico. Se non hai aggiunto una funzione con setFn, l'operazione fallirà.

TIP

Il sistema di task personalizzati supporta hook e contesti. Se desideri supportare il concatenamento delle proprietà (come only, skip e le tue proprietà personalizzate), puoi importare createChainable da vitest/suite e racchiudere la tua funzione con esso. Dovrai chiamare custom come custom.call(this) qualora decidessi di farlo.