Reporter

WARNING

Questa è un'API avanzata. Se desideri solo configurare i reporter integrati, consulta la guida "Reporter".

Vitest gestisce un proprio ciclo di vita per l'esecuzione dei test. Questo ciclo è rappresentato dai seguenti metodi del reporter:

• 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

I test e le suite all'interno di un singolo modulo verranno riportati in ordine, a meno che non siano stati saltati. Tutti i test saltati vengono riportati alla fine della suite/modulo.

Si noti che, poiché i moduli di test possono essere eseguiti in parallelo, Vitest li riporterà in parallelo.

Questa guida elenca tutti i metodi del reporter supportati. Tuttavia, non dimenticare che, invece di creare il tuo reporter, puoi estendere quello esistente:

import { BaseReporter } from 'vitest/reporters';

export default class CustomReporter extends BaseReporter {
  onTestRunEnd(testModules, errors) {
    console.log(testModules.length, 'test hanno terminato l\'esecuzione');
    super.onTestRunEnd(testModules, errors);
  }
}

onInit

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

Questo metodo viene chiamato quando Vitest è stato avviato o inizializzato, ma prima che i test siano stati filtrati.

INFO

Internamente, questo metodo viene chiamato all'interno di vitest.start, vitest.init o vitest.mergeReports. Se stai usando l'API programmatica, assicurati di chiamare uno di questi a seconda delle tue esigenze prima di chiamare vitest.runTestSpecifications, per esempio. La CLI integrata eseguirà sempre i metodi nell'ordine corretto.

Si noti che è possibile accedere all'istanza di vitest anche dai casi di test, dalle suite e dai moduli di test tramite la proprietà project, ma potrebbe anche essere utile memorizzare un riferimento a vitest in questo metodo.

Esempio

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,
      'file di test verranno eseguiti in',
      this.vitest.config.root
    );
  }
}

export default new MyReporter();

onBrowserInit sperimentale

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

Questo metodo viene chiamato quando viene inizializzata l'istanza del browser. Riceve un'istanza del progetto per il quale il browser è stato inizializzato. project.browser sarà sempre definito quando questo metodo viene chiamato.

onTestRunStart

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

Questo metodo viene chiamato all'inizio di una nuova esecuzione di test. Riceve un array di specifiche di test programmate per l'esecuzione. Questo array è di sola lettura e disponibile solo a scopo informativo.

Se Vitest non ha trovato alcun file di test da eseguire, questo evento verrà invocato con un array vuoto, e quindi onTestRunEnd verrà chiamato immediatamente dopo.

Esempio

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

class MyReporter implements Reporter {
  onTestRunStart(specifications: TestSpecification[]) {
    console.log(specifications.length, 'file di test verranno eseguiti');
  }
}

export default new MyReporter();

AVVISO DI OBSOLESCENZA

Questo metodo è stato aggiunto in Vitest 3, sostituendo onPathsCollected e onSpecsCollected, entrambi ora deprecati.

onTestRunEnd

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

Questo metodo viene chiamato dopo che tutti i test hanno terminato l'esecuzione e la copertura ha unito tutti i report, se abilitata. Si noti che è possibile ottenere le informazioni sulla copertura nell'hook onCoverage.

Riceve un elenco di sola lettura di moduli di test. È possibile iterare su di esso tramite la proprietà testModule.children per riportare lo stato e gli errori, se presenti.

Il secondo argomento è un elenco di sola lettura di errori non gestiti che Vitest non è stato in grado di attribuire a nessun test. Questi possono verificarsi al di fuori dell'esecuzione del test a causa di un errore in un plugin, o all'interno dell'esecuzione del test come effetto collaterale di una funzione non attesa (ad esempio, un timeout che ha generato un errore dopo che il test ha terminato l'esecuzione).

Il terzo argomento indica il motivo per cui l'esecuzione del test è terminata:

• passed: l'esecuzione del test è terminata normalmente e non ci sono errori.
• failed: l'esecuzione del test ha almeno un errore (a causa di un errore di sintassi durante la raccolta o di un errore effettivo durante l'esecuzione del test).
• interrupted: il test è stato interrotto dalla chiamata vitest.cancelCurrentRun o è stato premuto Ctrl+C nel terminale (si noti che è ancora possibile avere test falliti in questo caso).

Se Vitest non ha trovato alcun file di test da eseguire, questo evento verrà invocato con array vuoti di moduli ed errori, e lo stato dipenderà dal valore di config.passWithNoTests.

