Reportéry

WARNING

Toto je pokročilé API. Pokud chcete pouze konfigurovat vestavěné reportéry, přečtěte si průvodce "Reportéři".

Vitest má svůj vlastní životní cyklus spuštění testů. Ty jsou reprezentovány metodami reportéra:

• onInit
• onTestRunStart
  • onTestModuleQueued
  • onTestModuleCollected
  • onTestModuleStart
    • onTestSuiteReady
      • onHookStart(beforeAll)
      • onHookEnd(beforeAll)
        • onTestCaseReady
          • onTestAnnotate 3.2.0+
          • onHookStart(beforeEach)
          • onHookEnd(beforeEach)
          • onHookStart(afterEach)
          • onHookEnd(afterEach)
        • onTestCaseResult
      • onHookStart(afterAll)
      • onHookEnd(afterAll)
    • onTestSuiteResult
  • onTestModuleEnd
• onTestRunEnd

Testy a sady v rámci jednoho modulu budou hlášeny v pořadí, pokud nebyly přeskočeny. Všechny přeskočené testy jsou hlášeny na konci sady/modulu.

Všimněte si, že protože testovací moduly mohou běžet paralelně, Vitest je bude hlásit paralelně.

Tato příručka uvádí všechny podporované metody reportérů. Nezapomeňte však, že místo vytváření vlastního reportéra můžete rozšířit stávající:

import { BaseReporter } from 'vitest/reporters';

export default class CustomReporter extends BaseReporter {
  onTestRunEnd(testModules, errors) {
    console.log(testModules.length, 'tests finished running');
    super.onTestRunEnd(testModules, errors);
  }
}

onInit

function onInit(vitest: Vitest): Awaitable<void>;

Tato metoda se volá, když je Vitest inicializován nebo spuštěn, ale před filtrováním testů.

INFO

Interně je tato metoda volána uvnitř vitest.start, vitest.init nebo vitest.mergeReports. Pokud používáte programové API, ujistěte se, že zavoláte jednu z nich v závislosti na vašich potřebách před voláním vitest.runTestSpecifications, například. Vestavěné CLI vždy spustí metody ve správném pořadí.

Všimněte si, že k instanci vitest můžete také získat přístup z testovacích případů, sad a testovacích modulů prostřednictvím vlastnosti project, ale může být také užitečné uložit odkaz na vitest v této metodě.

Příklad

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

class MyReporter implements Reporter {
  private vitest!: Vitest;

  onInit(vitest: Vitest) {
    this.vitest = vitest;
  }

  onTestRunStart(specifications: TestSpecification[]) {
    console.log(
      specifications.length,
      'test files will run in',
      this.vitest.config.root
    );
  }
}

export default new MyReporter();

onBrowserInit experimentální

function onBrowserInit(project: TestProject): Awaitable<void>;

Tato metoda je volána, když je inicializována instance prohlížeče. Přijímá instanci projektu, pro který je prohlížeč inicializován. project.browser bude vždy definován, když je tato metoda volána.

onTestRunStart

function onTestRunStart(specifications: TestSpecification[]): Awaitable<void>;

Tato metoda se volá, když začíná nové spuštění testů. Přijímá pole specifikací testů naplánovaných ke spuštění. Toto pole je pouze pro čtení a je k dispozici pouze pro informační účely.

Pokud Vitest nenajde žádné testovací soubory ke spuštění, tato událost se vyvolá s prázdným polem a poté se okamžitě zavolá onTestRunEnd.

Příklad

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

class MyReporter implements Reporter {
  onTestRunStart(specifications: TestSpecification[]) {
    console.log(specifications.length, 'test files will run');
  }
}

export default new MyReporter();

OZNÁMENÍ O ZRUŠENÍ

Tato metoda byla přidána ve Vitest 3 a nahrazuje onPathsCollected a onSpecsCollected, které jsou nyní zastaralé.

onTestRunEnd

