命令列界面

命令

vitest

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

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

vitest foobar

只會執行路徑中包含 foobar 的測試檔案。此篩選器僅檢查是否包含，不支援正規表示式或 glob 模式（除非您的終端在 Vitest 收到篩選器之前處理它）。

vitest run

執行一次，不進入監聽模式。

vitest watch

執行所有測試套件，並監聽變更，在變更時重新執行測試。與不帶參數呼叫 vitest 相同。在 CI 環境中會自動切換到 vitest run。

vitest dev

vitest watch 的別名。

vitest related

僅執行針對一系列原始碼檔案的測試。適用於靜態引入（例如，import('./index.js') 或 import index from './index.js），但不適用於動態引入（例如，import(filepath)）。所有檔案都應該相對於根目錄。

可與 lint-staged 或您的 CI 設定一起使用。

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

TIP

別忘了 Vitest 預設是啟用監聽模式執行。如果您使用像 lint-staged 這樣的工具，您也應該傳遞 --run 選項，以便命令能夠正常結束。

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

vitest bench

僅執行 基準測試，比較效能結果。

選項

選項
-r, --root <path>	根路徑
-c, --config <path>	配置文件路徑
-u, --update	更新快照
-w, --watch	啟用監聽模式
-t, --testNamePattern <pattern>	執行名稱與指定正則表達式模式匹配的測試
--dir <path>	掃描測試檔案的基本目錄
--ui	啟用 UI
--open	自動開啟 UI (預設: !process.env.CI)
--api.port [port]	指定伺服器埠。請注意，如果埠已被佔用，Vite 會自動嘗試下一個可用埠，因此這可能不是伺服器最終監聽的實際埠。如果為 true，則設定為 51204
--api.host [host]	指定伺服器應偵聽的 IP 位址。設定為 0.0.0.0 或 true 以偵聽所有位址，包括 LAN 和公共位址
--api.strictPort	設定為 true，如果埠已被佔用，則退出，而不是自動嘗試下一個可用埠
--silent	靜默來自測試的控制台輸出
--hideSkippedTests	隱藏跳過的測試的日誌
--reporter <name>	指定報告器
--outputFile <filename/-s>	在指定支援的報告器時將測試結果寫入檔案, 使用 cac 的點表示法來表示多個報告器的各個輸出 (例如: --outputFile.tap=./tap.txt)
--coverage.all	是否包含所有檔案，包括未測試的檔案到報告中
--coverage.provider <name>	選擇用於覆蓋率收集的工具, 可用值為: "v8", "istanbul" 和 "custom"
--coverage.enabled	啟用覆蓋率收集。可以使用 --coverage 命令列選項覆蓋 (預設: false)
--coverage.include <pattern>	覆蓋率中包含的檔案，作為 glob 模式。使用多個模式時可以多次指定 (預設: **)
--coverage.exclude <pattern>	覆蓋率中排除的檔案。使用多個副檔名時可以多次指定 (預設: 訪問 coverage.exclude)
--coverage.extension <extension>	覆蓋率中包含的副檔名。使用多個副檔名時可以多次指定 (預設: [".js", ".cjs", ".mjs", ".ts", ".mts", ".cts", ".tsx", ".jsx", ".vue", ".svelte"])
--coverage.clean	在執行測試之前清除覆蓋率結果 (預設: true)
--coverage.cleanOnRerun	在監聽模式重新執行時清除覆蓋率報告 (預設: true)
--coverage.reportsDirectory <path>	將覆蓋率報告寫入的目錄 (預設: ./coverage)
--coverage.reporter <name>	要使用的覆蓋率報告器。訪問 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 <number>	行的閾值. 訪問 istanbuljs 獲取更多資訊. 此選項不適用於自定義提供程序
--coverage.thresholds.functions <number>	函式的閾值. 訪問 istanbuljs 獲取更多資訊. 此選項不適用於自定義提供程序
--coverage.thresholds.branches <number>	分支的閾值. 訪問 istanbuljs 獲取更多資訊. 此選項不適用於自定義提供程序
--coverage.thresholds.statements <number>	語句的閾值. 訪問 istanbuljs 獲取更多資訊. 此選項不適用於自定義提供程序
--coverage.ignoreClassMethods <name>	要忽略覆蓋率的類別方法名稱的陣列。訪問 istanbuljs 獲取更多資訊. 此選項僅適用於 istanbul 提供程序 (預設: [])
--coverage.processingConcurrency <number>	在處理覆蓋率結果時使用的並行限制. (預設值為 20 和 CPU 數量之間較小的值)
--coverage.customProviderModule <path>	指定自定義覆蓋率提供程序模組的模組名稱或路徑。訪問 自定義覆蓋率提供程序 獲取更多資訊. 此選項僅適用於自定義提供程序
--coverage.watermarks.statements <watermarks>	用於語句的高和低水位線，格式為 <high>,<low>
--coverage.watermarks.lines <watermarks>	用於行的高和低水位線，格式為 <high>,<low>
--coverage.watermarks.branches <watermarks>	用於分支的高和低水位線，格式為 <high>,<low>
--coverage.watermarks.functions <watermarks>	用於函式的高和低水位線，格式為 <high>,<low>
--mode <name>	覆蓋 Vite 模式 (預設: test 或 benchmark)
--workspace <path>	工作區配置檔案的路徑
--isolate	在隔離環境中執行每個測試檔案。要停用隔離，請使用 --no-isolate (預設: true)
--globals	全域注入 APIs
--dom	使用 happy-dom 模擬瀏覽器 API
--browser.enabled	在瀏覽器中執行測試。等同於 --browser.enabled (預設: false)
--browser.name <name>	在指定的瀏覽器中執行所有測試。某些瀏覽器僅適用於特定的 provider (請參閱 --browser.provider)。訪問 browser.name 以獲取更多資訊
--browser.headless	在無頭模式下執行瀏覽器（即不開啟 GUI (圖形使用者介面)）。如果你在 CI 中執行 Vitest，它預設會被啟用 (預設: process.env.CI)
--browser.api.port [port]	指定伺服器埠。請注意，如果埠已被佔用，Vite 會自動嘗試下一個可用埠，因此這可能不是伺服器最終監聽的實際埠。如果為 true，則設定為 63315
--browser.api.host [host]	指定伺服器應偵聽的 IP 位址。設定為 0.0.0.0 或 true 以偵聽所有位址，包括 LAN 和公共位址
--browser.api.strictPort	設定為 true，如果埠已被佔用，則退出，而不是自動嘗試下一個可用埠
--browser.provider <name>	用於執行瀏覽器測試的 Provider。某些瀏覽器僅適用於特定的 Provider。可以是 "webdriverio"、"playwright" 或自定義 Provider 的路徑。訪問 browser.provider 以獲取更多資訊 (預設: "webdriverio")
--browser.providerOptions <options>	傳遞給瀏覽器 provider 的選項。訪問 browser.providerOptions 以獲取更多資訊
--browser.slowHijackESM	讓 Vitest 在瀏覽器中使用它自己的模組解析，以啟用諸如 vi.mock 和 vi.spyOn 之類的 API。訪問 browser.slowHijackESM 以獲取更多資訊 (預設: false)
--browser.isolate	在隔離模式下執行每個瀏覽器測試檔案。要停用隔離，使用 --browser.isolate=false (預設: true)
--browser.fileParallelism	是否應該並行執行所有的測試檔案。使用 --browser.file-parallelism=false 來停用 (預設: 與 --file-parallelism 相同)
--pool <pool>	如果不在瀏覽器中執行, 則指定 pool (預設: threads)
--poolOptions.threads.isolate	在執行緒池中隔離測試 (預設: true)
--poolOptions.threads.singleThread	在單執行緒中執行測試
--poolOptions.threads.maxThreads <workers>	執行測試的最大執行緒數
--poolOptions.threads.minThreads <workers>	執行測試的最小執行緒數
--poolOptions.threads.useAtomics	使用 Atomics 同步執行緒。這可以在某些情況下提高效能，但可能會導致舊版本 Node 中的區段錯誤 (預設: false)
--poolOptions.vmThreads.isolate	在執行緒池中隔離測試 (預設: true)
--poolOptions.vmThreads.singleThread	在單執行緒中執行測試
--poolOptions.vmThreads.maxThreads <workers>	執行測試的最大執行緒數
--poolOptions.vmThreads.minThreads <workers>	執行測試的最小執行緒數
--poolOptions.vmThreads.useAtomics	使用 Atomics 同步執行緒。這可以在某些情況下提高效能，但可能會導致舊版本 Node 中的區段錯誤 (預設: false)
--poolOptions.vmThreads.memoryLimit <limit>	VM 執行緒集區的記憶體限制。如果您看到記憶體洩漏，請嘗試調整此值。
--poolOptions.forks.isolate	在 forks 池中隔離測試 (預設: true)
--poolOptions.forks.singleFork	在單個 child_process 中執行測試 (預設: false)
--poolOptions.forks.maxForks <workers>	執行測試的最大行程數
--poolOptions.forks.minForks <workers>	執行測試的最小行程數
--poolOptions.vmForks.isolate	在 forks 池中隔離測試 (預設: true)
--poolOptions.vmForks.singleFork	在單個 child_process 中執行測試 (預設: false)
--poolOptions.vmForks.maxForks <workers>	執行測試的最大行程數
--poolOptions.vmForks.minForks <workers>	執行測試的最小行程數
--poolOptions.vmForks.memoryLimit <limit>	VM forks 池的記憶體限制。如果您看到記憶體洩漏，請嘗試調整此值。
--fileParallelism	是否應該並行執行所有的測試檔案。使用 --no-file-parallelism 來停用 (預設: true)
--maxWorkers <workers>	執行測試的最大 worker 數
--minWorkers <workers>	執行測試的最小 worker 數
--environment <name>	指定執行器環境，如果不是在瀏覽器中執行 (預設: node)
--passWithNoTests	在未找到測試時通過
--logHeapUsage	在 node 中執行時顯示每個測試的堆大小
--allowOnly	允許標記為 only 的測試和套件 (預設: !process.env.CI)
--dangerouslyIgnoreUnhandledErrors	忽略任何發生的未處理的錯誤
--shard <shards>	要執行的測試套件分片，格式為 <index>/<count>
--changed [since]	執行受更改檔案影響的測試 (預設: false)
--sequence.shuffle.files	以隨機順序執行檔案。如果啟用此選項，長時間執行的測試不會提前啟動。(預設: false)
--sequence.shuffle.tests	以隨機順序執行測試 (預設: false)
--sequence.concurrent	使測試並行執行 (預設: false)
--sequence.seed <seed>	設定隨機種子。如果 --sequence.shuffle 為 false，此選項將不起作用. 訪問 "Random Seed" page 獲取更多資訊
--sequence.hooks <order>	更改 hooks 的執行順序。可接受的值為: "stack", "list" 和 "parallel". 訪問 sequence.hooks 獲取更多資訊 (預設: "parallel")
--sequence.setupFiles <order>	更改 setup files 的執行順序。可接受的值為: "list" 和 "parallel". 如果設定為 "list", 將按照定義的順序執行 setup files。如果設定為 "parallel", 將並行執行 setup files (預設: "parallel")
--inspect [[host:]port]	啟用 Node.js 檢查器 (預設: 127.0.0.1:9229)
--inspectBrk [[host:]port]	啟用 Node.js 檢查器並在測試開始前中斷
--testTimeout <timeout>	測試的預設逾時時間，以毫秒為單位 (預設: 5000)
--hookTimeout <timeout>	預設 hook 逾時時間，以毫秒為單位 (預設: 10000)
--bail <number>	當給定數量的測試失敗時停止測試執行 (預設: 0)
--retry <times>	如果測試失敗，則重試指定的次數 (預設: 0)
--diff <path>	將用於產生差異介面的差異配置的路徑
--exclude <glob>	從測試中排除的附加檔案 glob
--expandSnapshotDiff	顯示快照失敗時的完整差異
--disableConsoleIntercept	停用自動攔截控制台日誌記錄 (預設: false)
--typecheck.enabled	在測試旁邊啟用類型檢查 (預設: false)
--typecheck.only	僅執行類型檢查測試。這會自動啟用類型檢查 (預設: false)
--typecheck.checker <name>	指定要使用的 類型檢查器。可用值為: "tsc" 和 "vue-tsc" 以及可執行檔案的路徑 (預設: "tsc")
--typecheck.allowJs	允許類型檢查 JavaScript 檔案。預設情況下，從 tsconfig.json 獲取值
--typecheck.ignoreSourceErrors	忽略源檔案中的類型錯誤
--typecheck.tsconfig <path>	自定義 tsconfig 檔案的路徑
--project <name>	如果你正在使用 Vitest 工作區功能，則要執行的專案的名稱。可以重複多個專案：--project=1 --project=2。你也可以使用萬用字元篩選專案，例如 --project=packages*
--slowTestThreshold <threshold>	將測試視為慢的毫秒閾值 (預設: 300)
--teardownTimeout <timeout>	teardown 函式的預設逾時時間，以毫秒為單位 (預設: 10000)
--maxConcurrency <number>	套件中最大並行測試數 (預設: 5)
--run	停用監聽模式
--segfaultRetry <times>	如果測試套件因區段錯誤而崩潰，則重試該測試套件指定次數 (預設: true)
--no-color	從控制台輸出中刪除顏色
--clearScreen	在監聽模式下重新執行測試時清除終端機螢幕 (預設: true)
--standalone	啟動 Vitest 而不執行測試。檔案篩選器將被忽略，測試將在更改時才執行 (預設: false)

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

changed

• 類型: boolean | string

• 預設值: false

  僅針對已變更的檔案執行測試。如果未提供值，將針對未提交的變更 (包含已暫存和未暫存的變更) 執行測試。

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

  與程式碼覆蓋率一起使用時，報告將只包含與這些變更相關的檔案。

  如果與 forceRerunTriggers 配置選項結合使用，則當 forceRerunTriggers 列表中至少一個檔案發生變更時，將執行整個測試套件。 預設情況下，變更 Vitest 設定檔和 package.json 總是會重新執行整個套件。

shard

• 類型: string

• 預設值: 已停用

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

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

  此命令會將所有測試分割為 count 個相同的部分，並且只會執行位於 index 部分中的測試。例如，若要將您的測試套件分成三個部分，請使用以下命令：

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

WARNING

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