Vitest 3

繁體中文

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 3 起，您也可以透過檔案名稱和行號指定測試：

bash
$ vitest basic/foo.test.ts:10

WARNING

請注意，Vitest 需要完整的檔案名稱才能使此功能正常運作。它可以是相對於目前工作目錄的相對路徑，也可以是絕對檔案路徑。

bash
$ vitest basic/foo.js:10 # ✅
$ vitest ./basic/foo.js:10 # ✅
$ vitest /users/project/basic/foo.js:10 # ✅
$ vitest foo:10 # ❌
$ vitest ./basic/foo:10 # ❌

目前 Vitest 也不支援範圍：

bash
$ vitest basic/foo.test.ts:10, basic/foo.test.ts:25 # ✅
$ vitest basic/foo.test.ts:10-25 # ❌

vitest run ​

執行一次測試，不進入監控模式。

vitest watch ​

執行所有測試套件，但監控變更並在變更時重新執行測試。與不帶參數執行 vitest 相同。在 CI 或 stdin 不是 TTY（非互動式環境）時，將退回為 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
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 參數的駝峰式命名和連字號命名（kebab-case）。例如，--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 ​

  • CLI: --silent [value]
  • Config: silent

靜音測試的控制台輸出。使用 'passed-only' 僅顯示失敗測試的日誌。

hideSkippedTests ​

  • CLI: --hideSkippedTests

隱藏被跳過的測試日誌。

reporters ​

指定報告器（default, basic, blob, verbose, dot, json, tap, tap-flat, junit, hanging-process, github-actions）。

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 ​

指定自訂覆蓋率提供者模組的名稱或路徑。詳情請參閱 自訂覆蓋率提供者。此選項僅適用於自訂提供者。

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 ​

以無頭模式執行瀏覽器（即不開啟圖形使用者介面（GUI））。如果您在 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）。

browser.connectTimeout ​

如果連接到瀏覽器花費的時間過長，測試套件將失敗（預設值: 60_000）。

pool ​

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

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

poolOptions.threads.isolate ​

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

poolOptions.threads.singleThread ​

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

poolOptions.threads.maxThreads ​

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

poolOptions.threads.minThreads ​

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

poolOptions.threads.useAtomics ​

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

poolOptions.vmThreads.isolate ​

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

poolOptions.vmThreads.singleThread ​

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

poolOptions.vmThreads.maxThreads ​

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

poolOptions.vmThreads.minThreads ​

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

poolOptions.vmThreads.useAtomics ​

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

poolOptions.vmThreads.memoryLimit ​

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

poolOptions.forks.isolate ​

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

poolOptions.forks.singleFork ​

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

poolOptions.forks.maxForks ​

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

poolOptions.forks.minForks ​

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

poolOptions.vmForks.isolate ​

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

poolOptions.vmForks.singleFork ​

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

poolOptions.vmForks.maxForks ​

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

poolOptions.vmForks.minForks ​

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

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 為假值，此選項將無效。詳情請參閱 "隨機種子" 頁面。

sequence.hooks ​

更改掛鉤執行的順序。接受的值為：「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）。使用 0 完全停用超時。

hookTimeout ​

預設掛鉤超時時間（毫秒）（預設值: 10000）。使用 0 完全停用超時。

bail ​

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

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

retry ​

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

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

diff.aAnnotation ​

預期行的註釋（預設值: Expected）。

diff.aIndicator ​

預期行的指示符（預設值: -）。

diff.bAnnotation ​

接收行的註釋（預設值: Received）。

diff.bIndicator ​

接收行的指示符（預設值: +）。

diff.commonIndicator ​

共同行的指示符（預設值: ）。

diff.contextLines ​

在每個變更周圍顯示的上下文行數（預設值: 5）。

diff.emptyFirstOrLastLinePlaceholder ​

空的第一行或最後一行的佔位符（預設值: ""）。

diff.expand ​

展開所有共同行（預設值: true）。

diff.includeChangeCounts ​

在差異輸出中包含比較計數（預設值: false）。

diff.omitAnnotationLines ​

從輸出中省略註釋行（預設值: false）。

diff.printBasicPrototype ​

列印基本原型物件和陣列（預設值: true）。

diff.maxDepth ​

列印巢狀物件時遞迴的深度限制（預設值: 20）。

diff.truncateThreshold ​

在每個變更前後顯示的行數（預設值: 0）。

diff.truncateAnnotation ​

截斷行的註釋（預設值: ... Diff result is truncated）。

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 檔案的路徑。

typecheck.spawnTimeout ​

啟動型別檢查器所需的最小時間（毫秒）。

project ​

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

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

slowTestThreshold ​

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

teardownTimeout ​

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

maxConcurrency ​

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

expect.requireAssertions ​

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

expect.poll.interval ​

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

expect.poll.timeout ​

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

printConsoleTrace ​

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

includeTaskLocation ​

在 location 屬性中收集測試和套件的位置。

attachmentsDir ​

context.annotate 附件的儲存目錄（預設值: .vitest-attachments）。

run ​

  • CLI: --run

停用監控模式。

color ​

  • CLI: --no-color

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

clearScreen ​

  • CLI: --clearScreen

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

configLoader ​

  • CLI: --configLoader <loader>

使用 bundle 將設定與 esbuild 捆綁，或使用 runner（實驗功能）即時執行。此功能僅在 vite 6.1.0 及更高版本中可用（預設值: bundle）。

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

以 MIT 授權條款 發布。

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

https://vitest.dev/guide/cli