Reporters

O Vitest oferece diversos reporters integrados para exibir a saída dos testes em diferentes formatos, além de permitir o uso de reporters personalizados. Você pode selecionar reporters de duas maneiras: utilizando a opção de linha de comando --reporter ou incluindo a propriedade reporters em seu arquivo de configuração. Se nenhum reporter for especificado, o Vitest utilizará o reporter default, conforme descrito abaixo.

Utilizando reporters via linha de comando:

bash

npx vitest --reporter=verbose

Utilizando reporters via vitest.config.ts:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    reporters: ['verbose'],
  },
});

Alguns reporters podem ser personalizados através de opções adicionais. As opções específicas de cada reporter são detalhadas nas seções seguintes.

export default defineConfig({
  test: {
    reporters: ['default', ['junit', { suiteName: 'UI tests' }]],
  },
});

Saída do Reporter

Por padrão, os reporters do Vitest exibem sua saída no terminal. Ao utilizar os reporters json, html ou junit, você pode, alternativamente, direcionar a saída dos seus testes para um arquivo, incluindo a opção de configuração outputFile em seu arquivo de configuração do Vite ou via CLI.

CLIvitest.config.ts

bash

npx vitest --reporter=json --outputFile=./test-output.json

export default defineConfig({
  test: {
    reporters: ['json'],
    outputFile: './test-output.json',
  },
});

Combinando Reporters

É possível utilizar múltiplos reporters simultaneamente para exibir os resultados dos testes em diferentes formatos. Por exemplo:

bash

npx vitest --reporter=json --reporter=default

export default defineConfig({
  test: {
    reporters: ['json', 'default'],
    outputFile: './test-output.json',
  },
});

O exemplo acima exibirá os resultados do teste no terminal no formato padrão e os gravará como JSON no arquivo de saída especificado.

Ao usar múltiplos reporters, também é possível designar vários arquivos de saída, da seguinte forma:

export default defineConfig({
  test: {
    reporters: ['junit', 'json', 'verbose'],
    outputFile: {
      junit: './junit-report.xml',
      json: './json-report.json',
    },
  },
});

Este exemplo gerará relatórios JSON e XML separados, além de exibir um relatório detalhado no terminal.

Reporters Integrados

Reporter Padrão

Por padrão (ou seja, se nenhum reporter for especificado), o Vitest exibirá um resumo dos testes em execução e seus respectivos status na parte inferior. Assim que um conjunto de testes for concluído com sucesso, seu status será reportado no topo do resumo.

Você pode desabilitar o resumo configurando o reporter:

vitest.config.ts

export default defineConfig({
  test: {
    reporters: [['default', { summary: false }]],
  },
});

Exemplo de saída para testes em andamento:

bash

 ✓ test/example-1.test.ts (5 tests | 1 skipped) 306ms
 ✓ test/example-2.test.ts (5 tests | 1 skipped) 307ms

 ❯ test/example-3.test.ts 3/5
 ❯ test/example-4.test.ts 1/5

 Test Files 2 passed (4)
      Tests 10 passed | 3 skipped (65)
   Start at 11:01:36
   Duration 2.00s

Saída final após a conclusão dos testes:

bash

 ✓ test/example-1.test.ts (5 tests | 1 skipped) 306ms
 ✓ test/example-2.test.ts (5 tests | 1 skipped) 307ms
 ✓ test/example-3.test.ts (5 tests | 1 skipped) 307ms
 ✓ test/example-4.test.ts (5 tests | 1 skipped) 307ms

 Test Files  4 passed (4)
      Tests  16 passed | 4 skipped (20)
   Start at  12:34:32
   Duration  1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)

Reporter Básico

O reporter basic é equivalente ao reporter default sem o resumo (summary).

CLIvitest.config.ts

bash

npx vitest --reporter=basic

export default defineConfig({
  test: {
    reporters: ['basic'],
  },
});

Exemplo de saída utilizando o reporter básico:

bash

✓ __tests__/file1.test.ts (2) 725ms
✓ __tests__/file2.test.ts (2) 746ms

 Test Files  2 passed (2)
      Tests  4 passed (4)
   Start at  12:34:32
   Duration  1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)

