開始使用

概述

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 會在執行前將其安裝到暫存位置。

編寫測試

舉例來說，我們將編寫一個簡單的測試，以驗證一個將兩個數字相加的函數的輸出。

// 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.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 配置中添加 test 屬性。您還需要在配置檔案的頂部使用 三斜線指示詞 引用 Vitest 的類型。

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

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

<reference types="vitest" /> 將在 Vitest 3 中失效，但您可以在 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 工作區 在同一專案中執行不同的配置。您可以在 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 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	線上體驗
workspace	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

使用未發布的提交

主分支上的每個 commit 以及帶有 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 與社群聯繫。