Runner API

WARNING

Toto je pokročilé API. Pokud chcete pouze spouštět testy, pravděpodobně ho nepotřebujete. Používají ho primárně autoři knihoven.

Cestu k vašemu testovacímu runneru můžete specifikovat pomocí volby runner ve vašem konfiguračním souboru. Tento soubor by měl mít výchozí export s konstruktorem třídy implementujícím tyto metody:

export interface VitestRunner {
  /**
   * První volaná metoda před samotným shromažďováním a spouštěním testů.
   */
  onBeforeCollect?: (paths: string[]) => unknown;
  /**
   * Voláno po shromáždění testů a před "onBeforeRun".
   */
  onCollected?: (files: File[]) => unknown;

  /**
   * Voláno, když má testovací runner zrušit další spuštění testů.
   * Runner by měl naslouchat této metodě a po jejím zavolání označit testy a sady jako přeskočené v
   * "onBeforeRunSuite" a "onBeforeRunTask".
   */
  onCancel?: (reason: CancelReason) => unknown;

  /**
   * Voláno před spuštěním jednoho testu. Výsledek (result) ještě není k dispozici.
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Voláno před samotným spuštěním testovací funkce. Pole "result" již obsahuje "state" a "startTime".
   */
  onBeforeTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;
  /**
   * Voláno poté, co jsou nastaveny výsledek a stav.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Voláno hned po spuštění testovací funkce. Ještě nemá nový stav. V případě, že testovací funkce vyvolá chybu, nebude tato metoda volána.
   */
  onAfterTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;

  /**
   * Voláno před spuštěním jedné sady. Výsledek (result) ještě není k dispozici.
   */
  onBeforeRunSuite?: (suite: Suite) => unknown;
  /**
   * Voláno po spuštění jedné sady. Má stav a výsledek.
   */
  onAfterRunSuite?: (suite: Suite) => unknown;

  /**
   * Pokud je definováno, bude voláno namísto standardního zpracování a správy sady Vitest.
   * Hooky "before" a "after" nebudou ignorovány.
   */
  runSuite?: (suite: Suite) => Promise<void>;
  /**
   * Pokud je definováno, bude voláno namísto standardního zpracování Vitest. Užitečné, pokud máte vlastní testovací funkci.
   * Hooky "before" a "after" nebudou ignorovány.
   */
  runTask?: (test: TaskPopulated) => Promise<void>;

  /**
   * Voláno při aktualizaci úkolu. Stejné jako "onTaskUpdate" v reportéru, avšak tato metoda běží ve stejném vlákně jako testy.
   */
  onTaskUpdate?: (
    task: [string, TaskResult | undefined, TaskMeta | undefined][]
  ) => Promise<void>;

  /**
   * Voláno před spuštěním všech testů v shromážděných cestách.
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * Voláno hned po spuštění všech testů v shromážděných cestách.
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * Voláno, když je definován nový kontext pro test. Užitečné, pokud chcete přidat vlastní vlastnosti do kontextu.
   * Pokud chcete definovat vlastní kontext pouze s runnerem, zvažte místo toho použití "beforeAll" v "setupFiles".
   */
  extendTaskContext?: (context: TestContext) => TestContext;
  /**
   * Voláno, když jsou importovány určité soubory. Může být voláno ve dvou situacích: pro shromažďování testů a pro import souborů nastavení.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
  /**
   * Funkce volaná, když se runner pokusí získat hodnotu v případě, že je `test.extend` použit s `{ injected: true }`.
   */
  injectValue?: (key: string) => unknown;
  /**
   * Veřejně dostupná konfigurace.
   */
  config: VitestRunnerConfig;
  /**
   * Název aktuálního poolu. Může ovlivnit, jak je na straně serveru odvozena stack trace.
   */
  pool?: string;
}

Při inicializaci této třídy Vitest předává svou konfiguraci – tu byste měli vystavit jako vlastnost config:

import type { RunnerTestFile } from 'vitest';
import type { VitestRunner, VitestRunnerConfig } from 'vitest/suite';
import { VitestTestRunner } from 'vitest/runners';

class CustomRunner extends VitestTestRunner implements VitestRunner {
  public config: VitestRunnerConfig;

  constructor(config: VitestRunnerConfig) {
    this.config = config;
  }

  onAfterRunFiles(files: RunnerTestFile[]) {
    console.log('finished running', files);
  }
}

export default CustomRunner;

WARNING

Vitest také injektuje instanci ViteNodeRunner jako vlastnost __vitest_executor. Můžete ji použít ke zpracování souborů v metodě importFile (toto je výchozí chování TestRunner a BenchmarkRunner).

ViteNodeRunner vystavuje metodu executeId, která se používá k importu testovacích souborů v prostředí přátelském k Vite. To znamená, že za běhu vyřeší importy a transformuje obsah souboru tak, aby mu Node rozuměl:

export default class Runner {
  async importFile(filepath: string) {
    await this.__vitest_executor.executeId(filepath);
  }
}

WARNING

Pokud nemáte vlastní runner nebo jste nedefinovali metodu runTask, Vitest se pokusí úkol automaticky získat. Pokud jste nepřidali funkci s setFn, selže.

TIP

Podpora snapshotů a některé další funkce závisí na runneru. Pokud je nechcete ztratit, můžete svůj runner rozšířit z VitestTestRunner importovaného z vitest/runners. Také vystavuje BenchmarkNodeRunner, pokud chcete rozšířit funkčnost benchmarků.

Úkoly

WARNING

„Runner Tasks API“ je experimentální a mělo by se primárně používat pouze v testovacím runtime. Vitest také vystavuje „Reported Tasks API“ (./api/test-module), které by mělo být preferováno při práci v hlavním vlákně (například uvnitř reportéru).

