feat: add metadata and multiple attachments to annotations

Author: macarie

packages/runner/src/context.ts

@@ -6,8 +6,6 @@ import type {
   SuiteCollector,
   Test,
   TestAnnotation,
-  TestAnnotationLocation,
-  TestAttachment,
   TestContext,
   WriteableTestContext,
 } from './types/tasks'
@@ -157,33 +155,47 @@ export function createTestContext(
     )
   }
 
-  async function annotate(
-    message: string,
-    location?: TestAnnotationLocation,
-    type?: string,
-    attachment?: TestAttachment,
-  ) {
-    const annotation: TestAnnotation = {
-      message,
-      type: type || 'notice',
+  function createAnnotation(annotation: TestAnnotation): TestAnnotation {
+    const stack = findTestFileStackTrace(
+      test.file.filepath,
+      new Error('STACK_TRACE').stack!,
+    )
+
+    if (stack) {
+      annotation.location = {
+        file: stack.file,
+        line: stack.line,
+        column: stack.column,
+      }
     }
-    if (attachment) {
+
+    if (annotation.attachment !== undefined && annotation.attachments !== undefined) {
+      throw new TypeError('A test annotation cannot have both "attachment" and "attachments"')
+    }
+
+    const attachments = annotation.attachments ?? (annotation.attachment !== undefined ? [annotation.attachment] : [])
+
+    for (const attachment of attachments) {
       if (attachment.body == null && !attachment.path) {
         throw new TypeError(`Test attachment requires "body" or "path" to be set. Both are missing.`)
       }
+
       if (attachment.body && attachment.path) {
         throw new TypeError(`Test attachment requires only one of "body" or "path" to be set. Both are specified.`)
       }
-      annotation.attachment = attachment
+
       // convert to a string so it's easier to serialise
       if (attachment.body instanceof Uint8Array) {
         attachment.body = encodeUint8Array(attachment.body)
       }
     }
-    if (location) {
-      annotation.location = location
-    }
 
+    return annotation
+  }
+
+  async function annotate(
+    annotation: TestAnnotation,
+  ) {
     if (!runner.onTestAnnotate) {
       throw new Error(`Test runner doesn't support test annotations.`)
     }
@@ -200,33 +212,29 @@ export function createTestContext(
       throw new Error(`Cannot annotate tests outside of the test run. The test "${test.name}" finished running with the "${test.result.state}" state already.`)
     }
 
-    const stack = findTestFileStackTrace(
-      test.file.filepath,
-      new Error('STACK_TRACE').stack!,
-    )
-
-    let location: undefined | TestAnnotationLocation
+    if (typeof message === 'object') {
+      const annotation = createAnnotation(message)
 
-    if (stack) {
-      location = {
-        file: stack.file,
-        line: stack.line,
-        column: stack.column,
-      }
+      return recordAsyncAnnotation(test, annotate(annotation))
     }
 
     if (typeof type === 'object') {
-      return recordAsyncAnnotation(
-        test,
-        annotate(message, location, undefined, type),
-      )
-    }
-    else {
-      return recordAsyncAnnotation(
-        test,
-        annotate(message, location, type, attachment),
-      )
+      const annotation = createAnnotation({
+        type: 'notice',
+        message,
+        attachment: type,
+      })
+
+      return recordAsyncAnnotation(test, annotate(annotation))
     }
+
+    const annotation = createAnnotation({
+      type: type ?? 'notice',
+      message,
+      attachment,
+    })
+
+    return recordAsyncAnnotation(test, annotate(annotation))
   }) as TestContext['annotate']
 
   context.onTestFailed = (handler, timeout) => {

packages/runner/src/types.ts

@@ -43,6 +43,7 @@ export type {
   Test,
   TestAnnotation,
   TestAnnotationLocation,
+  TestAnnotationMetadata,
   TestAPI,
   TestAttachment,
   TestContext,

packages/runner/src/types/tasks.ts

@@ -286,9 +286,11 @@ export interface Test<ExtraContext = object> extends TaskPopulated {
 }
 
 export interface TestAttachment {
+  name?: string
   contentType?: string
   path?: string
   body?: string | Uint8Array
+  metadata?: Record<string, unknown>
 }
 
 export interface TestAnnotationLocation {
@@ -297,11 +299,23 @@ export interface TestAnnotationLocation {
   file: string
 }
 
+export interface TestAnnotationMetadata {
+  'internal:toMatchScreenshot'?: {
+    kind: string
+  }
+  [key: string]: unknown
+}
+
 export interface TestAnnotation {
+  title?: string
   message: string
   type: string
   location?: TestAnnotationLocation
   attachment?: TestAttachment
+  /** @experimental */
+  attachments?: TestAttachment[]
+  /** @experimental */
+  metadata?: TestAnnotationMetadata
 }
 
 export type Task = Test | Suite | File
@@ -703,6 +717,8 @@ export interface TestContext {
    * @see {@link https://vitest.dev/guide/test-context#annotate}
    */
   readonly annotate: {
+    /** @experimental */
+    (annotation: Omit<TestAnnotation, 'location'>): Promise<TestAnnotation>
     (message: string, type?: string, attachment?: TestAttachment): Promise<TestAnnotation>
     (message: string, attachment?: TestAttachment): Promise<TestAnnotation>
   }