Vitest 2

繁體中文

English
简体中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

繁體中文

English
简体中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

外觀

命令列介面 ​

命令 ​

vitest ​

在目前目錄中啟動 Vitest。在開發環境中會自動進入監看模式，而在 CI 環境中則會自動進入執行模式。

您可以傳遞額外參數作為要執行的測試檔案篩選條件。例如：

bash
vitest foobar

將僅執行路徑中包含 foobar 的測試檔案。此篩選條件僅檢查包含性，不支援正規表達式或 glob 模式（除非您的終端機在 Vitest 接收篩選條件之前已處理）。

vitest run ​

執行單次測試，不進入監看模式。

vitest watch ​

執行所有測試套件，並監看變更。當檔案變更時，會重新執行測試。此命令與不帶參數呼叫 vitest 的效果相同。在 CI 環境中會回退到 vitest run。

vitest dev ​

vitest watch 的別名。

僅執行涵蓋指定來源檔案列表的測試。適用於靜態匯入（例如 import('./index.js') 或 import index from './index.js），但不適用於動態匯入（例如 import(filepath)）。所有檔案路徑都應相對於專案根資料夾。

適用於與 lint-staged 或您的 CI 設定搭配使用。

bash
vitest related /src/index.ts /src/hello-world.js

TIP

請注意，Vitest 預設會啟用監看模式執行。如果您使用 lint-staged 等工具，則應同時傳遞 --run 選項，以便命令能夠正常結束。

js
// .lintstagedrc.js
export default {
  '*.{js,ts}': 'vitest related --run',
};

vitest bench ​

僅執行用於比較效能結果的基準測試。

vitest init ​

vitest init <name> 可用於設定專案配置。目前，它僅支援 browser 值：

bash
vitest init browser

vitest list ​

vitest list 命令繼承所有 vitest 選項，用於列印所有匹配測試的列表。此命令會忽略 reporters 選項。預設情況下，它將列印所有符合檔案篩選器和名稱模式的測試名稱：

shell
vitest list filename.spec.ts -t="some-test"
txt
describe > some-test
describe > some-test > test 1
describe > some-test > test 2

您可以傳遞 --json 旗標，以 JSON 格式列印測試或將其儲存到獨立檔案中：

bash
vitest list filename.spec.ts -t="some-test" --json=./file.json

如果 --json 旗標未接收到值，它會將 JSON 輸出到標準輸出（stdout）。

您也可以傳遞 --filesOnly 旗標，以僅列印測試檔案：

bash
vitest list --filesOnly
txt
tests/test1.test.ts
tests/test2.test.ts

選項 ​

TIP

Vitest 支援 CLI 參數的駝峰式命名法和烤肉串式命名法。例如，--passWithNoTests 和 --pass-with-no-tests 都會生效（--no-color 和 --inspect-brk 為例外）。

Vitest 也支援不同的值指定方式：--reporter dot 和 --reporter=dot 皆為有效。

如果選項支援陣列值，您需要多次傳遞該選項：

vitest --reporter=dot --reporter=default

布林選項可以使用 no- 前綴來否定。將值指定為 false 也會生效：

vitest --no-api
vitest --api=false

root ​

  • CLI: -r, --root <path>
  • Config: root

專案根目錄。

config ​

  • CLI: -c, --config <path>

設定檔路徑。

update ​

  • CLI: -u, --update
  • Config: update

更新快照。

watch ​

  • CLI: -w, --watch
  • Config: watch

啟用觀察模式。

testNamePattern ​

執行名稱符合指定正規表達式模式的測試。

dir ​

  • CLI: --dir <path>
  • Config: dir

掃描測試檔案的基礎目錄。

ui ​

  • CLI: --ui
  • Config: ui

啟用使用者介面 (UI)。

open ​

  • CLI: --open
  • Config: open

自動開啟 UI (預設值: !process.env.CI)。

api.port ​

  • CLI: --api.port [port]

指定伺服器埠號。請注意，若埠號已被佔用，Vite 將自動嘗試下一個可用埠號，因此這可能不是伺服器最終監聽的實際埠號。若設為 true，將設定為 51204。

