入门

概述

Vitest（发音为 "veetest"）是一个由 Vite 提供支持的下一代测试框架。

你可以在为什么选择 Vitest部分了解更多关于该项目的背景和设计理念。

在线体验 Vitest

你可以在 StackBlitz 上在线体验 Vitest。它直接在浏览器中运行 Vitest，功能与本地环境几乎相同，且无需在你的机器上安装任何东西。

将 Vitest 添加到你的项目

通过视频学习安装方法

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

TIP

Vitest 需要 Vite >=v5.0.0 和 Node >=v18.0.0。

推荐使用上述方法之一，在 package.json 中安装 vitest。如果你更倾向于直接运行 vitest，可以使用 npx vitest（npx 工具随 npm 和 Node.js 一起提供）。

npx 工具会执行指定的命令。默认情况下，npx 会首先检查命令是否存在于本地项目的二进制文件中。如果未找到，npx 将在系统的 $PATH 中查找并执行。如果在这两个位置都未找到命令，npx 将在执行前将其安装到临时位置。

编写测试

举个例子，我们将编写一个简单的测试，用于验证一个将两个数字相加的函数的输出。

// sum.js
export function sum(a, b) {
  return a + b;
}

// sum.test.js
import { expect, test } from 'vitest';
import { sum } from './sum.js';

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

TIP

默认情况下，测试文件名必须包含 ".test." 或 ".spec."。

接下来，为了执行测试，请在你的 package.json 中添加以下内容：

{
  "scripts": {
    "test": "vitest"
  }
}

最后，根据你使用的包管理器，运行 npm run test、yarn test 或 pnpm test，Vitest 将打印以下消息：

✓ sum.test.js (1)
  ✓ adds 1 + 2 to equal 3

Test Files  1 passed (1)
     Tests  1 passed (1)
  Start at  02:15:44
  Duration  311ms

WARNING

如果你使用 Bun 作为包管理器，请确保使用 bun run test 命令而不是 bun test，否则 Bun 将运行其自己的测试运行器。

了解更多关于 Vitest 的用法，请参阅 API 部分。

配置 Vitest

Vitest 的主要优点之一是它与 Vite 的统一配置。如果存在，Vitest 将读取你的根 vite.config.ts，以匹配你的 Vite 应用程序的插件和设置。例如，你的 Vite resolve.alias 和 plugins 配置将开箱即用。如果你想在测试期间使用不同的配置，可以选择以下方法：

• 创建 vitest.config.ts，它将具有更高的优先级。
• 向 CLI 传递 --config 选项，例如 vitest --config ./path/to/vitest.config.ts。
• 使用 process.env.VITEST 或 defineConfig 上的 mode 属性（如果未被覆盖，该属性将设置为 test），在 vite.config.ts 中有条件地应用不同的配置。

Vitest 支持与 Vite 相同的配置文件扩展名：.js、.mjs、.cjs、.ts、.cts、.mts。Vitest 不支持 .json 扩展名。

如果你不使用 Vite 作为构建工具，你可以使用配置文件中的 test 属性来配置 Vitest：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ...
  },
});

TIP

即使你没有直接使用 Vite，Vitest 仍然严重依赖它的转换管道。因此，你也可以配置 Vite 文档中描述的任何属性。

如果你已经在使用 Vite，请在你的 Vite 配置中添加 test 属性。你还需要在配置文件顶部使用三斜杠指令添加对 Vitest 类型的引用。

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ...
  },
});

<reference types="vitest" /> 将在 Vitest 3 中停止工作，但你可以在 Vitest 2.1 中开始迁移到 vitest/config：

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... 在此处指定选项。
  },
});

请参阅配置参考中的配置选项列表。

WARNING

如果你决定为 Vite 和 Vitest 使用两个单独的配置文件，请确保在你的 Vitest 配置文件中定义相同的 Vite 选项，因为它会覆盖你的 Vite 文件，而不是对其进行扩展。你还可以使用 vite 或 vitest/config 条目中的 mergeConfig 方法将 Vite 配置与 Vitest 配置合并：

vitest.config.mjs

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config.mjs';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // ...
    },
  })
);

vite.config.mjs

import { defineConfig } from 'vite';
import Vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [Vue()],
});

但是，我们建议将 Vite 和 Vitest 的配置放在同一个文件中，而不是创建两个单独的文件。

工作区支持

使用 Vitest 工作区在同一个项目中运行不同的项目配置。你可以在 vitest.workspace 文件中定义一个文件和文件夹列表来定义你的工作区。该文件支持 .js、.ts、.json 扩展名。此功能非常适用于 monorepo 设置。

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  // 你可以使用 glob 模式列表来定义你的工作区
  // Vitest 期望一个配置文件列表
  // 或包含配置文件的目录
  'packages/*',
  'tests/*/vitest.config.{e2e,unit}.ts',
  // 你甚至可以在同一个 "vitest" 进程中运行相同的测试，
  // 但使用不同的配置。
  {
    test: {
      name: 'happy-dom',
      root: './shared_tests',
      environment: 'happy-dom',
      setupFiles: ['./setup.happy-dom.ts'],
    },
  },
  {
    test: {
      name: 'node',
      root: './shared_tests',
      environment: 'node',
      setupFiles: ['./setup.node.ts'],
    },
  },
]);

命令行界面

在安装了 Vitest 的项目中，你可以在 npm 脚本中使用 vitest 可执行文件，或者直接使用 npx vitest 运行它。以下是脚手架 Vitest 项目中的默认 npm 脚本：

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

要运行一次测试而不监听文件变化，请使用 vitest run。 你可以指定额外的 CLI 选项，例如 --port 或 --https。有关 CLI 选项的完整列表，请在你的项目中运行 npx vitest --help。

了解更多关于命令行界面的信息。

自动依赖安装

如果某些依赖项尚未安装，Vitest 将提示你安装。你可以通过设置 VITEST_SKIP_INSTALL_CHECKS=1 环境变量来禁用此行为。

IDE 集成

我们为 Visual Studio Code 提供了官方扩展，以提升你的 Vitest 测试体验。

从 VS Code Marketplace 安装

了解更多关于 IDE 集成

示例

示例	来源	在线体验
basic	GitHub	在线体验
fastify	GitHub	在线体验
in-source-test	GitHub	在线体验
lit	GitHub	在线体验
vue	GitHub	在线体验
marko	GitHub	在线体验
preact	GitHub	在线体验
react	GitHub	在线体验
solid	GitHub	在线体验
svelte	GitHub	在线体验
sveltekit	GitHub	在线体验
profiling	GitHub	不可用
typecheck	GitHub	在线体验
workspace	GitHub	在线体验

使用 Vitest 的项目

• unocss
• unplugin-auto-import
• unplugin-vue-components
• vue
• vite
• vitesse
• vitesse-lite
• fluent-vue
• vueuse
• milkdown
• gridjs-svelte
• spring-easing
• bytemd
• faker
• million
• Vitamin
• neodrag
• svelte-multiselect
• iconify
• tdesign-vue-next
• cz-git

使用未发布的提交

主分支上的每次提交以及带有 cr-tracked 标签的 PR 都会发布到 pkg.pr.new。你可以通过运行 npm i https://pkg.pr.new/vitest@{commit} 来安装它。

如果你想在本地测试自己的修改，可以自行构建并建立链接（需要 pnpm）：

git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # 你可以使用你惯用的包管理器来完成这一步

然后进入你使用 Vitest 的项目，运行 pnpm link --global vitest（或者你用来全局链接 vitest 的包管理器）。

社区

如果你有问题或需要帮助，请通过 Discord 和 GitHub Discussions 向社区寻求帮助。