Esempio

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, 'è riuscito'));
    } else if (reason === 'failed') {
      // nota che questo salterà possibili errori nelle suite
      // puoi ottenerli da 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('l\'esecuzione del test è stata interrotta, salto il report');
    }
  }
}

export default new MyReporter();

AVVISO DI OBSOLESCENZA

Questo metodo è stato aggiunto in Vitest 3, sostituendo onFinished, che ora è deprecato.

onCoverage

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

Questo hook viene chiamato dopo che i risultati della copertura sono stati elaborati. I reporter del provider di copertura vengono chiamati dopo questo hook. I tipi di coverage dipendono dal coverage.provider. Per i provider predefiniti di Vitest è possibile importare i tipi dal pacchetto istanbul-lib-coverage:

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

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

Se Vitest non ha eseguito alcuna copertura, questo hook non viene chiamato.

onTestModuleQueued

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

Questo metodo viene chiamato poco prima che Vitest importi il file di setup e il modulo di test stesso. Ciò significa che testModule non avrà ancora children, ma è possibile iniziare a riportarlo come il prossimo test da eseguire.

onTestModuleCollected

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

Questo metodo viene chiamato quando tutti i test all'interno del file sono stati raccolti, il che significa che la collezione testModule.children è popolata, ma i test non hanno ancora alcun risultato.

onTestModuleStart

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

Questo metodo viene chiamato subito dopo onTestModuleCollected a meno che Vitest non sia in esecuzione in modalità collection (vitest.collect() o vitest collect nella CLI), in questo caso non verrà chiamato affatto perché non ci sono test da eseguire.

onTestModuleEnd

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

Questo metodo viene chiamato quando ogni test nel modulo ha terminato l'esecuzione. Ciò significa che ogni test all'interno di testModule.children avrà un test.result() che non è uguale a pending.

onHookStart

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

Questo metodo viene chiamato quando uno di questi hook ha iniziato l'esecuzione:

• beforeAll
• afterAll
• beforeEach
• afterEach

Se beforeAll o afterAll sono avviati, l'entity sarà TestSuite o TestModule.

Se beforeEach o afterEach sono avviati, l'entity sarà sempre TestCase.

WARNING

Il metodo onHookStart non verrà chiamato se l'hook non è stato eseguito durante l'esecuzione del test.

onHookEnd

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

Questo metodo viene chiamato quando uno di questi hook ha terminato l'esecuzione:

• beforeAll
• afterAll
• beforeEach
• afterEach

Se beforeAll o afterAll sono terminati, l'entity sarà TestSuite o TestModule.

Se beforeEach o afterEach sono terminati, l'entity sarà sempre TestCase.

WARNING

Il metodo onHookEnd non verrà chiamato se l'hook non è stato eseguito durante l'esecuzione del test.

onTestSuiteReady

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

Questo metodo viene chiamato prima che la suite inizi a eseguire i suoi test. Questo metodo viene chiamato anche se la suite è stata saltata.

Se il file non ha suite, questo metodo non verrà chiamato. Considera l'utilizzo di onTestModuleStart per coprire questo caso d'uso.

onTestSuiteResult

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

Questo metodo viene chiamato dopo che la suite ha terminato l'esecuzione dei test. Questo metodo viene chiamato anche se la suite è stata saltata.

Se il file non ha suite, questo metodo non verrà chiamato. Considera l'utilizzo di onTestModuleEnd per coprire questo caso d'uso.

onTestCaseReady

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

Questo metodo viene chiamato prima che il test inizi a essere eseguito o sia stato saltato. Si noti che gli hook beforeEach e afterEach sono considerati parte del test perché possono influenzarne il risultato.

WARNING

Si noti che testCase.result() potrebbe già avere lo stato di passed o failed quando viene chiamato onTestCaseReady. Questo può accadere se il test è stato eseguito troppo velocemente e sia onTestCaseReady che onTestCaseResult sono stati programmati per essere eseguiti nella stessa microtask.

onTestCaseResult

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

Questo metodo viene chiamato quando il test ha terminato l'esecuzione o è stato semplicemente saltato. Si noti che questo verrà chiamato dopo che l'hook afterEach è terminato, se ce ne sono.

A questo punto, testCase.result() avrà uno stato non in sospeso.

onTestAnnotate 3.2.0+

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

L'hook onTestAnnotate è associato al metodo context.annotate. Quando annotate viene invocato, Vitest lo serializza e invia lo stesso allegato al thread principale dove il reporter può interagire con esso.

Se il percorso è specificato, Vitest lo memorizza in una directory separata (configurata da attachmentsDir) e modifica la proprietà path per farvi riferimento.