快速入门

概述

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 将在执行前将其安装到临时位置。

编写测试

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

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

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 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.config 文件中定义项目的文件和文件夹列表。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      // 你可以使用 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	在线体验
projects	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 联系社区。