index.md

title
快速起步 | 指南

快速起步

总览

Vitest（发音为 "veetest"） 是由 Vite 驱动的下一代测试框架。

你可以在 为什么是 Vitest 中了解有关该项目背后的基本原理的更多信息。

在线试用 Vitest

你可以在 StackBlitz 上在线尝试 Vitest 。它直接在浏览器中运行 Vitest，它几乎与本地设置相同，但不需要在你的计算机上安装任何东西。

将 Vitest 安装到项目

通过视频了解如何安装

::: code-group

npm install -D vitest

yarn add -D vitest

pnpm add -D vitest

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 首先会检查命令是否存在于本地项目的 node_modules/.bin 中。如果没有找到，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 中开箱即用。如果你想在测试期间想要不同的配置，你可以:

• 创建 vitest.config.ts，优先级将会最高。
• 将 --config 选项传递给 CLI，例如 vitest --config ./path/to/vitest.config.ts。
• 在 defineConfig 上使用 process.env.VITEST 或 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 属性。你还需要使用 三斜杠指令 在你的配置文件的顶部引用。

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

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

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

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

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

可以参阅 配置索引 中的配置选项列表

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

:::code-group

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

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

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

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

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

支持工作空间

使用 Vitest Workspaces 在同一项目中运行不同的项目配置。你可以在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 插件市场进行安装

了解更多有关 IDE 插件 的更多信息

示例

Example	Source	Playground
basic	GitHub	Play Online
fastify	GitHub	Play Online
in-source-test	GitHub	Play Online
lit	GitHub	Play Online
vue	GitHub	Play Online
marko	GitHub	Play Online
preact	GitHub	Play Online
react	GitHub	Play Online
solid	GitHub	Play Online
svelte	GitHub	Play Online
sveltekit	GitHub	Play Online
profiling	GitHub	Not Available
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

使用未发布的功能

主分支上的每个提交和带有 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 社区来寻求帮助。