api.host ​

  • CLI: --api.host [host]

指定伺服器應監聽的 IP 位址。將此設為 0.0.0.0 或 true，以監聽所有位址，包括區域網路和公共位址。

api.strictPort ​

  • CLI: --api.strictPort

若設為 true，如果埠號已被佔用則退出，而非自動嘗試下一個可用埠號。

silent ​

靜默測試的控制台輸出。

hideSkippedTests ​

  • CLI: --hideSkippedTests

隱藏跳過測試的日誌。

reporters ​

指定報告器。

outputFile ​

當也指定了支援的報告器時，將測試結果寫入檔案。對於多個報告器的個別輸出，請使用 cac 的點表示法（範例：--outputFile.tap=./tap.txt）。

coverage.all ​

是否將所有檔案（包括未經測試的檔案）納入覆蓋率報告。

coverage.provider ​

選擇用於覆蓋率收集的工具，可用值為："v8"、"istanbul" 和 "custom"。

coverage.enabled ​

啟用覆蓋率收集。可以使用 --coverage CLI 選項覆寫（預設值: false）。

coverage.include ​

以 glob 模式包含在覆蓋率中的檔案。當使用多個模式時，可以指定多次（預設值: **）。

coverage.exclude ​

從覆蓋率中排除的檔案。當使用多個副檔名時，可以指定多次（預設值: 請參閱 coverage.exclude）。

coverage.extension ​

包含在覆蓋率中的副檔名。當使用多個副檔名時，可以指定多次（預設值: [".js", ".cjs", ".mjs", ".ts", ".mts", ".tsx", ".jsx", ".vue", ".svelte"]）。

coverage.clean ​

在執行測試前清除覆蓋率結果（預設值: true）。

coverage.cleanOnRerun ​

在觀察模式重新執行時清除覆蓋率報告（預設值: true）。

coverage.reportsDirectory ​

寫入覆蓋率報告的目錄（預設值: ./coverage）。

coverage.reporter ​

要使用的覆蓋率報告器。請參閱 coverage.reporter 以獲取更多資訊（預設值: ["text", "html", "clover", "json"]）。

coverage.reportOnFailure ​

即使測試失敗也生成覆蓋率報告（預設值: false）。

coverage.allowExternal ​

收集專案根目錄之外檔案的覆蓋率（預設值: false）。

coverage.skipFull ​

不顯示語句、分支和函數覆蓋率達到 100% 的檔案（預設值: false）。

coverage.thresholds.100 ​

將所有覆蓋率閾值設定為 100 的捷徑（預設值: false）。

coverage.thresholds.perFile ​

檢查每個檔案的閾值。請參閱 --coverage.thresholds.lines、--coverage.thresholds.functions、--coverage.thresholds.branches 和 --coverage.thresholds.statements 以獲取實際閾值（預設值: false）。

coverage.thresholds.autoUpdate ​

當當前覆蓋率高於配置的閾值時，更新配置檔案中的 "lines"、"functions"、"branches" 和 "statements" 閾值（預設值: false）。

coverage.thresholds.lines ​

  • CLI: --coverage.thresholds.lines <number>

行數覆蓋率閾值。請參閱 istanbuljs 以獲取更多資訊。此選項不適用於自訂提供者。

coverage.thresholds.functions ​

  • CLI: --coverage.thresholds.functions <number>

函數覆蓋率閾值。請參閱 istanbuljs 以獲取更多資訊。此選項不適用於自訂提供者。

coverage.thresholds.branches ​

  • CLI: --coverage.thresholds.branches <number>

分支覆蓋率閾值。請參閱 istanbuljs 以獲取更多資訊。此選項不適用於自訂提供者。

coverage.thresholds.statements ​

  • CLI: --coverage.thresholds.statements <number>

語句覆蓋率閾值。請參閱 istanbuljs 以獲取更多資訊。此選項不適用於自訂提供者。

coverage.ignoreClassMethods ​

要忽略覆蓋率的類別方法名稱陣列。請參閱 istanbuljs 以獲取更多資訊。此選項僅適用於 istanbul 提供者（預設值: []）。

