快速起步

总览

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

提示

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)
})

提示

一般情况下，执行测试的文件名中必须包含 .test. 或 .spec.。

接下来，为了执行测试，请将以下部分添加到你的 package.json 文件中：

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

警告

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

了解更多关于 Vitest 的使用，请参考 API 索引 部分。

配置 Vitest

Vitest 的主要优势之一是它与 Vite 的统一配置。如果存在，vitest 将读取你的根目录 vite.config.ts 以匹配插件并设置为你的 Vite 应用。例如，你的 Vite 有 resolve.alias 和 plugins 的配置将会在 Vitest 中开箱即用。如果你想在测试期间想要不同的配置，你可以:

• 创建 vitest.config.ts，优先级将会最高。
• 将 --config 选项传递给 CLI，例如 vitest --config ./path/to/vitest.config.ts。
• 在 defineConfig 上使用 process.env.VITEST 或 mode 属性（如果没有被覆盖，将设置为 test）有条件地在 vite.config.ts 中应用不同的配置。请注意，像任何其他环境变量一样，VITEST 也会在测试中的 import.meta.env 上暴露出来

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

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

vitest.config.ts

import { defineConfig } from 'vitest/config'

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

提示

即使你自己不使用 Vite，Vitest 的转换管道也严重依赖它。因此，你还可以配置 Vite 文档 中描述的任何属性。

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

vite.config.ts

/// <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 Vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

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

但我们建议 Vite 和 Vitest 使用相同的文件，而不是创建两个单独的文件。

多项目支持

通过 测试项目 功能，你可以在同一个项目里运行多套不同的配置。只需在 vitest.config 文件中列出对应的文件和文件夹，即可定义各个项目。

vitest.config.ts

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      // 你可以使用全局模式的列表来定义你的项目
      // 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 脚本：

package.json

{
  "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 插件市场进行安装

了解更多有关 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 社区来寻求帮助。