test context & advanced

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

TestCase class and task.type property

The TestCase class represents a single test and is only available in the main thread. A TestCase instance always has a type property with the value 'test'. You can check if (task.type === 'test') to distinguish TestCase from other task types.

TestCase.project property

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

TestCase.module property

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

TestCase.name property

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

TestCase.fullName property

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

TestCase.id is deterministic and based on project, module, and test order

The id property is a unique identifier for the test that is deterministic and will be the same across multiple runs. The ID is based on the project name, module ID, and test order. The format is: file_hash_suite_index_test_index (example: 1223128da3_0_0). The ID can have a minus sign at the start (example: -1223128da3_0_0_0). Do not try to parse the ID.

TestCase.location property and includeTaskLocation config

The location property indicates where in the module the test was defined, with line and column values. Locations are collected only if includeTaskLocation is enabled in the config. This option is automatically enabled if --reporter=html, --ui, or --browser flags are used.

TestCase.parent property

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

TestCase.options interface and structure

TestCase.tags property

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

TestCase.ok() method

The ok() method checks if the test did not fail the suite. It returns true if the test is not finished yet or was skipped.

TestCase.meta() method and attaching custom metadata

The meta() method returns a TaskMeta object containing custom metadata attached to the test during execution. You can attach metadata by assigning a property to ctx.task.meta during a test run. If the test did not finish running yet, meta will be an empty object unless it has static meta defined. Since Vitest 4.1, Vitest inherits the meta property defined on the suite.

TestCase.result() returns TestResult with four possible states

The result() method returns a TestResult that can be in one of four states: pending, skipped, failed, or passed. TestResultPending has state 'pending' and no errors. TestResultSkipped has state 'skipped', no errors, and an optional note from ctx.skip(note). TestResultFailed has state 'failed' and a ReadonlyArray<TestError>. TestResultPassed has state 'passed' and optionally a ReadonlyArray<TestError> (can occur if retry was triggered).

TestCase.diagnostic() method and TestDiagnostic interface

The diagnostic() method returns TestDiagnostic | undefined with test execution details. TestDiagnostic contains: slow (boolean), heap (number | undefined - only if logHeapUsage flag used), duration (number in ms), startTime (number in ms), retryCount (number), repeatCount (number), flaky (boolean if test passed on second retry). Returns undefined if test was not scheduled to run yet.

TestCase.annotations() method

The annotations() method returns a ReadonlyArray<TestAnnotation> containing test annotations added via the task.annotate API during test execution.

TestCase.artifacts() method

The artifacts() method returns a ReadonlyArray<TestArtifact> of test artifacts recorded via the recordArtifact API during test execution. This method was added in Vitest 4.0.11 as an experimental feature.

TestCase.toTestSpecification() method

The toTestSpecification() method returns a new test specification that can be used to filter or run this specific test case. This method is available since Vitest 4.1.0.

TestCase.logs() method

The logs() method returns a ReadonlyArray<UserConsoleLog> containing console logs recorded during the test execution. This method is available since Vitest 5.0.0.

TestProject.provide() method

The provide method allows providing custom values to tests in addition to the config.provide field. It takes a key (string) and value, and all values are validated with structuredClone before they are stored. The signature is: function provide<T extends keyof ProvidedContext & string>(key: T, value: ProvidedContext[T]): void. Values can be provided dynamically and provided values in tests will be updated on their next run.

TestProject.getProvidedContext() method

The getProvidedContext method returns the context object. Every project also inherits the global context set by vitest.provide. Project context values will always override the root project's context.

TestProject provide usage example

Example of using provide in Node.js API and test file: In node.js: import { createVitest } from 'vitest/node'; const vitest = await createVitest('test'); const project = vitest.projects.find(p => p.name === 'custom'); project.provide('key', 'value'); await vitest.start(); In test.spec.js: import { inject } from 'vitest'; const value = inject('key');

TestProject getProvidedContext example

Example of using getProvidedContext: import { createVitest } from 'vitest/node'; const vitest = await createVitest('test'); vitest.provide('global', true); const project = vitest.projects.find(p => p.name === 'custom'); project.provide('key', 'value'); const context = project.getProvidedContext(); // { global: true, key: 'value' }

Give your agent this brain