Vitest · Config reference · all subjects

test artifacts

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

recordArtifact function signature and purpose

The recordArtifact function has the signature `function recordArtifact<Artifact extends TestArtifact>(task: Test, artifact: Artifact): Promise<Artifact>`. It records an artifact during test execution and returns it. It expects a task as the first parameter and an object assignable to TestArtifact as the second parameter. Artifacts must be recorded before the task is reported; any artifacts recorded after that will not be included in the task. When an artifact is recorded on a test, it emits an onTestArtifactRecord runner event and an onTestCaseArtifactRecord reporter event.

TestArtifactBase interface structure

The TestArtifactBase interface is the base for all test artifacts with the following properties: attachments (optional TestAttachment array) for file or data attachments, and location (optional TestArtifactLocation) indicating the source location where the artifact was created. Vitest automatically manages the attachments array and injects the location property. When api.allowWrite is disabled, Vitest empties the attachments array on every artifact before reporting it.

TestAttachment interface structure and properties

The TestAttachment interface has the following properties: contentType (optional string, e.g., 'image/png', 'text/plain') for MIME type; path (optional string) for local file path or external HTTP(S) URL, with relative paths resolved from project root; body (optional string or Uint8Array) for inline attachment content; bodyEncoding (optional, experimental, 'base64' or 'utf-8') specifying how string body is encoded, defaulting to 'base64'. If body is a string, Vitest assumes it is base64-encoded unless bodyEncoding is set to 'utf-8'. When body is Uint8Array, Vitest automatically encodes it as base64. Local files are copied to attachments directory before reporters receive them; external URLs are preserved as-is.

TestArtifactLocation interface structure

The TestArtifactLocation interface represents source code location information with the following properties: line (number, 1-indexed) for line number in source file; column (number, 1-indexed) for column number in the line; file (string) for path to the source file.

Custom artifact type registration using module augmentation

To register custom artifact types, use TypeScript's module augmentation feature to extend the TestArtifactRegistry interface. Each custom artifact should extend TestArtifactBase and include a unique type discriminator property. Best practices include: using a Symbol as the registry key to guarantee uniqueness; following the pattern 'package-name:artifact-name' for the type property (with 'internal:' being a reserved prefix); using attachments for files or data and extending TestAttachment for custom metadata; including | [] in the union when narrowing the attachments type since Vitest may empty the array at runtime; and the location property is automatically injected.

Test Artifacts API availability and status

Test Artifacts API is experimental and available from version 4.0.11 onwards. recordArtifact and TestArtifactBase are marked as experimental and breaking changes might not follow SemVer, so users should pin Vitest's version when using them. The API surface may change based on feedback.

Relationship between annotations and artifacts

Test annotations are built on top of the artifact system. When using annotations in tests, they create 'internal:annotation' artifacts under the hood. However, annotations are simpler to use and designed for end-users, while artifacts require custom data. Annotations do not appear in the task.artifacts array for backwards compatibility reasons until the next major version. Use annotations to add notes to tests; use artifacts for custom data.

Custom artifact example with accessibility audit

Example of a custom accessibility artifact: Define an A11yReportAttachment extending TestAttachment with contentType 'text/html' and path properties. Define AccessibilityArtifact extending TestArtifactBase with type 'a11y:report', passed (boolean), wcagLevel ('A' | 'AA' | 'AAA'), and attachments ([A11yReportAttachment] | []). Register with a Symbol key in TestArtifactRegistry via module augmentation. Then use in a custom matcher by calling recordArtifact(this.task, { type: 'a11y:report', passed: report.violations.length === 0, wcagLevel, attachments: [{ contentType: 'text/html', path: report.path }] }).

Give your agent this brain