Reporters

WARNING

Esta é uma API avançada. Se você deseja apenas configurar os reporters embutidos, consulte o guia "Reporters".

O Vitest possui seu próprio ciclo de vida de execução de testes, representado pelos seguintes métodos do 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

Testes e suites dentro de um único módulo serão reportados em ordem, a menos que tenham sido ignorados. Todos os testes ignorados são relatados no final da suite/módulo.

Observe que, como os módulos de teste podem ser executados em paralelo, o Vitest os reportará em paralelo.

Este guia lista todos os métodos de reporter suportados. No entanto, não se esqueça de que, em vez de criar seu próprio reporter, você pode estender um existente:

import { BaseReporter } from 'vitest/reporters';

export default class CustomReporter extends BaseReporter {
  onTestRunEnd(testModules, errors) {
    console.log(testModules.length, 'testes finalizaram a execução');
    super.onTestRunEnd(testModules, errors);
  }
}

onInit

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

Este método é chamado quando o Vitest é iniciado ou inicializado, mas antes que os testes sejam filtrados.

INFO

Internamente, este método é chamado dentro de vitest.start, vitest.init ou vitest.mergeReports. Se você estiver usando a API programática, certifique-se de chamar um desses métodos, dependendo das suas necessidades, antes de chamar vitest.runTestSpecifications, por exemplo. A CLI embutida sempre executará os métodos na ordem correta.

Observe que você também pode ter acesso à instância vitest a partir de casos de teste, suites e módulos de teste por meio de uma propriedade project, mas também pode ser útil armazenar uma referência a vitest neste método.

Exemplo

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,
      'arquivos de teste serão executados em',
      this.vitest.config.root
    );
  }
}

export default new MyReporter();

onBrowserInit experimental

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

Este método é chamado quando a instância do navegador é criada. Ele recebe uma instância do projeto para o qual o navegador é iniciado. project.browser sempre será definido quando este método for chamado.

onTestRunStart

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

Este método é chamado quando uma nova execução de teste é iniciada. Ele recebe um array de especificações de teste agendadas para execução. Este array é somente leitura e está disponível apenas para fins informativos.

Se o Vitest não encontrar nenhum arquivo de teste para executar, este evento será invocado com um array vazio, e então onTestRunEnd será chamado imediatamente depois.

Exemplo

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

class MyReporter implements Reporter {
  onTestRunStart(specifications: TestSpecification[]) {
    console.log(specifications.length, 'arquivos de teste serão executados');
  }
}

export default new MyReporter();

AVISO DE OBSOLESCÊNCIA

Este método foi adicionado no Vitest 3, substituindo onPathsCollected e onSpecsCollected, ambos agora depreciados.

onTestRunEnd

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

Este método é chamado depois que todos os testes terminaram de ser executados e a cobertura mesclou todos os relatórios, se estiver habilitada. Observe que você pode obter as informações de cobertura no hook onCoverage.

Ele recebe uma lista somente leitura de módulos de teste. Você pode iterar sobre ela por meio de uma propriedade testModule.children para relatar o estado e os erros, se houver.

O segundo argumento é uma lista somente leitura de erros não tratados que o Vitest não conseguiu atribuir a nenhum teste. Isso pode acontecer fora da execução do teste devido a um erro em um plugin, ou dentro da execução do teste como um efeito colateral de uma função não aguardada (por exemplo, um timeout que lançou um erro depois que o teste terminou de ser executado).

O terceiro argumento indica por que a execução do teste foi finalizada:

• passed: a execução do teste foi finalizada normalmente e não há erros
• failed: a execução do teste tem pelo menos um erro (devido a um erro de sintaxe durante a coleta ou um erro real durante a execução do teste)
• interrupted: o teste foi interrompido pela chamada vitest.cancelCurrentRun ou Ctrl+C foi pressionado no terminal (observe que ainda é possível ter testes falhos neste caso)

Se o Vitest não encontrar nenhum arquivo de teste para executar, este evento será invocado com arrays vazios de módulos e erros, e o estado dependerá do valor de config.passWithNoTests.

