快速开始

概述

Vitest 是一个由 Vite 驱动的快速单元测试框架。

你可以在 为什么选择 Vitest 章节了解更多关于该项目背后的设计理念。

在线体验 Vitest

你可以在 StackBlitz 上体验 Vitest 的在线版本。它直接在浏览器中运行 Vitest，与本地环境几乎完全一致，无需在本地机器上安装任何依赖。

将 Vitest 添加到你的项目

通过视频学习如何安装

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

TIP

Vitest 需要 Vite >=v3.0.0 和 Node >=v14.18

建议在你的 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);
});

接下来，为了执行测试，将以下内容添加到你的 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 (transform 23ms, setup 0ms, collect 16ms, tests 2ms, environment 0ms, prepare 106ms)

要了解更多关于 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
graphql	GitHub	Play Online
image-snapshot	GitHub	Play Online
lit	GitHub	Play Online
mocks	GitHub	Play Online
nextjs	GitHub	Play Online
playwright	GitHub
puppeteer	GitHub
react-enzyme	GitHub	Play Online
react-mui	GitHub	Play Online
react-storybook	GitHub	Play Online
react-testing-lib-msw	GitHub	Play Online
react-testing-lib	GitHub	Play Online
react	GitHub	Play Online
ruby	GitHub	Play Online
solid	GitHub	Play Online
svelte	GitHub	Play Online
vitesse	GitHub	Play Online
vue-jsx	GitHub	Play Online
vue	GitHub	Play Online
vue2	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 上联系社区。