開始使用

概觀

Vitest 是一個由 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 1.0 需要 Vite >=v5.0.0 和 Node >=v18.0.0

建議您採用上述任一方法，在 package.json 中安裝 vitest。如果您希望直接執行 vitest，可以使用 npx vitest（npx 命令隨附於 npm 和 Node.js）。

預設情況下，npx 會檢查命令是否存在於 $PATH 或本機專案的二進位檔案中，並執行該命令。如果找不到命令，則會在執行前自動安裝。

編寫測試

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

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

// sum.test.js
import { expect, test } from 'vitest';
import { sum } from './sum';

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

若要深入了解 Vitest 的使用方式，請參閱 API 章節。

配置 Vitest

Vitest 的主要優勢之一，在於它與 Vite 採用統一配置。如果存在 vite.config.ts，vitest 會讀取此根目錄檔案，以符合您 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: {
    // ...
  },
});

請參閱 配置參考 中的配置選項列表

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 setup。

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  // you can use a list of glob patterns to define your workspaces
  // Vitest expects a list of config files
  // or directories where there is a config file
  'packages/*',
  'tests/*/vitest.config.{e2e,unit}.ts',
  // you can even run the same tests,
  // but with different configs in the same "vitest" process
  {
    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 scripts 中的 vitest 二進位檔案，或使用 npx vitest 直接執行。以下是預設的 Vitest 專案中的預設 npm 指令碼：

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

若要執行單次測試，而不監看檔案變更，請使用 vitest run。 您可以指定其他 CLI 選項，例如 --port 或 --https。如需完整的 CLI 選項清單，請在您的專案中執行 npx vitest --help。

了解更多有關 命令列介面

IDE 整合

我們也為 Visual Studio Code 提供官方擴充功能，以提升您使用 Vitest 的測試體驗。

從 VS Code Marketplace 安裝

了解更多有關 IDE 整合

範例

範例	來源	Playground
basic	GitHub	Play Online
fastify	GitHub	Play Online
lit	GitHub	Play Online
marko	GitHub	Play Online
preact	GitHub	Play Online
react	GitHub	Play Online
solid	GitHub	Play Online
sveltekit	GitHub	Play Online
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

使用未發布的版本

如果您想搶先體驗最新功能，需要將 vitest repo 克隆到本機，然後自行建置並連結（需要 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 與社群交流。