coverage.processingConcurrency ​

處理覆蓋率結果時使用的並行限制。（預設值為 20 和 CPU 數量的最小值）。

coverage.customProviderModule ​

指定自訂覆蓋率提供者模組的名稱或路徑。請參閱 Custom Coverage Provider 以獲取更多資訊。此選項僅適用於自訂提供者。

coverage.watermarks.statements ​

  • CLI: --coverage.watermarks.statements <watermarks>

語句覆蓋率的高低水位線，格式為 <high>,<low>。

coverage.watermarks.lines ​

  • CLI: --coverage.watermarks.lines <watermarks>

行數覆蓋率的高低水位線，格式為 <high>,<low>。

coverage.watermarks.branches ​

  • CLI: --coverage.watermarks.branches <watermarks>

分支覆蓋率的高低水位線，格式為 <high>,<low>。

coverage.watermarks.functions ​

  • CLI: --coverage.watermarks.functions <watermarks>

函數覆蓋率的高低水位線，格式為 <high>,<low>。

mode ​

  • CLI: --mode <name>
  • Config: mode

覆寫 Vite 模式（預設值: test 或 benchmark）。

workspace ​

工作區設定檔的路徑。

isolate ​

獨立執行每個測試檔案。要禁用隔離，請使用 --no-isolate（預設值: true）。

globals ​

全域注入 API。

dom ​

  • CLI: --dom

使用 happy-dom 模擬瀏覽器 API。

browser.enabled ​

在瀏覽器中執行測試。等同於 --browser.enabled（預設值: false）。

browser.name ​

在特定瀏覽器中執行所有測試。某些瀏覽器僅適用於特定提供者（請參閱 --browser.provider）。請參閱 browser.name 以獲取更多資訊。

browser.headless ​

以無頭模式（即不開啟圖形使用者介面）執行瀏覽器。如果您在 CI 中執行 Vitest，它將預設啟用（預設值: process.env.CI）。

browser.api.port ​

指定伺服器埠號。請注意，若埠號已被佔用，Vite 將自動嘗試下一個可用埠號，因此這可能不是伺服器最終監聽的實際埠號。若設為 true，將設定為 63315。

browser.api.host ​

指定伺服器應監聽的 IP 位址。將此設為 0.0.0.0 或 true，以監聽所有位址，包括區域網路和公共位址。

browser.api.strictPort ​

若設為 true，如果埠號已被佔用則退出，而非自動嘗試下一個可用埠號。

browser.provider ​

用於執行瀏覽器測試的提供者。某些瀏覽器僅適用於特定提供者。可以是 "webdriverio"、"playwright"、"preview"，或自訂提供者的路徑。請參閱 browser.provider 以獲取更多資訊（預設值: "preview"）。

browser.providerOptions ​

傳遞給瀏覽器提供者的選項。請參閱 browser.providerOptions 以獲取更多資訊。

browser.isolate ​

獨立執行每個瀏覽器測試檔案。要禁用隔離，請使用 --browser.isolate=false（預設值: true）。

browser.ui ​

執行測試時顯示 Vitest UI（預設值: !process.env.CI）。

browser.fileParallelism ​

瀏覽器測試檔案是否應並行執行。使用 --browser.fileParallelism=false 禁用（預設值: true）。

pool ​

  • CLI: --pool <pool>
  • Config: pool

指定測試池，如果不在瀏覽器中執行（預設值: threads）。

poolOptions.threads.isolate ​

在執行緒池中隔離測試（預設值: true）。

poolOptions.threads.singleThread ​

在單一執行緒內執行測試（預設值: false）。

poolOptions.threads.maxThreads ​

執行測試的最大執行緒數或百分比。

poolOptions.threads.minThreads ​

執行測試的最小執行緒數或百分比。

poolOptions.threads.useAtomics ​

使用 Atomics 同步執行緒。這在某些情況下可以提高效能，但可能導致舊版 Node 中出現區段錯誤（預設值: false）。

poolOptions.vmThreads.isolate ​

在 VM 執行緒池中隔離測試（預設值: true）。

poolOptions.vmThreads.singleThread ​

