TestCase
TestCase
类表示单个测试。此类仅在主线程中可用。如果您正在处理运行时任务,请参阅“Runner API”。
TestCase
实例始终有一个值为 test
的 type
属性。您可以使用它来区分不同的任务类型:
if (task.type === 'test') {
task // TestCase
}
WARNING
我们计划引入一个新的 Reporter API,默认将使用此 API。目前,Reporter API 使用 runner tasks,但您仍然可以通过 vitest.state.getReportedEntity
方法访问 TestCase
:
import type { RunnerTestFile, TestModule, Vitest } from 'vitest/node'
class Reporter {
private vitest!: Vitest
onInit(vitest: Vitest) {
this.vitest = vitest
}
onFinished(files: RunnerTestFile[]) {
for (const file of files) {
const testModule = this.vitest.getReportedEntity(file) as TestModule
for (const test of testModule.children.allTests()) {
console.log(test) // TestCase
}
}
}
}
project
这引用了测试所属的 TestProject
。
module
这是对定义测试的 TestModule
的直接引用。
name
这是传递给 test
函数的测试名称。
import { test } from 'vitest'
test('the validation works correctly', () => {
// ...
})
fullName
包括所有父套件并用 >
符号分隔的测试名称。此测试的完整名称为 "the validation logic > the validation works correctly":
import { describe, test } from 'vitest'
describe('the validation logic', () => {
test('the validation works correctly', () => {
// ...
})
})
id
这是测试的唯一标识符。此 ID 是确定性的,在多次运行中相同的测试将具有相同的 ID。ID 基于 project 名称、模块 ID 和测试顺序。
ID 的格式如下:
1223128da3_0_0
^^^^^^^^^^ the file hash
^ suite index
^ test index
TIP
你可以使用 vitest/node
中的 generateFileHash
函数来生成文件哈希,该函数自 Vitest 3 起可用:
import { generateFileHash } from 'vitest/node'
const hash = generateFileHash(
'/file/path.js', // relative path
undefined, // the project name or `undefined` is not set
)
DANGER
不要尝试解析 ID。它可能以连字符开头,例如:-1223128da3_0_0_0
。
location
测试在模块中定义的位置。只有在配置中启用了 includeTaskLocation
时才会收集位置信息。请注意,如果使用了 --reporter=html
、--ui
或 --browser
参数,此选项会自动启用。
此测试的位置将等于 { line: 3, column: 1 }
:
import { test } from 'vitest'
test('the validation works correctly', () => {
// ...
})
parent
父级 suite。如果测试是直接在 模块 内调用的,则父级将是模块本身。
options
interface TaskOptions {
each: boolean | undefined
concurrent: boolean | undefined
shuffle: boolean | undefined
retry: number | undefined
repeats: number | undefined
mode: 'run' | 'only' | 'skip' | 'todo'
}
收集测试时使用的选项。
ok
function ok(): boolean
检查测试是否未使套件失败。如果测试尚未完成或被跳过,它将返回 true
。
skipped
function skipped(): boolean
检查测试是否在收集期间或通过 ctx.skip()
动态跳过。
meta
function meta(): TaskMeta
在测试执行期间附加的自定义元数据。可以通过在测试运行期间将属性赋值给 ctx.task.meta
对象来附加元数据:
import { test } from 'vitest'
test('the validation works correctly', ({ task }) => {
// ...
task.meta.decorated = false
})
如果测试尚未完成运行,元数据将是一个空对象。
result
function result(): TestResult | undefined
测试结果。如果测试在收集期间被跳过、尚未完成或只是被收集,则结果将为 undefined
。
如果测试被跳过,返回值将是 TestResultSkipped
:
interface TestResultSkipped {
/**
* The test was skipped with `skip` or `todo` flag.
* You can see which one was used in the `options.mode` option.
*/
state: 'skipped'
/**
* Skipped tests have no errors.
*/
errors: undefined
/**
* A custom note passed down to `ctx.skip(note)`.
*/
note: string | undefined
}
TIP
如果测试因为其他测试有 only
标志而被跳过,则 options.mode
将等于 skip
。
如果测试失败,返回值将是 TestResultFailed
:
interface TestResultFailed {
/**
* The test failed to execute.
*/
state: 'failed'
/**
* Errors that were thrown during the test execution.
*/
errors: TestError[]
}
如果测试通过,返回值将是 TestResultPassed
:
interface TestResultPassed {
/**
* The test passed successfully.
*/
state: 'passed'
/**
* Errors that were thrown during the test execution.
*/
errors: TestError[] | undefined
}
WARNING
请注意,状态为 passed
的测试仍可能附带有错误——如果 retry
至少触发了一次,这种情况就可能发生。
diagnostic
function diagnostic(): TestDiagnostic | undefined
有关测试的有用信息,例如持续时间、内存使用等:
interface TestDiagnostic {
/**
* If the duration of the test is above `slowTestThreshold`.
*/
slow: boolean
/**
* The amount of memory used by the test in bytes.
* This value is only available if the test was executed with `logHeapUsage` flag.
*/
heap: number | undefined
/**
* The time it takes to execute the test in ms.
*/
duration: number
/**
* The time in ms when the test started.
*/
startTime: number
/**
* The amount of times the test was retried.
*/
retryCount: number
/**
* The amount of times the test was repeated as configured by `repeats` option.
* This value can be lower if the test failed during the repeat and no `retry` is configured.
*/
repeatCount: number
/**
* If test passed on a second retry.
*/
flaky: boolean
}