Overview of the Nx Vitest Plugin

Vitest is a fast unit test framework powered by Vite. It provides a modern testing experience with:

• Lightning fast test execution powered by Vite
• Native ESM, TypeScript, and JSX support out of the box
• Jest-compatible API for easy migration
• Smart instant watch mode
• Component testing for UI frameworks

Setting Up @nx/vitest

Installation

Keep Nx Package Versions In Sync

Make sure to install the @nx/vitest version that matches the version of nx in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can fix Nx version mismatches with this recipe.

In any Nx workspace, you can install @nx/vitest by running the following command:

nx add @nx/vitest

This will install the correct version of @nx/vitest.

How @nx/vitest Infers Tasks

Inferred Tasks

Since Nx 18, Nx plugins can infer tasks for your projects based on the configuration of different tools. You can read more about it at the Inferred Tasks concept page.

The @nx/vitest plugin will create a task for any project that has a Vitest configuration file present. Any of the following files will be recognized as a Vitest configuration file:

• vitest.config.js
• vitest.config.ts
• vitest.config.mjs
• vitest.config.mts
• vitest.config.cjs
• vitest.config.cts
• vite.config.js (with test configuration)
• vite.config.ts (with test configuration)
• vite.config.mjs (with test configuration)
• vite.config.mts (with test configuration)
• vite.config.cjs (with test configuration)
• vite.config.cts (with test configuration)

View Inferred Tasks

To view inferred tasks for a project, open the project details view in Nx Console or run nx show project my-project --web in the command line.

@nx/vitest Configuration

The @nx/vitest plugin is configured in the plugins array in nx.json.

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "options": {
        "testTargetName": "test"
      }
    }
  ]
}

• The testTargetName option controls the name of the inferred Vitest tasks. The default name is test.

Configuring @nx/vitest for both E2E and Unit Tests

While Vitest is most often used for unit tests, there are cases where it can be used for e2e tests as well as unit tests within the same workspace. In this case, you can configure the @nx/vitest plugin twice for the different cases.

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "exclude": ["e2e/**/*"],
      "options": {
        "testTargetName": "test"
      }
    },
    {
      "plugin": "@nx/vitest",
      "include": ["e2e/**/*"],
      "options": {
        "testTargetName": "e2e-local",
        "ciTargetName": "e2e-ci"
      }
    }
  ]
}

Splitting E2E Tests

Migrating from @nx/vite

In Nx 21 and earlier, Vitest task splitting was configured through @nx/vite/plugin. Starting with Nx 22, this functionality has moved to @nx/vitest. The @nx/vite plugin will have its Vitest features removed in Nx 23.

If Vitest is used to run E2E tests, you can enable splitting the tasks by file to get improved caching, distribution, and retrying flaky tests. Enable this Atomizer feature by providing a ciTargetName. This will create a target with that name which can be used in CI to run the tests for each file in a distributed fashion.

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "include": ["e2e/**/*"],
      "options": {
        "testTargetName": "e2e-local",
        "ciTargetName": "e2e-ci"
      }
    }
  ]
}

Customizing Atomized Tasks Group Name

By default, the atomized tasks group name is derived from the ciTargetName. For example, atomized tasks for the e2e-ci target will be grouped under the name "E2E (CI)" when displayed in Nx Cloud or nx show project <project> UI. You can customize that name by explicitly providing the optional ciGroupName plugin option:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "include": ["e2e/**/*"],
      "options": {
        "testTargetName": "e2e-local",
        "ciTargetName": "e2e-ci",
        "ciGroupName": "My E2E tests (CI)"
      }
    }
  ]
}

Using Vitest

Add Vitest to a Project

Run the configuration generator to add Vitest to an existing project:

nx g @nx/vitest:configuration --project=<project-name>

Hint: You can use the --dry-run flag to see what will be generated.

Replace <project-name> with the name of the project you're wanting to add Vitest to.

Testing Applications

The recommended way to run/debug Vitest tests is via an editor:

• VSCode Vitest Extension
• WebStorm

To run Vitest tests via Nx use:

nx test frontend

Testing Specific Files

You can test specific files by passing a pattern:

nx test frontend -- HomePage.spec.ts

Watching for Changes

Using the --watch flag will run the tests in watch mode:

nx test frontend --watch

Testing UI Mode

Vitest provides a UI for interacting with your tests. You can run tests in UI mode with:

nx test frontend --ui

Code Coverage

Enable code coverage with the --coverage flag:

nx test frontend --coverage

By default, coverage reports will be generated in the coverage/ directory under the project root.

Performance in CI

Typically, in CI it's recommended to use nx affected -t test --parallel=[# CPUs] for the best performance.

This allows Nx to run tests across multiple projects in parallel while leveraging caching to skip tests for unchanged projects.

Configurations

Vitest

Primary configurations for Vitest will be via the vitest.config.ts or vite.config.ts file that is generated for your project. Learn more about Vitest configurations.

Nx

The Nx task options can be configured via the project config file or via the command line flags.

If you're using inferred tasks, you can provide the Vitest args for the command you're running.

Migrating from @nx/vite

If you're currently using @nx/vite for Vitest testing, see the migration guide for instructions on switching to @nx/vitest.

More Documentation

• Vitest Docs