在單一 VM 執行緒內執行測試（預設值: false）。

poolOptions.vmThreads.maxThreads ​

執行測試的最大 VM 執行緒數或百分比。

poolOptions.vmThreads.minThreads ​

執行測試的最小 VM 執行緒數或百分比。

poolOptions.vmThreads.useAtomics ​

使用 Atomics 同步 VM 執行緒。這在某些情況下可以提高效能，但可能導致舊版 Node 中出現區段錯誤（預設值: false）。

poolOptions.vmThreads.memoryLimit ​

VM 執行緒池的記憶體限制。如果您看到記憶體洩漏，請嘗試調整此值。

poolOptions.forks.isolate ​

在 forks 池中隔離測試（預設值: true）。

poolOptions.forks.singleFork ​

在單一子程序內執行測試（預設值: false）。

poolOptions.forks.maxForks ​

執行測試的最大程序數或百分比。

poolOptions.forks.minForks ​

執行測試的最小程序數或百分比。

poolOptions.vmForks.isolate ​

在 VM forks 池中隔離測試（預設值: true）。

poolOptions.vmForks.singleFork ​

在單一 VM 子程序內執行測試（預設值: false）。

poolOptions.vmForks.maxForks ​

執行測試的最大 VM 程序數或百分比。

poolOptions.vmForks.minForks ​

執行測試的最小 VM 程序數或百分比。

poolOptions.vmForks.memoryLimit ​

VM forks 池的記憶體限制。如果您看到記憶體洩漏，請嘗試調整此值。

fileParallelism ​

所有測試檔案是否應並行執行。使用 --no-file-parallelism 禁用（預設值: true）。

maxWorkers ​

執行測試的最大工作者數或百分比。

minWorkers ​

執行測試的最小工作者數或百分比。

environment ​

指定執行器環境，如果不在瀏覽器中執行（預設值: node）。

passWithNoTests ​

未找到測試時視為通過。

logHeapUsage ​

在 Node 中執行時顯示每個測試的堆積使用量。

allowOnly ​

允許標記為 only 的測試和套件（預設值: !process.env.CI）。

dangerouslyIgnoreUnhandledErrors ​

忽略所有未處理的錯誤。

sequence.shuffle.files ​

以隨機順序執行檔案。如果啟用此選項，長時間執行的測試將不會提早開始。（預設值: false）。

sequence.shuffle.tests ​

以隨機順序執行測試（預設值: false）。

sequence.concurrent ​

使測試並行執行（預設值: false）。

sequence.seed ​

設定隨機化種子。若 --sequence.shuffle 為假值，此選項將無效。請參閱 "Random Seed" 頁面 以獲取更多資訊。

sequence.hooks ​

更改 hook 的執行順序。接受的值為："stack"、"list" 和 "parallel"。請參閱 sequence.hooks 以獲取更多資訊（預設值: "parallel"）。

sequence.setupFiles ​

更改設定檔案的執行順序。接受的值為："list" 和 "parallel"。如果設定為 "list"，將按照定義的順序執行設定檔案。如果設定為 "parallel"，將並行執行設定檔案（預設值: "parallel"）。

inspect ​

  • CLI: --inspect [[host:]port]
  • Config: inspect

啟用 Node.js 偵測器（預設值: 127.0.0.1:9229）。

inspectBrk ​

啟用 Node.js 偵測器並在測試開始前中斷。

testTimeout ​

測試的預設逾時時間（毫秒）（預設值: 5000）。

hookTimeout ​

預設 hook 逾時時間（毫秒）（預設值: 10000）。

bail ​

  • CLI: --bail <number>
  • Config: bail

當指定數量的測試失敗時停止測試執行（預設值: 0）。

retry ​

  • CLI: --retry <times>
  • Config: retry

若測試失敗，重試指定次數（預設值: 0）。

diff ​

  • CLI: --diff <path>
  • Config: diff

用於生成差異介面的差異設定檔路徑。

exclude ​

  • CLI: --exclude <glob>
  • Config: exclude

要從測試中排除的額外檔案 glob 模式。

expandSnapshotDiff ​

快照失敗時顯示完整差異。