function onTestRunEnd(
  testModules: ReadonlyArray<TestModule>,
  unhandledErrors: ReadonlyArray<SerializedError>,
  reason: TestRunEndReason
): Awaitable<void>;

Tato metoda je volána poté, co všechny testy dokončily běh a pokrytí sloučilo všechny zprávy, pokud je povoleno. Všimněte si, že informace o pokrytí můžete získat v hooku onCoverage.

Přijímá seznam testovacích modulů pouze pro čtení. Můžete jej iterovat pomocí vlastnosti testModule.children a hlásit stav a případné chyby.

Druhým argumentem je seznam neošetřených chyb pouze pro čtení, které Vitest nedokázal přiřadit žádnému testu. Ty se mohou vyskytnout mimo spuštění testu kvůli chybě v pluginu nebo uvnitř spuštění testu jako vedlejší efekt neočekávané funkce (například timeout, který vyvolal chybu po dokončení testu).

Třetí argument udává, proč bylo spuštění testu dokončeno:

• passed: spuštění testu bylo dokončeno normálně a nejsou žádné chyby
• failed: spuštění testu má alespoň jednu chybu (kvůli syntaktické chybě během sběru nebo skutečné chybě během provádění testu)
• interrupted: test byl přerušen voláním vitest.cancelCurrentRun nebo bylo stisknuto Ctrl+C v terminálu (všimněte si, že v tomto případě je stále možné mít neúspěšné testy)

Pokud Vitest nenašel žádné testovací soubory ke spuštění, tato událost bude vyvolána s prázdnými poli modulů a chyb a stav bude záviset na hodnotě config.passWithNoTests.

Příklad

import type {
  Reporter,
  SerializedError,
  TestModule,
  TestRunEndReason,
  TestSpecification,
} from 'vitest/node';

class MyReporter implements Reporter {
  onTestRunEnd(
    testModules: ReadonlyArray<TestModule>,
    unhandledErrors: ReadonlyArray<SerializedError>,
    reason: TestRunEndReason
  ) {
    if (reason === 'passed') {
      testModules.forEach(module => console.log(module.moduleId, 'succeeded'));
    } else if (reason === 'failed') {
      // note that this will skip possible errors in suites
      // you can get them from testSuite.errors()
      for (const testCase of testModules.children.allTests()) {
        if (testCase.result().state === 'failed') {
          console.log(
            testCase.fullName,
            'in',
            testCase.module.moduleId,
            'failed'
          );
          console.log(testCase.result().errors);
        }
      }
    } else {
      console.log('test run was interrupted, skipping report');
    }
  }
}

export default new MyReporter();

OZNÁMENÍ O ZRUŠENÍ

Tato metoda byla přidána ve Vitest 3 a nahrazuje onFinished, které je nyní zastaralé.

onCoverage

function onCoverage(coverage: unknown): Awaitable<void>;

Tento hook je volán poté, co byly zpracovány výsledky pokrytí. Reportéři poskytovatele pokrytí jsou voláni po tomto hooku. Typy coverage závisí na coverage.provider. Pro výchozí vestavěné poskytovatele Vitestu můžete importovat typy z balíčku istanbul-lib-coverage:

import type { CoverageMap } from 'istanbul-lib-coverage';

declare function onCoverage(coverage: CoverageMap): Awaitable<void>;

Pokud Vitest neprovedl žádné pokrytí, tento hook není volán.

onTestModuleQueued

function onTestModuleQueued(testModule: TestModule): Awaitable<void>;

Tato metoda je volána těsně předtím, než Vitest importuje soubor nastavení a samotný testovací modul. To znamená, že testModule ještě nebude mít žádné children, ale můžete jej začít hlásit jako další test ke spuštění.

onTestModuleCollected

function onTestModuleCollected(testModule: TestModule): Awaitable<void>;

Tato metoda je volána, když byly shromážděny všechny testy uvnitř souboru, což znamená, že kolekce testModule.children je naplněna, ale testy ještě nemají žádné výsledky.