Reporter Verbose

O reporter verbose é similar ao reporter default, mas também exibe cada teste individualmente após a conclusão do conjunto de testes. Ele também mostra os testes atualmente em execução que estão demorando mais que o slowTestThreshold. Assim como o reporter default, você pode desabilitar o resumo configurando o reporter.

CLIvitest.config.ts

bash

npx vitest --reporter=verbose

export default defineConfig({
  test: {
    reporters: [['verbose', { summary: false }]],
  },
});

Exemplo de saída para testes em andamento com slowTestThreshold: 300 (padrão):

bash

 ✓ __tests__/example-1.test.ts (2) 725ms
   ✓ first test file (2) 725ms
     ✓ 2 + 2 should equal 4
     ✓ 4 - 2 should equal 2

 ❯ test/example-2.test.ts 3/5
   ↳ should run longer than three seconds 1.57s
 ❯ test/example-3.test.ts 1/5

 Test Files 2 passed (4)
      Tests 10 passed | 3 skipped (65)
   Start at 11:01:36
   Duration 2.00s

Exemplo de saída final do terminal para um conjunto de testes aprovado:

bash

✓ __tests__/file1.test.ts (2) 725ms
   ✓ first test file (2) 725ms
     ✓ 2 + 2 should equal 4
     ✓ 4 - 2 should equal 2
✓ __tests__/file2.test.ts (2) 746ms
  ✓ second test file (2) 746ms
    ✓ 1 + 1 should equal 2
    ✓ 2 - 1 should equal 1

 Test Files  2 passed (2)
      Tests  4 passed (4)
   Start at  12:34:32
   Duration  1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)

Reporter Dot

Imprime um único ponto para cada teste concluído, fornecendo uma saída mínima e mostrando todos os testes executados. Detalhes são fornecidos apenas para testes falhos, juntamente com o resumo do reporter basic para o conjunto de testes.

CLIvitest.config.ts

bash

npx vitest --reporter=dot

export default defineConfig({
  test: {
    reporters: ['dot'],
  },
});

Exemplo de saída do terminal para um conjunto de testes aprovado:

bash

....

 Test Files  2 passed (2)
      Tests  4 passed (4)
   Start at  12:34:32
   Duration  1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)

Reporter JUnit

Produz um relatório dos resultados do teste no formato XML JUnit. Pode ser impresso no terminal ou salvo em um arquivo XML utilizando a opção de configuração outputFile.

CLIvitest.config.ts

bash

npx vitest --reporter=junit

export default defineConfig({
  test: {
    reporters: ['junit'],
  },
});

Exemplo de um relatório XML JUnit:

xml

<?xml version="1.0" encoding="UTF-8" ?>
<testsuites name="vitest tests" tests="2" failures="1" errors="0" time="0.503">
    <testsuite name="__tests__/test-file-1.test.ts" timestamp="2023-10-19T17:41:58.580Z" hostname="My-Computer.local" tests="2" failures="1" errors="0" skipped="0" time="0.013">
        <testcase classname="__tests__/test-file-1.test.ts" name="first test file &gt; 2 + 2 should equal 4" time="0.01">
            <failure message="expected 5 to be 4 // Object.is equality" type="AssertionError">
AssertionError: expected 5 to be 4 // Object.is equality
 ❯ __tests__/test-file-1.test.ts:20:28
            </failure>
        </testcase>
        <testcase classname="__tests__/test-file-1.test.ts" name="first test file &gt; 4 - 2 should equal 2" time="0">
        </testcase>
    </testsuite>
</testsuites>

O XML gerado contém tags testsuites e testcase aninhadas. Elas também podem ser personalizadas via opções do reporter suiteName e classnameTemplate. classnameTemplate pode ser uma template string ou uma função.

Os placeholders suportados para a opção classnameTemplate são:

filename
filepath

export default defineConfig({
  test: {
    reporters: [
      [
        'junit',
        {
          suiteName: 'custom suite name',
          classnameTemplate: 'filename:{filename} - filepath:{filepath}',
        },
      ],
    ],
  },
});