disableConsoleIntercept ​

禁用控制台日誌的自動攔截（預設值: false）。

typecheck.enabled ​

在測試同時啟用型別檢查（預設值: false）。

typecheck.only ​

僅執行型別檢查測試。這會自動啟用型別檢查（預設值: false）。

typecheck.checker ​

指定要使用的型別檢查器。可用值為："tsc" 和 "vue-tsc" 以及可執行檔的路徑（預設值: "tsc"）。

typecheck.allowJs ​

允許對 JavaScript 檔案進行型別檢查。預設情況下從 tsconfig.json 中獲取值。

typecheck.ignoreSourceErrors ​

忽略來自原始碼檔案的型別錯誤。

typecheck.tsconfig ​

自訂 tsconfig 檔案的路徑。

project ​

  • CLI: --project <name>
  • Config: project

若您使用 Vitest 工作區功能，要執行的專案名稱。這可以重複用於多個專案：--project=1 --project=2。您也可以使用萬用字元過濾專案，例如 --project=packages*。

slowTestThreshold ​

測試被視為慢速的閾值（毫秒）（預設值: 300）。

teardownTimeout ​

拆卸函數的預設逾時時間（毫秒）（預設值: 10000）。

maxConcurrency ​

套件中並行測試的最大數量（預設值: 5）。

expect.requireAssertions ​

要求所有測試至少有一個斷言。

expect.poll.interval ​

expect.poll() 斷言的輪詢間隔（毫秒）（預設值: 50）。

expect.poll.timeout ​

expect.poll() 斷言的輪詢逾時時間（毫秒）（預設值: 1000）。

printConsoleTrace ​

始終列印控制台堆疊追蹤。

run ​

  • CLI: --run

禁用觀察模式。

color ​

  • CLI: --no-color

從控制台輸出中移除顏色。

clearScreen ​

  • CLI: --clearScreen

在觀察模式下重新執行測試時清除終端螢幕（預設值: true）。

standalone ​

  • CLI: --standalone

啟動 Vitest 而不執行測試。檔案過濾器將被忽略，測試只會在變更時執行（預設值: false）。

changed ​

  • 類型：boolean | string
  • 預設：false

僅針對已變更的檔案執行測試。如果未提供值，它將針對未提交的變更（包括已暫存和未暫存的）執行測試。

若要針對上次提交中進行的變更執行測試，您可以使用 --changed HEAD~1。您也可以傳遞提交雜湊值（例如 --changed 09a9920）或分支名稱（例如 --changed origin/develop）。

與程式碼覆蓋率搭配使用時，報告將僅包含與變更相關的檔案。

如果與 forceRerunTriggers 配置選項搭配使用，只要 forceRerunTriggers 列表中至少有一個檔案發生變更，它就會執行整個測試套件。預設情況下，Vitest 配置檔案和 package.json 的變更將始終重新執行整個套件。

shard ​

  • 類型：string
  • 預設：disabled

要執行的測試套件分片，其格式為 <index>/<count>，其中：

  • count 是一個正整數，表示分割後的總部分數。
  • index 是一個正整數，表示分割後部分的索引。

此命令會將所有測試分成 count 個相等的部分，並且僅執行位於 index 部分的測試。例如，要將您的測試套件分成三部分，請使用：

sh
vitest run --shard=1/3
vitest run --shard=2/3
vitest run --shard=3/3

WARNING

您不能在啟用 --watch 的情況下使用此選項（預設在開發環境中啟用）。

TIP

如果 --reporter=blob 在未指定輸出檔案的情況下使用，預設路徑將包含目前的分片配置，以避免與其他 Vitest 處理程序發生衝突。

merge-reports ​

  • 類型： boolean | string

合併指定資料夾（預設為 .vitest-reports）中的所有 blob 報告。您可以將任何報告器與此命令搭配使用（blob 除外）：

sh
vitest --merge-reports --reporter=junit

[cac 的點表示法]：https://github.com/cacjs/cac#dot-nested-options

以 MIT 授權條款 發布。

版權所有 (c) 2021-Present Vitest Team

https://v2.vitest.dev/guide/cli