Exemplo

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, 'foi bem-sucedido'));
    } else if (reason === 'failed') {
      // observe que isso ignorará possíveis erros em suites
      // você pode obtê-los de testSuite.errors()
      for (const testCase of testModules.children.allTests()) {
        if (testCase.result().state === 'failed') {
          console.log(
            testCase.fullName,
            'no módulo',
            testCase.module.moduleId,
            'falhou'
          );
          console.log(testCase.result().errors);
        }
      }
    } else {
      console.log('A execução do teste foi interrompida, ignorando o relatório.');
    }
  }
}

export default new MyReporter();

AVISO DE OBSOLESCÊNCIA

Este método foi adicionado no Vitest 3, substituindo onFinished, que agora está depreciado.

onCoverage

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

Este hook é chamado após os resultados da cobertura serem processados. Os reporters do provedor de cobertura são chamados após este hook. As tipagens de coverage dependem do coverage.provider. Para os provedores embutidos padrão do Vitest, você pode importar os tipos do pacote istanbul-lib-coverage:

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

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

Se o Vitest não coletou nenhuma cobertura, este hook não é chamado.

onTestModuleQueued

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

Este método é chamado logo antes do Vitest importar o arquivo de configuração do teste e o próprio módulo de teste. Isso significa que testModule ainda não terá children, mas você pode começar a reportá-lo como o próximo teste a ser executado.

onTestModuleCollected

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

Este método é chamado quando todos os testes neste arquivo foram coletados, o que significa que a coleção testModule.children está preenchida, mas os testes ainda não têm nenhum resultado.

onTestModuleStart

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

Este método é chamado imediatamente após onTestModuleCollected, a menos que o Vitest esteja sendo executado no modo de coleta (vitest.collect() ou vitest collect na CLI), neste caso, ele não será chamado de forma alguma porque não há testes para executar.

onTestModuleEnd

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

Este método é chamado quando cada teste no módulo foi executado. Isso significa que cada teste dentro de testModule.children terá um test.result() que não é igual a pending.

onHookStart

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

Este método é chamado quando qualquer um desses hooks começou a ser executado:

• beforeAll
• afterAll
• beforeEach
• afterEach

Se beforeAll ou afterAll forem iniciados, a entity será TestSuite ou TestModule.

Se beforeEach ou afterEach forem iniciados, a entity sempre será TestCase.

WARNING

O método onHookStart não será chamado se o hook não for executado durante a execução do teste.

onHookEnd

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

Este método é chamado quando qualquer um desses hooks terminou de ser executado:

• beforeAll
• afterAll
• beforeEach
• afterEach

Se beforeAll ou afterAll tiverem terminado, a entity será TestSuite ou TestModule.

Se beforeEach ou afterEach tiverem terminado, a entity sempre será TestCase.

WARNING

O método onHookEnd não será chamado se o hook não foi executado durante a execução do teste.

onTestSuiteReady

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

Este método é chamado antes que a suite comece a executar seus testes. Este método também é chamado se a suite foi ignorada.

Se o arquivo não tiver nenhuma suite, este método não será chamado. Considere usar onTestModuleStart para cobrir este caso de uso.

onTestSuiteResult

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

Este método é chamado depois que a suite terminou de executar os testes. Este método também é chamado se a suite foi ignorada.

Se o arquivo não tiver nenhuma suite, este método não será chamado. Considere usar onTestModuleEnd para cobrir este caso de uso.

onTestCaseReady

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

Este método é chamado antes que o teste comece a ser executado ou seja ignorado. Observe que os hooks beforeEach e afterEach são considerados parte do teste porque podem influenciar o resultado.

WARNING

Note que pode ocorrer de testCase.result() já estar com estado passed ou failed quando onTestCaseReady é chamado. Isso pode acontecer se o teste estiver sendo executado muito rapidamente e onTestCaseReady e onTestCaseResult foram agendados para serem executados na mesma microtarefa.

onTestCaseResult

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

Este método é chamado quando o teste terminou de ser executado ou foi apenas ignorado. Observe que isso será chamado depois que o hook afterEach terminar, se houver.

Neste momento, testCase.result() terá um estado definido (não pendente).

onTestAnnotate 3.2.0+

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

O hook onTestAnnotate está relacionado ao método context.annotate. Quando annotate é invocado, o Vitest o serializa e envia o mesmo anexo para o thread principal, onde o reporter pode interagir com ele.

Se o caminho for especificado, o Vitest o armazena em um diretório separado (configurado por attachmentsDir) e modifica a propriedade path para referenciá-lo.