Test Runner

WARNING

To jest zaawansowane API. Jeśli po prostu uruchamiasz testy, prawdopodobnie nie będziesz go potrzebować. Jest ono używane głównie przez twórców bibliotek.

Możesz określić ścieżkę do swojego runnera testów za pomocą opcji runner w pliku konfiguracyjnym. Ten plik powinien eksportować domyślnie klasę implementującą następujące metody:

export interface VitestRunner {
  /**
   * Pierwsza metoda wywoływana przed zebraniem i uruchomieniem testów.
   */
  onBeforeCollect?: (paths: string[]) => unknown;
  /**
   * Wywoływana po zebraniu testów i przed "onBeforeRun".
   */
  onCollected?: (files: File[]) => unknown;

  /**
   * Wywoływana, gdy runner testów powinien anulować dalsze uruchamianie testów.
   * Runner powinien nasłuchiwać tej metody i oznaczać testy oraz pakiety testów (suite) jako pominięte w
   * "onBeforeRunSuite" i "onBeforeRunTask", gdy ta metoda zostanie wywołana.
   */
  onCancel?: (reason: CancelReason) => unknown;

  /**
   * Wywoływana przed uruchomieniem pojedynczego testu. Nie ma jeszcze wyniku (result).
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Wywoływana przed faktycznym uruchomieniem funkcji testowej. Dostępny jest już wynik (result), stan (state) i czas rozpoczęcia (startTime).
   */
  onBeforeTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;
  /**
   * Wywoływana po ustawieniu wyniku (result) i stanu (state).
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Wywoływana zaraz po uruchomieniu funkcji testowej. Nowy stan (state) nie jest jeszcze dostępny. Nie zostanie wywołana, jeśli funkcja testowa zgłosi wyjątek.
   */
  onAfterTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;

  /**
   * Wywoływana przed uruchomieniem pojedynczego pakietu testów (suite). Nie ma jeszcze wyniku (result).
   */
  onBeforeRunSuite?: (suite: Suite) => unknown;
  /**
   * Wywoływana po uruchomieniu pojedynczego pakietu testów (suite). Dostępny jest stan (state) i wynik (result).
   */
  onAfterRunSuite?: (suite: Suite) => unknown;

  /**
   * Jeśli zdefiniowano, zostanie wywołana zamiast standardowego partycjonowania i obsługi pakietów testów (suite) przez Vitest.
   * Hooki "before" i "after" nie zostaną zignorowane.
   */
  runSuite?: (suite: Suite) => Promise<void>;
  /**
   * Przydatne, jeśli masz własną funkcję testową.
   * Hooki "before" i "after" nie zostaną zignorowane.
   */
  runTask?: (test: TaskPopulated) => Promise<void>;

  /**
   * Działa tak samo jak "onTaskUpdate" w reporterze, ale w tym samym wątku co testy.
   */
  onTaskUpdate?: (task: [string, TaskResult | undefined][]) => Promise<void>;

  /**
   * Wywoływana przed uruchomieniem wszystkich testów w zebranych ścieżkach.
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * Wywoływana zaraz po uruchomieniu wszystkich testów w zebranych ścieżkach.
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * Wywoływana, gdy zdefiniowany jest nowy kontekst dla testu. Przydatne, jeśli chcesz dodać niestandardowe właściwości do kontekstu.
   * Jeśli chcesz tylko zdefiniować niestandardowy kontekst za pomocą runnera, rozważ użycie "beforeAll" w "setupFiles" zamiast tego.
   *
   * Ta metoda jest wywoływana zarówno dla obsługi "test" jak i "custom".
   *
   * @see https://www.getbook.com/pl/book/vitest-1/advanced/runner#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(
    context: TaskContext<T>
  ) => TaskContext<T>;
  /**
   * Może być wywołane w dwóch sytuacjach: podczas zbierania testów i importowania plików setup.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
  /**
   * Publicznie dostępna konfiguracja.
   */
  config: VitestRunnerConfig;
}

Podczas inicjalizacji tej klasy, Vitest przekazuje konfigurację Vitest - powinieneś ją udostępnić jako właściwość config.

WARNING

Vitest wstrzykuje również instancję ViteNodeRunner jako właściwość __vitest_executor. Możesz jej użyć do przetwarzania plików w metodzie importFile (to jest domyślne zachowanie TestRunner i BenchmarkRunner).

ViteNodeRunner udostępnia metodę executeId, która jest używana do importowania plików testowych w środowisku przyjaznym dla Vite. Oznacza to, że będzie rozwiązywać importy i przekształcać zawartość pliku w czasie wykonywania, aby Node mógł ją zrozumieć.

TIP

Obsługa snapshotów i niektóre inne funkcje zależą od runnera. Jeśli nie chcesz ich stracić, możesz rozszerzyć swój runner z VitestTestRunner importowanego z vitest/runners. Dostępny jest również BenchmarkNodeRunner, jeśli chcesz rozszerzyć funkcjonalność benchmarków.

Własne zadania (task)

Możesz rozszerzyć system zadań Vitest o własne zadania. Zadanie to obiekt, który jest częścią pakietu testów (suite). Jest automatycznie dodawany do bieżącego pakietu testów za pomocą metody suite.task:

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

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

// ta funkcja zostanie wywołana w fazie zbierania:
// nie wywołuj tutaj obsługi funkcji, dodaj ją do zadań zestawu
// za pomocą metody "getCurrentSuite().task()"
// uwaga: createTaskCollector zapewnia obsługę "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

Jeśli nie masz niestandardowego runnera lub nie zdefiniowałeś metody runTest, Vitest spróbuje automatycznie pobrać zadanie. Jeśli nie dodano funkcji za pomocą setFn, operacja się nie powiedzie.

TIP

Niestandardowy system zadań obsługuje hooki i konteksty. Aby obsługiwać łańcuchowanie właściwości (takich jak only, skip i własne), możesz zaimportować createChainable z vitest/suite i opakować nią swoją funkcję. W takim przypadku wywołaj custom jako custom.call(this).