报告器
Vitest 提供了几种内置报告器,以不同格式显示测试输出,以及使用自定义报告器的能力。你可以使用 --reporter
命令行选项,或者在你的 outputFile
配置选项 中加入 reporters
属性来选择不同的报告器。如果没有指定报告器,Vitest 将使用下文所述的默认报告器。
通过命令行使用报告器:
npx vitest --reporter=verbose
通过配置文件 vitest.config.ts
使用报告器:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
reporters: ['verbose'],
},
})
某些报告器可以通过传递附加选项进行自定义。具体选项将在下面的章节中介绍。
export default defineConfig({
test: {
reporters: ['default', ['junit', { suiteName: 'UI tests' }]],
},
})
报告器输出
默认情况下,Vitest 的报告器会将输出打印到终端。当使用 json
、html
或 junit
报告器时,你可以在 Vite 配置文件中或通过 CLI 加入 outputFile
配置选项,将测试输出写入文件。
npx vitest --reporter=json --outputFile=./test-output.json
export default defineConfig({
test: {
reporters: ['json'],
outputFile: './test-output.json',
},
})
组合报告器
你可以同时使用多个报告器,并以不同格式打印测试结果。
例如:
npx vitest --reporter=json --reporter=default
export default defineConfig({
test: {
reporters: ['json', 'default'],
outputFile: './test-output.json',
},
})
上面的示例将同时把测试结果以默认样式打印到终端,和以 JSON 格式写入指定的输出文件。
使用多个报告器时,还可以指定多个输出文件,如下所示:
export default defineConfig({
test: {
reporters: ['junit', 'json', 'verbose'],
outputFile: {
junit: './junit-report.xml',
json: './json-report.json',
},
},
})
这个示例将编写单独的 JSON 和 XML 报告,并将详细报告打印到终端。
内置报告器
默认报告器
默认情况下(即如果没有指定报告器),Vitest 会在底部显示运行测试的摘要及其状态。一旦测试套件通过,其状态将被报告在摘要的顶部。
我们可以通过配置报告器来禁用摘要:
export default defineConfig({
test: {
reporters: [
['default', { summary: false }]
]
},
})
项目中的测试输出示例:
✓ 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
测试完成后的最终输出:
✓ 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)
基础报告器
basic
报告器等同于没有 summary
的 default
报告器。
npx vitest --reporter=basic
export default defineConfig({
test: {
reporters: ['basic'],
},
})
使用基础报告器的输出示例:
✓ __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)
详细报告器
详细报告器与 default
报告器相同,但它还会在测试套件完成后显示每个单独的测试。它还会显示当前正在运行且耗时超过 slowTestThreshold
的测试。与 default
报告器类似,我们可以通过配置报告器来禁用摘要。
npx vitest --reporter=verbose
export default defineConfig({
test: {
reporters: [
['verbose', { summary: false }]
]
},
})
使用默认 slowTestThreshold: 300
的情况下,测试进行中的示例输出:
✓ __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
测试套件通过后的终端最终输出示例:
✓ __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)
Dot 报告器
为每个已完成的测试打印一个点,以提供最少的输出,并显示所有已运行的测试。只提供失败测试的详细信息,以及套件的基本报告摘要。
npx vitest --reporter=dot
export default defineConfig({
test: {
reporters: ['dot'],
},
})
测试套件通过后的终端最终输出示例:
....
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)
JUnit 报告器
以 JUnit XML 格式输出测试结果报告。既可打印到终端,也可使用 outputFile
配置选项写入 XML 文件。
npx vitest --reporter=junit
export default defineConfig({
test: {
reporters: ['junit'],
},
})
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 > 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 > 4 - 2 should equal 2" time="0">
</testcase>
</testsuite>
</testsuites>
输出的 XML 包含嵌套的 testsuites
和 testcase
标签。这些也可以通过报告选项 suiteName
和 classnameTemplate
进行自定义。classnameTemplate
可以是一个模板字符串或者一个函数。
classnameTemplate
选项支持的占位符有:
- filename
- filepath
export default defineConfig({
test: {
reporters: [
['junit', { suiteName: 'custom suite name', classnameTemplate: 'filename:{filename} - filepath:{filepath}' }]
]
},
})
输出的 XML 包含嵌套的 testsuites
和 testcase
标记。你可以使用环境变量 VITEST_JUNIT_SUITE_NAME
和 VITEST_JUNIT_CLASSNAME
分别配置它们的名称和类名属性。
JSON 报告器
以与 Jest 的 --json
选项兼容的 JSON 格式生成测试结果报告。可以打印到终端,也可以使用 outputFile
配置选项写入文件。
npx vitest --reporter=json
export default defineConfig({
test: {
reporters: ['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
自Vitest 3起,如果启用了代码覆盖率功能,JSON 报告器会在 coverageMap
中包含覆盖率信息。
HTML 报告器
生成 HTML 文件,通过交互式 GUI 查看测试结果。文件生成后,Vitest 将保持本地开发服务器运行,并提供一个链接,以便在浏览器中查看报告。
可使用 outputFile
配置选项指定输出文件。如果没有提供 outputFile
选项,则会创建一个新的 HTML 文件。
npx vitest --reporter=html
export default defineConfig({
test: {
reporters: ['html'],
},
})
TIP
该报告器需要安装 @vitest/ui
。
TAP 报告器
按照 Test Anything Protocol (TAP)输出报告。
npx vitest --reporter=tap
export default defineConfig({
test: {
reporters: ['tap'],
},
})
TAP 报告示例:
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
}
}
TAP 扁平报告器
输出 TAP 扁平报告。与 TAP Reporter
一样,测试结果的格式遵循 TAP 标准,但测试套件的格式是扁平列表,而不是嵌套层次结构。
npx vitest --reporter=tap-flat
export default defineConfig({
test: {
reporters: ['tap-flat'],
},
})
TAP 扁平报告示例:
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
Hanging process 报告器
展示任何妨碍 Vitest 安全退出的 hanging processes ,hanging-process
报告器本身不显示测试结果,但可与其他报告器结合使用,以便在测试运行时监控进程。使用这个报告器可能会消耗大量资源,因此通常应保留用于在 Vitest 无法正常退出进程的情况下进行调试的目的。
npx vitest --reporter=hanging-process
export default defineConfig({
test: {
reporters: ['hanging-process'],
},
})
Github Actions Reporter
输出 工作流命令 为测试失败提供注释。当 process.env.GITHUB_ACTIONS === 'true'
时,会自动启用 default
报告器。
如果配置了非默认报告器,则需要显式添加 github-actions
。
export default defineConfig({
test: {
reporters: process.env.GITHUB_ACTIONS ? ['dot', 'github-actions'] : ['dot'],
},
})
Blob Reporter
将测试结果存储在计算机上,以便以后可以使用 --merge-reports
命令进行合并。 默认情况下,将所有结果存储在 .vitest-reports
文件夹中,但可以用 --outputFile
或 --outputFile.blob
标志覆盖。
npx vitest --reporter=blob --outputFile=reports/blob-1.json
如果你在带有 --shard
标志的不同机器上运行 Vitest,我们建议你使用此报告程序。 使用 CI 管道末尾的 --merge-reports
命令,可以将所有 blob 报告合并到任何报告中:
npx vitest --merge-reports=reports --reporter=json --reporter=default
TIP
Both --reporter=blob
and --merge-reports
do not work in watch mode.
自定义报告器
你可以使用从 NPM 安装的第三方自定义报告器,方法是在 reporter
选项中指定它们的软件包名称:
npx vitest --reporter=some-published-vitest-reporter
export default defineConfig({
test: {
reporters: ['some-published-vitest-reporter'],
},
})
此外,你还可以定义自己的自定义报告器,并通过指定文件路径来使用它们:
npx vitest --reporter=./path/to/reporter.ts
自定义报告器应实现报告器接口。