Tým v současné době diskutuje, zda by „Runner Tasks“ měly být v budoucnu nahrazeny „Reported Tasks“.

Sady a testy se interně nazývají tasks. Vitest runner inicializuje úkol File před shromažďováním jakýchkoli testů – jedná se o nadmnožinu Suite s několika dalšími vlastnostmi. Je k dispozici u každého úkolu (včetně File) jako vlastnost file.

interface File extends Suite {
  /**
   * Název poolu, do kterého soubor patří.
   * @default 'forks'
   */
  pool?: string;
  /**
   * Cesta k souboru ve formátu UNIX.
   */
  filepath: string;
  /**
   * Název testovacího projektu, do kterého soubor patří.
   */
  projectName: string | undefined;
  /**
   * Doba shromažďování všech testů v souboru.
   * Tato doba zahrnuje také import všech závislostí souboru.
   */
  collectDuration?: number;
  /**
   * Doba importu souboru nastavení.
   */
  setupDuration?: number;
}

Každá sada má vlastnost tasks, která je naplněna během fáze shromažďování. Je užitečné procházet strom úkolů shora dolů.

interface Suite extends TaskBase {
  type: 'suite';
  /**
   * Úkol typu File. Jedná se o kořenový úkol souboru.
   */
  file: File;
  /**
   * Pole úkolů, které jsou součástí sady.
   */
  tasks: Task[];
}

Každý úkol má vlastnost suite, která odkazuje na sadu, ve které se nachází. Pokud jsou test nebo describe inicializovány na nejvyšší úrovni, nebudou mít vlastnost suite (nebude se rovnat file!). File také nikdy nemá vlastnost suite. Je užitečné procházet úkoly zdola nahoru.

interface Test<ExtraContext = object> extends TaskBase {
  type: 'test';
  /**
   * Testovací kontext, který bude předán testovací funkci.
   */
  context: TestContext & ExtraContext;
  /**
   * Úkol typu File. Jedná se o kořenový úkol souboru.
   */
  file: File;
  /**
   * Zda byl úkol přeskočen voláním `context.skip()`.
   */
  pending?: boolean;
  /**
   * Určuje, zda má úkol uspět, i když selže. Pokud úkol selže, bude označen jako úspěšný.
   */
  fails?: boolean;
  /**
   * Pole pro ukládání slibů (z asynchronních očekávání), na které se čeká před dokončením testu.
   */
  promises?: Promise<any>[];
}

Každý úkol může mít pole result. Sady mohou mít toto pole pouze v případě, že chyba vyvolaná v callbacku sady nebo v callbackech beforeAll/afterAll zabrání shromažďování testů. Testy mají toto pole vždy po volání svých callbacků – pole state a errors jsou přítomna v závislosti na výsledku. Pokud byla chyba vyvolána v callbackech beforeEach nebo afterEach, vyvolaná chyba bude přítomna v task.result.errors.

export interface TaskResult {
  /**
   * Stav úkolu. Dědí `task.mode` během shromažďování.
   * Po dokončení úkolu se změní na `pass` nebo `fail`.
   * - **pass**: úkol proběhl úspěšně
   * - **fail**: úkol selhal
   */
  state: TaskState;
  /**
   * Chyby, které nastaly během provádění úkolu. Může se vyskytnout několik chyb,
   * například pokud `expect.soft()` selhalo vícekrát.
   */
  errors?: ErrorWithDiff[];
  /**
   * Doba běhu úkolu v milisekundách.
   */
  duration?: number;
  /**
   * Čas v milisekundách, kdy se úkol začal spouštět.
   */
  startTime?: number;
  /**
   * Velikost haldy v bajtech po dokončení úkolu.
   * K dispozici pouze, pokud je nastavena volba `logHeapUsage` a je definováno `process.memoryUsage`.
   */
  heap?: number;
  /**
   * Stav háčků souvisejících s úkolem. Užitečné pro reportování.
   */
  hooks?: Partial<
    Record<'afterAll' | 'beforeAll' | 'beforeEach' | 'afterEach', TaskState>
  >;
  /**
   * Počet opakování úkolu. Úkol se opakuje pouze v případě, že
   * selhal a je nastavena volba `retry`.
   */
  retryCount?: number;
  /**
   * Počet opakování úkolu. Úkol se opakuje pouze v případě, že
   * je nastavena volba `repeats`. Toto číslo také obsahuje `retryCount`.
   */
  repeatCount?: number;
}

Vaše funkce úkolu

Vitest vystavuje utilitu createTaskCollector pro vytvoření vlastní metody test. Chová se stejně jako test, ale během shromažďování volá vlastní metodu.

Úkol je objekt, který je součástí sady. Je automaticky přidán do aktuální sady metodou suite.task:

import { createTaskCollector, getCurrentSuite } from 'vitest/suite';

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

// tato funkce bude volána během fáze shromažďování:
// obslužnou funkci zde nevolejte, přidejte ji k úkolům sady
// pomocí metody "getCurrentSuite().task()"
// poznámka: createTaskCollector poskytuje podporu pro "todo"/"each"/...
export const myCustomTask = createTaskCollector(function (name, fn, timeout) {
  getCurrentSuite().task(name, {
    ...this, // aby "todo"/"skip"/... bylo správně sledováno
    meta: {
      customPropertyToDifferentiateTask: true,
    },
    handler: fn,
    timeout,
  });
});

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('posekat trávník', () => {
    gardener.mowerTheLawn();
  });
  myCustomTask('water flowers', () => {
    gardener.waterFlowers();
  });

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

vitest ./garden/tasks.test.js