Reporter JSON

Gera um relatório dos resultados do teste em um formato JSON compatível com a opção --json do Jest. Pode ser impresso no terminal ou salvo em um arquivo utilizando a opção de configuração outputFile.

CLIvitest.config.ts

bash

npx vitest --reporter=json

export default defineConfig({
  test: {
    reporters: ['json'],
  },
});

Exemplo de um relatório JSON:

json

{
  "numTotalTestSuites": 4,
  "numPassedTestSuites": 2,
  "numFailedTestSuites": 1,
  "numPendingTestSuites": 1,
  "numTotalTests": 4,
  "numPassedTests": 1,
  "numFailedTests": 1,
  "numPendingTests": 1,
  "numTodoTests": 1,
  "startTime": 1697737019307,
  "success": false,
  "testResults": [
    {
      "assertionResults": [
        {
          "ancestorTitles": ["", "first test file"],
          "fullName": " first test file 2 + 2 should equal 4",
          "status": "failed",
          "title": "2 + 2 should equal 4",
          "duration": 9,
          "failureMessages": ["expected 5 to be 4 // Object.is equality"],
          "location": {
            "line": 20,
            "column": 28
          },
          "meta": {}
        }
      ],
      "startTime": 1697737019787,
      "endTime": 1697737019797,
      "status": "failed",
      "message": "",
      "name": "/root-directory/__tests__/test-file-1.test.ts"
    }
  ],
  "coverageMap": {}
}

INFO

Desde o Vitest 3, o reporter JSON inclui informações de cobertura em coverageMap se a cobertura estiver habilitada.

Reporter HTML

Gera um arquivo HTML para visualizar os resultados dos testes através de uma GUI interativa. Após a geração do arquivo, o Vitest manterá um servidor de desenvolvimento local ativo e fornecerá um link para visualizar o relatório em um navegador.

O arquivo de saída pode ser definido utilizando a opção de configuração outputFile. Se nenhuma opção outputFile for informada, um novo arquivo HTML será criado.

CLIvitest.config.ts

bash

npx vitest --reporter=html

export default defineConfig({
  test: {
    reporters: ['html'],
  },
});

TIP

Este reporter requer o pacote @vitest/ui instalado.

Reporter TAP

Gera um relatório seguindo o Test Anything Protocol (TAP).

CLIvitest.config.ts

bash

npx vitest --reporter=tap

export default defineConfig({
  test: {
    reporters: ['tap'],
  },
});

Exemplo de um relatório TAP:

bash

TAP version 13
1..1
not ok 1 - __tests__/test-file-1.test.ts # time=14.00ms {
    1..1
    not ok 1 - first test file # time=13.00ms {
        1..2
        not ok 1 - 2 + 2 should equal 4 # time=11.00ms
            ---
            error:
                name: "AssertionError"
                message: "expected 5 to be 4 // Object.is equality"
            at: "/root-directory/__tests__/test-file-1.test.ts:20:28"
            actual: "5"
            expected: "4"
            ...
        ok 2 - 4 - 2 should equal 2 # time=1.00ms
    }
}

Reporter TAP Flat

Gera um relatório TAP flat. Assim como o reporter tap, os resultados dos testes são formatados para seguir os padrões TAP, mas os conjuntos de testes são formatados como uma lista plana em vez de uma hierarquia aninhada.

CLIvitest.config.ts

bash

npx vitest --reporter=tap-flat

export default defineConfig({
  test: {
    reporters: ['tap-flat'],
  },
});

Exemplo de um relatório TAP flat:

bash

TAP version 13
1..2
not ok 1 - __tests__/test-file-1.test.ts > first test file > 2 + 2 should equal 4 # time=11.00ms
    ---
    error:
        name: "AssertionError"
        message: "expected 5 to be 4 // Object.is equality"
    at: "/root-directory/__tests__/test-file-1.test.ts:20:28"
    actual: "5"
    expected: "4"
    ...
