Skip to content
Vitest 3
Main Navigation Guide & APIConfigBrowser ModeAdvanced API
3.2.0
2.1.9
1.6.1
0.34.6

English

简体中文
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

English

简体中文
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

Appearance

Sidebar Navigation

Introduction

Why Vitest

Getting Started

Features

Config Reference

API

Test API Reference

Mock Functions

Vi Utility

Expect

ExpectTypeOf

Assert

AssertType

Guides

CLI

Test Filtering

Test Projects

Reporters

Coverage

Snapshot

Mocking

Parallelism

Testing Types

Vitest UI

In-Source Testing

Test Context

Test Annotations

Environment

Extending Matchers

IDE Integration

Debugging

Common Errors

Migration Guide

Migrating to Vitest 3.0

Migrating from Jest

Performance

Profiling Test Performance

Improving Performance

Browser Mode

Node API Reference

Comparisons

On this page

Test Annotations ​

Vitest supports annotating your tests with custom messages and files via the context.annotate API. These annotations will be attached to the test case and passed down to reporters in the onTestAnnotate hook.

ts
test('hello world', async ({ annotate }) => {
  await annotate('this is my test');

  if (condition) {
    await annotate("this should've errored", 'error');
  }

  const file = createTestSpecificFile();
  await annotate('creates a file', { body: file });
});

WARNING

The annotate function returns a Promise, so it needs to be awaited if you rely on it somehow. However, Vitest will also automatically await any non-awaited annotation before the test finishes.

Depending on your reporter, you will see these annotations differently.

Built-in Reporters ​

default ​

The default reporter prints annotations only if the test has failed:

  ⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯

  FAIL  example.test.js > an example of a test with annotation
Error: thrown error
  ❯ example.test.js:11:21
      9 |    await annotate('annotation 1')
      10|    await annotate('annotation 2', 'warning')
      11|    throw new Error('thrown error')
        |          ^
      12|  })

  ❯ example.test.js:9:15 notice
    ↳ annotation 1
  ❯ example.test.js:10:15 warning
    ↳ annotation 2

  ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯

verbose ​

In a TTY terminal, the verbose reporter works similarly to the default reporter. However, in a non-TTY environment, the verbose reporter will also print annotations after every test.

✓ example.test.js > an example of a test with annotation

  ❯ example.test.js:9:15 notice
    ↳ annotation 1
  ❯ example.test.js:10:15 warning
    ↳ annotation 2

html ​

The HTML reporter shows annotations the same way the UI does. You can see the annotation on the line where it was called. At the moment, if the annotation wasn't called in a test file, you cannot see it in the UI. We are planning to support a separate test summary view where it will be visible.

Vitest UIVitest UI

junit ​

The junit reporter lists annotations inside the testcase's properties tag. The JUnit reporter will ignore all attachments and will print only the type and the message.

xml
<testcase classname="basic/example.test.js" name="an example of a test with annotation" time="0.14315">
    <properties>
        <property name="notice" value="the message of the annotation">
        </property>
    </properties>
</testcase>

github-actions ​

The github-actions reporter will print the annotation as a notice message by default. You can configure the type by passing down the second argument as notice, warning or error. If type is none of these, Vitest will show the message as a notice.

GitHub ActionsGitHub Actions

tap ​

The tap and tap-flat reporters print annotations as diagnostic messages on a new line starting with a # symbol. They will ignore all attachments and will print only the type and message:

ok 1 - an example of a test with annotation # time=143.15ms
    # notice: the message of the annotation
Pager
Previous pageTest Context
Next pageEnvironment

Released under the MIT License.

Copyright (c) 2021-Present Vitest Team

https://vitest.dev/guide/test-annotations

Released under the MIT License.

Copyright (c) 2021-Present Vitest Team