test context

27 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

meta property on tasks for sharing test data

Every task (suite or test) in Vitest has a `meta` property that can be used to share data between tests and the Node.js process. The `meta` property can be modified from within the test context or inside beforeAll/afterAll hooks for suite tasks. This communication is one-way only: the `meta` property can only be modified from within the test context, and changes made within the Node.js context will not be visible in tests.

Setting meta property in test context

The `meta` property can be populated on a test by accessing `task.meta` within a test function. Example: `test('custom', ({ task }) => { task.meta.custom = 'some-custom-handler' })`

Setting meta property in beforeAll/afterAll hooks

The `meta` property can be populated on a suite task inside beforeAll/afterAll hooks by accessing the suite parameter. Example: `afterAll((suite) => { suite.meta.done = true })`

meta property serialization requirements

The `meta` property must be serializable. Vitest uses different serialization methods depending on the execution context: message port for worker threads, process.send for child processes, and flatted package for browser environments. The meta property is present on every test in the json reporter, so all data must be serializable to JSON. Error properties must be serialized before being set on meta.

Extending TaskMeta type definitions with TypeScript

Custom meta properties can be type-safe by extending the TaskMeta interface in a module declaration. Example: `declare module 'vitest' { interface TaskMeta { done?: boolean; custom?: string; } }`

TestCase fullName includes parent suites separated by >

The fullName property contains the name of the test including all parent suites, with each level separated by a > symbol. For example, a test 'the validation works correctly' inside a describe block 'the validation logic' would have fullName 'the validation logic > the validation works correctly'.

TestCase id is deterministic and unique identifier

The id property is a test's unique identifier that is deterministic and remains the same for the same test across multiple runs. The ID is based on the project name, module ID and test order, with the format consisting of a file hash, suite index, and test index separated by underscores. For example: 1223128da3_0_0. The ID can have a minus sign at the start. Do not attempt to parse the ID manually.

generateFileHash function for creating file hash

The generateFileHash function from 'vitest/node' can generate file hashes for test IDs. It is available since Vitest 3. The function signature is: generateFileHash('/file/path.js', undefined) where the first parameter is the relative path and the second parameter is the project name or undefined if not set.

TestCase location property requires includeTaskLocation config

The location property indicates where in the module the test was defined, with values like { line: 3, column: 1 }. Locations are collected only if includeTaskLocation is enabled in the config. This option is automatically enabled when using --reporter=html, --ui, or --browser flags.

TestCase options interface with all fields

TestCase tags property since 4.1.0

The tags property contains tags that were implicitly or explicitly assigned to the test, available since Vitest 4.1.0.

TestCase ok() method returns boolean

The ok() method has signature function ok(): boolean and checks if the test did not fail the suite. If the test is not finished yet or was skipped, it returns true.

TestCase meta() method returns TaskMeta

The meta() method has signature function meta(): TaskMeta and returns custom metadata that was attached to the test during its execution. The meta can be attached by assigning a property to the ctx.task.meta object during a test run. If the test did not finish running yet, the meta will be an empty object unless it has static meta passed as { meta: { decorated: true } } to the test function. Since Vitest 4.1, meta properties defined on the parent suite are inherited.

TestCase result() method returns test result

The result() method has signature function result(): TestResult and returns test results. If the test is not finished yet or was just collected, it returns TestResultPending with state 'pending' and errors undefined. If skipped, it returns TestResultSkipped with state 'skipped', errors undefined, and optional note from ctx.skip(note). If failed, it returns TestResultFailed with state 'failed' and errors array of TestError. If passed, it returns TestResultPassed with state 'passed' and optional errors array. A passed test can still have errors if retry was triggered at least once.

TestCase diagnostic() method returns test metrics

The diagnostic() method has signature function diagnostic(): TestDiagnostic | undefined and returns useful information about the test. The TestDiagnostic object contains: slow (boolean indicating if duration exceeds slowTestThreshold), heap (number | undefined - memory used in bytes, only if logHeapUsage flag used), duration (number - test execution time in ms), startTime (number - time in ms when test started), retryCount (number - times test was retried), repeatCount (number - times test was repeated, may be lower if test failed during repeat with no retry configured), flaky (boolean - true if test passed on a second retry). Returns undefined if the test was not scheduled to run yet.

TestCase annotations() method returns array

The annotations() method has signature function annotations(): ReadonlyArray<TestAnnotation> and returns test annotations added via the task.annotate API during test execution.

TestCase toTestSpecification() method since 4.1.0

The toTestSpecification() method has signature function toTestSpecification(): TestSpecification and returns a new test specification that can be used to filter or run this specific test case. Available since Vitest 4.1.0.

TestCase logs() method returns console logs since 5.0.0

The logs() method has signature function logs(): ReadonlyArray<UserConsoleLog> and returns console logs recorded during test execution. Available since Vitest 5.0.0.

TestCase parent is suite or module

The parent property contains the parent suite. If the test was called directly inside the module, the parent will be the module itself.

TestCase class type property always equals 'test'

The TestCase instance always has a type property with the value 'test'. This can be used to distinguish between different task types by checking if task.type === 'test'.

TestCase project property references TestProject

The project property on a TestCase instance is a direct reference to the TestProject that the test belongs to.

TestCase module property references TestModule

The module property on a TestCase instance is a direct reference to the TestModule where the test is defined.

TestCase name property contains test name

The name property contains the test name that was passed to the test function.

Annotation API for test annotations

Vitest 3.2 introduces an Annotation API that allows annotating any test with custom messages and attachments. Annotations are visible in the UI, HTML, junit, TAP, and GitHub Actions reporters. Vitest prints related annotations in the CLI if a test fails.

Test signal API with AbortSignal

Vitest provides an AbortSignal object to the test body via the signal parameter. The signal is aborted when the test times out, another test fails with bail flag set to non-zero, or the user presses Ctrl+C. This allows stopping resources that support the Web API AbortSignal, such as fetch requests.

Test signal example for fetch timeout

Example of using test signal to stop fetch requests: it('stop request when test times out', async ({ signal }) => { await fetch('/heavy-resource', { signal }) }, 2000). The signal parameter is automatically provided to the test body.

test.extend with type inference builder pattern

The test.extend method now supports type inference without manual type declarations. Simple values return their type directly: .extend('config', { port: 3000, host: 'localhost' }) infers type as { port: number; host: string }. Function fixtures infer types from return values: .extend('server', async ({ config }) => { return `http://${config.host}:${config.port}` }) infers return type. For setup/cleanup, the onCleanup callback registers teardown logic: .extend('tempFile', async ({}, { onCleanup }) => { onCleanup(() => fs.unlink(filePath)); return filePath }).

Give your agent this brain