快速入門

概述

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，此檔案將具有更高的優先級。
• 將 --config 選項傳遞給 CLI，例如 vitest --config ./path/to/vitest.config.ts。
• 在 vite.config.ts 中，使用 process.env.VITEST 或 defineConfig 上的 mode 屬性（若未覆寫，將設定為 test）來有條件地套用不同的配置。

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 選項，因為 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.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 與社群交流。