> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/getting-started/other-frameworks/vitest/your-first-vitest-run.md).

# Your First Vitest Run

Running Vitest tests with Currents dashboard

Vitest doesn't have a dedicated Currents reporter. Instead, Vitest writes a JUnit XML report using its built-in `junit` reporter, and [@currents/cmd](https://docs.currents.dev/resources/reporters/currents-cmd.md) converts and uploads it to Currents.

## Prerequisites

<details>

<summary>Create an Organization and a Project</summary>

After signing up for the dashboard service, you will be prompted to create a new organization and a project. You can change their names later.

<img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2FOa9kh3RUY3BB5TbSjpwV%2Fcurrents-create-org.gif?alt=media&amp;token=8ec9db10-946e-48c9-ab3f-27726712e272" alt="Creating an Organization and a Project in Currents dashboard" data-size="original">

After creating a new organization and a project, you'll see on-screen instructions with your newly created **Project ID** and **Record Key.**

</details>

<details>

<summary>Install @currents/cmd package</summary>

```bash
npm install @currents/cmd --save-dev
```

</details>

<details>

<summary>Enable the JUnit reporter</summary>

**Option 1**: Update the Vitest configuration file:

{% code title="vitest.config.js" %}

```javascript
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    reporters: ["default", "junit"],
    outputFile: {
      junit: "./results.xml",
    },
  },
});
```

{% endcode %}

**Option 2**: Pass the reporter as an argument when executing Vitest.

{% code title="package.json" %}

```json
{
  ...
  "scripts": {
    ...
    "test": "vitest run --reporter=default --reporter=junit --outputFile.junit=./results.xml",
  },
  ...
}
```

{% endcode %}

See [Vitest reporters documentation](https://vitest.dev/guide/reporters#junit-reporter) for the full list of the JUnit reporter options.

</details>

<details>

<summary>Update your .gitignore</summary>

Add the converted reports directory and the JUnit XML file to your .gitignore to avoid pushing temporary generated reports to your repository.

```
.currents
results.xml
```

</details>

## Your First Vitest Run

#### Step 1: Run the tests

```sh
npx vitest run
```

If you passed the reporter in the `test` script (Option 2), run `npm test` instead.

Vitest saves the JUnit XML report at the location configured by `outputFile.junit` - `./results.xml` in the examples above.

#### Step 2: Convert and upload the results

Run `currents run upload` with `--input-format junit` to convert the JUnit XML report to the Currents format and send it to the Currents dashboard (see [Upload JUnit XML reports](https://docs.currents.dev/resources/reporters/currents-cmd/currents-convert.md)). Set `--framework-version` to the Vitest version you're running.

```sh
npx currents run upload \
  --key=XXX \
  --project-id=YYY \
  --input-format=junit \
  --input-file=./results.xml \
  --framework=vitest \
  --framework-version=v3.2.4
```

Set the [**Record Key**](https://docs.currents.dev/guides/record-key.md) and [**Project ID**](https://docs.currents.dev/dashboard/projects/project-settings.md) obtained from Currents dashboard in the previous step.

## Explore Your First Run

The execution results will show on the Currents dashboard. A link to the run is printed when the upload completes.

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2FoeTzRHuIVtdrzzYPH1wn%2Fimage.png?alt=media&amp;token=91f8ed20-bbbf-4eff-9efa-7810c0d198bb" alt=""><figcaption><p>A link to the recorded results</p></figcaption></figure>

## Good To Know

`vitest run` exits with a non-zero code when tests fail, which stops a CI job before the results are converted and uploaded. Run the conversion and upload steps unconditionally - see [Vitest - GitHub Actions](https://docs.currents.dev/getting-started/other-frameworks/vitest/ci-setup/vitest-github-actions.md) for an example.

## Example

Check out the [Vitest example](https://github.com/currents-dev/currents-junit-xml-example/tree/main/packages/vitest) in the JUnit XML example repository.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.currents.dev/getting-started/other-frameworks/vitest/your-first-vitest-run.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
