Skip to content

docs(reporters): .vitest results directory convention #9993

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AriPerkkio wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(reporters): .vitest results directory convention #9993

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/guide/advanced/reporters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,29 @@ class MyReporter implements Reporter {
}
```

## Storing artifacts on file system

If your custom reporter needs to store any artifacts on file system it should place them inside `.vitest` directory. This directory is a convention that Vitest reporters and third party integrations can use to co-locate their results in a single directory. This way users of your custom reporter do not need to add multiple exclusion in their `.gitignore`. Only the `.vitest` is needed.
Copy link
Copy Markdown
Member

@sheremet-va sheremet-va Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we make it simpler for custom reporters to use this convention by exposing utilities on something like vitest.report?

  • vitest.report.writeFile
  • vitest.report.deleteFile
  • vitest.report.readFile

It accepts a file relative to .vitest folder. If .vitest folder doesn't exist, we create it. This could also be useful for internal reporters.

Copy link
Copy Markdown
Member Author

@AriPerkkio AriPerkkio Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good - anything to make it easier for users to follow these guidelines.

Maybe it something like:

// Automatically creates `<root>/.vitest` and `.vitest/my-yaml-reporter`.
// All actions are scoped to `.vitest/my-yaml-reporter`.
// resultWriter cannot remove '.vitest'.
const resultWriter = vitest.report.createResultWriter("my-yaml-reporter");

// Removes and re-creates `.vitest/my-yaml-reporter`.
resultWriter.clean();

// Writes `.vitest/my-yaml-reporter/result.yml`.
resultWriter.write("- key: value", "result.yml");

// Reads `.vitest/my-yaml-reporter/result.yml`.
resultWriter.read("result.yml");

// Deletes `.vitest/my-yaml-reporter/result.yml`.
resultWriter.delete("result.yml");

Copy link
Copy Markdown
Member

@sheremet-va sheremet-va Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good


Reporters and other integrations should respect following rules around `.vitest` directory:

- `.vitest` directory is placed in [the `root` of the project](/config/root)
- Reporter can create `.vitest` directory if it does not already exist
- Reporter should never remove `.vitest` directory
- Reporter should create their own directory inside `.vitest`, for example `.vitest/yaml-reporter/`
- Reporter can remove their own specific directory inside `.vitest`, for example `.vitest/yaml-reporter/`

```ansi
.vitest
│
├── yaml-reporter
│ ├── results.yaml
│ └── summary.yaml
│
└── junit-reporter
└── report.xml
```

Comment on lines +75 to +97
Copy link
Copy Markdown
Member Author

@AriPerkkio AriPerkkio Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://deploy-preview-9993--vitest-dev.netlify.app/guide/advanced/reporters.html#storing-artifacts-on-file-system

## Exported Reporters

`vitest` comes with a few [built-in reporters](/guide/reporters) that you can use out of the box.
Expand Down
7 changes: 7 additions & 0 deletions docs/guide/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,13 @@ It is recommended that you install a copy of `vitest` in your `package.json`, us

The `npx` tool will execute the specified command. By default, `npx` will first check if the command exists in the local project's binaries. If it is not found there, `npx` will look in the system's `$PATH` and execute it if found. If the command is not found in either location, `npx` will install it in a temporary location prior to execution.

Vitest and third party integrations can use `.vitest` directory to store generated artifacts. It's recommended to add this in your `.gitignore`.

``` sh [.gitignore]
# Vitest reports and artifacts
.vitest/
```

Comment on lines +46 to +52
Copy link
Copy Markdown
Member Author

@AriPerkkio AriPerkkio Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://deploy-preview-9993--vitest-dev.netlify.app/guide/#adding-vitest-to-your-project

## Writing Tests

As an example, we will write a simple test that verifies the output of a function that adds two numbers.
Expand Down
Loading