onTestModuleStart

function onTestModuleStart(testModule: TestModule): Awaitable<void>;

Tato metoda je volána hned po onTestModuleCollected, pokud Vitest neběží v režimu sběru (vitest.collect() nebo vitest collect v CLI), v tomto případě nebude volána vůbec, protože nejsou žádné testy ke spuštění.

onTestModuleEnd

function onTestModuleEnd(testModule: TestModule): Awaitable<void>;

Tato metoda je volána, když každý test v modulu dokončil běh. To znamená, že každý test uvnitř testModule.children bude mít test.result(), které se nerovná pending.

onHookStart

function onHookStart(context: ReportedHookContext): Awaitable<void>;

Tato metoda se volá, když začínají některé z těchto hooků:

• beforeAll
• afterAll
• beforeEach
• afterEach

Pokud se spustí beforeAll nebo afterAll, entity bude buď TestSuite nebo TestModule.

Pokud se spustí beforeEach nebo afterEach, entity bude vždy TestCase.

WARNING

Metoda onHookStart nebude volána, pokud se hook nespustil během běhu testu.

onHookEnd

function onHookEnd(context: ReportedHookContext): Awaitable<void>;

Tato metoda se volá, když se dokončily některé z těchto hooků:

• beforeAll
• afterAll
• beforeEach
• afterEach

Pokud se dokončily beforeAll nebo afterAll, entity bude buď TestSuite nebo TestModule.

Pokud se dokončily beforeEach nebo afterEach, entity bude vždy TestCase.

WARNING

Metoda onHookEnd nebude volána, pokud se hook nespustil během běhu testu.

onTestSuiteReady

function onTestSuiteReady(testSuite: TestSuite): Awaitable<void>;

Tato metoda je volána předtím, než sada začne spouštět své testy. Tato metoda je také volána, pokud byla sada přeskočena.

Pokud soubor nemá žádné sady, tato metoda nebude volána. Zvažte použití onTestModuleStart pro pokrytí tohoto případu použití.

onTestSuiteResult

function onTestSuiteResult(testSuite: TestSuite): Awaitable<void>;

Tato metoda je volána poté, co sada dokončila spouštění testů. Tato metoda je také volána, pokud byla sada přeskočena.

Pokud soubor nemá žádné sady, tato metoda nebude volána. Zvažte použití onTestModuleEnd pro pokrytí tohoto případu použití.

onTestCaseReady

function onTestCaseReady(testCase: TestCase): Awaitable<void>;

Tato metoda se volá před tím, než se test začne spouštět nebo byl přeskočen. Všimněte si, že hooky beforeEach a afterEach jsou považovány za součást testu, protože mohou ovlivnit výsledek.

WARNING

Všimněte si, že testCase.result() může mít stav passed nebo failed již v okamžiku volání onTestCaseReady. To se může stát, pokud test běžel příliš rychle a onTestCaseReady i onTestCaseResult byly naplánovány ke spuštění ve stejném mikroúkolu.

onTestCaseResult

function onTestCaseResult(testCase: TestCase): Awaitable<void>;

Tato metoda se volá, když test dokončil běh nebo byl právě přeskočen. Všimněte si, že tato metoda bude volána po dokončení hooku afterEach, pokud nějaké existují.

V tomto okamžiku bude testCase.result() mít stav, který není pending.

onTestAnnotate 3.2.0+

function onTestAnnotate(
  testCase: TestCase,
  annotation: TestAnnotation
): Awaitable<void>;

Hook onTestAnnotate je spojen s metodou context.annotate. Když je annotate vyvolán, Vitest jej serializuje a odešle stejnou přílohu do hlavního vlákna, kde s ní může reportér interagovat.

Pokud je zadána cesta, Vitest ji uloží do samostatného adresáře (konfigurovaného pomocí attachmentsDir) a upraví vlastnost path tak, aby na ni odkazovala.