快速开始

概述

Vitest 是一个由 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 1.0 需要 Vite >=v5.0.0 和 Node >=v18.0.0

建议在你的 package.json 文件中安装 vitest。当然，如果你更喜欢直接运行 vitest，可以使用 npx vitest（npx 命令随 npm 和 Node.js 一起提供）。

npx 命令会从本地 node_modules/.bin 目录执行命令，并自动安装运行所需的依赖包。默认情况下，npx 会检查命令是否存在于 $PATH 环境变量或本地项目依赖中，如果未找到，则会在执行前自动安装。

编写测试

作为示例，我们将编写一个简单的测试，验证一个将两个数字相加的函数的输出。

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

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

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

要了解更多关于 Vitest 的使用，请参阅 API 章节。

配置 Vitest

Vitest 的一个主要优势是与 Vite 共享统一的配置。如果存在 vite.config.ts 文件，vitest 会读取该文件，以便与你的 Vite 应用使用相同的插件和配置。例如，Vite 的 resolve.alias 和 plugins 配置可以直接使用，无需额外配置。如果你需要在测试环境中使用不同的配置，可以采用以下方法：

• 创建 vitest.config.ts，它的优先级更高
• 将 --config 选项传递给 CLI，例如 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，请在你的 Vite 配置中添加 test 属性。你还需要在你的配置文件的顶部使用 三斜线指令 添加对 Vitest 类型的引用。

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

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

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

WARNING

如果你决定为 Vite 和 Vitest 使用不同的配置文件，请确保在 Vitest 的配置文件中定义与 Vite 相同的配置项，因为 Vitest 的配置会覆盖 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。

了解更多关于 命令行界面

IDE 集成

我们为 Visual Studio Code 提供了官方扩展，以增强使用 Vitest 的测试体验。

从 VS Code Marketplace 安装

了解更多关于 IDE 集成

示例

示例	源码	在线演示
basic	GitHub	Play Online
fastify	GitHub	Play Online
lit	GitHub	Play Online
marko	GitHub	Play Online
preact	GitHub	Play Online
react	GitHub	Play Online
solid	GitHub	Play Online
sveltekit	GitHub	Play Online
typecheck	GitHub	Play Online
workspace	GitHub	Play Online

使用 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

使用未发布的提交

如果你希望提前体验最新的功能，你需要克隆 vitest repo 到你的本地机器，然后自己构建和链接它（需要 pnpm）：

git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # you can use your preferred package manager for this step # 你可以在此步骤中使用你喜欢的包管理器

然后转到你正在使用 Vitest 的项目并运行 pnpm link --global vitest（或者你用于全局链接 vitest 的包管理器）。

社区

如果你有问题或需要帮助，请在 Discord 和 GitHub Discussions 上联系社区。