ok 2 - __tests__/test-file-1.test.ts > first test file > 4 - 2 should equal 2 # time=0.00ms

Reporter de Processos Pendurados

Exibe uma lista de processos pendurados, se houver algum impedindo que o Vitest seja encerrado com segurança. O reporter hanging-process não exibe os resultados dos testes em si, mas pode ser usado em conjunto com outro reporter para monitorar processos enquanto os testes são executados. O uso deste reporter pode ser intensivo em recursos, portanto, geralmente deve ser reservado para fins de depuração em situações em que o Vitest consistentemente não consegue sair do processo.

CLIvitest.config.ts

bash

npx vitest --reporter=hanging-process

export default defineConfig({
  test: {
    reporters: ['hanging-process'],
  },
});

Reporter Github Actions

Gera comandos de fluxo de trabalho para fornecer anotações para falhas de teste. Este reporter é automaticamente habilitado com um reporter default quando process.env.GITHUB_ACTIONS === 'true'.

Se você configurar reporters não padrão, precisará adicionar explicitamente github-actions.

export default defineConfig({
  test: {
    reporters: process.env.GITHUB_ACTIONS ? ['dot', 'github-actions'] : ['dot'],
  },
});

Você pode personalizar os caminhos de arquivo que aparecem no formato de comando de anotação do GitHub utilizando a opção onWritePath. Isso é útil ao executar o Vitest em um ambiente em contêineres, como o Docker, onde os caminhos de arquivo podem não corresponder aos caminhos no ambiente do GitHub Actions.

export default defineConfig({
  test: {
    reporters: process.env.GITHUB_ACTIONS
      ? [
          'default',
          [
            'github-actions',
            {
              onWritePath(path) {
                return path.replace(
                  /^\/app\//,
                  `${process.env.GITHUB_WORKSPACE}/`
                );
              },
            },
          ],
        ]
      : ['default'],
  },
});

Reporter Blob

Salva os resultados dos testes na máquina para que possam ser mesclados posteriormente utilizando o comando --merge-reports. Por padrão, armazena todos os resultados na pasta .vitest-reports, mas pode ser sobrescrito pelas flags --outputFile ou --outputFile.blob.

bash

npx vitest --reporter=blob --outputFile=reports/blob-1.json

Recomendamos usar este reporter se você estiver executando o Vitest em diferentes máquinas com a flag --shard. Todos os relatórios blob podem ser mesclados em qualquer relatório utilizando o comando --merge-reports no final do seu pipeline de CI:

bash

npx vitest --merge-reports=reports --reporter=json --reporter=default

TIP

Tanto --reporter=blob quanto --merge-reports não funcionam no modo de observação (watch mode).

Reporters Personalizados

Você pode utilizar reporters personalizados de terceiros instalados via NPM especificando o nome do pacote na opção de reporters:

CLIvitest.config.ts

bash

npx vitest --reporter=some-published-vitest-reporter

export default defineConfig({
  test: {
    reporters: ['some-published-vitest-reporter'],
  },
});

Além disso, você pode definir seus próprios reporters personalizados e utilizá-los especificando o caminho do arquivo:

bash

npx vitest --reporter=./path/to/reporter.ts

Os reporters personalizados devem implementar a interface Reporter.

Reporters ​

Saída do Reporter ​

Combinando Reporters ​

Reporters Integrados ​

Reporter Padrão ​

Reporter Básico ​

Reporter Verbose ​

Reporter Dot ​

Reporter JUnit ​

Reporter JSON ​

Reporter HTML ​

Reporter TAP ​

Reporter TAP Flat ​

Reporter de Processos Pendurados ​

Reporter Github Actions ​

Reporter Blob ​

Reporters Personalizados ​

Reporters

Saída do Reporter

Combinando Reporters

Reporters Integrados

Reporter Padrão

Reporter Básico

Reporter Verbose

Reporter Dot

Reporter JUnit

Reporter JSON

Reporter HTML

Reporter TAP

Reporter TAP Flat

Reporter de Processos Pendurados

Reporter Github Actions

Reporter Blob

Reporters Personalizados