跳至主要內容
版本：29.7

Jest CLI 選項

jest 命令列執行器有許多有用的選項。您可以執行 jest --help 來檢視所有可用的選項。以下顯示的許多選項也可以一起使用，以完全按照您想要的方式執行測試。Jest 的每個 設定 選項也可以透過 CLI 來指定。

以下是簡要概述

從命令列執行​

執行所有測試（預設）

jest

僅執行使用樣式或檔案名稱指定的測試

jest my-test #or
jest path/to/my-test.js

執行與已變更檔案相關的測試，根據 hg/git（未提交的檔案）

jest -o

執行與 path/to/fileA.js 和 path/to/fileB.js 相關的測試

jest --findRelatedTests path/to/fileA.js path/to/fileB.js

執行符合此規格名稱的測試（基本上與 describe 或 test 中的名稱相符）。

jest -t name-of-spec

執行監控模式

jest --watch #runs jest -o by default
jest --watchAll #runs all tests

監控模式也允許指定檔案的名稱或路徑，以專注於特定測試集。

與套件管理員一起使用​

如果您透過套件管理員執行 Jest，您仍然可以將命令列參數直接傳遞為 Jest 參數。

代替

jest -u -t="ColorPicker"

您可以使用

npm test -- -u -t="ColorPicker"

駝峰式和破折號參數支援​

Jest 支援駝峰式和破折號參數格式。以下範例將有相同的結果

jest --collect-coverage
jest --collectCoverage

參數也可以混合

jest --update-snapshot --detectOpenHandles

選項​

注意

CLI 選項優先於 設定檔 中的值。

參考​

jest <regexForTestFiles>​

當您使用參數執行 jest 時，該參數會被視為用於比對專案中檔案的正規表示法。可以透過提供樣式來執行測試套件。只有與樣式相符的檔案會被選取並執行。根據您的終端機，您可能需要為此參數加上引號：jest "my.*(complex)?pattern"。在 Windows 上，您需要使用 / 作為路徑分隔符號，或將 \ 換成 \\。

--bail[=<n>]​

別名：-b。在 n 個測試套件失敗後立即結束測試套件。預設為 1。

--cache​

是否使用快取。預設為 true。使用 --no-cache 來停用快取。

注意

只有在您遇到快取相關問題時，才應該停用快取。平均而言，停用快取會使 Jest 的速度至少降低兩倍。

如果您想要檢查快取，請使用 --showConfig 並查看 cacheDirectory 的值。如果您需要清除快取，請使用 --clearCache。

--changedFilesWithAncestor​

執行與目前變更和最後一次提交變更相關的測試。行為類似於 --onlyChanged。

--changedSince​

執行自提供分支或提交雜湊以來變更相關的測試。如果目前分支已偏離給定的分支，則只會測試在本地進行的變更。行為類似於 --onlyChanged。

--ci​

提供此選項時，Jest 會假設它在 CI 環境中執行。這會在遇到新快照時改變行為。它不會自動儲存新快照（這是常規行為），而是會讓測試失敗，並要求使用 --updateSnapshot 執行 Jest。

--clearCache​

刪除 Jest 快取目錄，然後退出而不執行測試。如果傳遞了選項，則會刪除 cacheDirectory，或 Jest 的預設快取目錄。可以透過呼叫 jest --showConfig 來找到預設快取目錄。

注意

清除快取會降低效能。

--clearMocks​

在每次測試前自動清除模擬呼叫、執行個體、內容和結果。等同於在每次測試前呼叫 jest.clearAllMocks()。這不會移除任何可能已提供的模擬實作。

--collectCoverageFrom=<glob>​

相對於 rootDir 的 glob 模式，用於比對需要收集涵蓋率資訊的檔案。

--colors​

強制測試結果輸出重點顯示，即使 stdout 不是 TTY。

注意

或者，您可以設定環境變數 FORCE_COLOR=true 以強制啟用，或 FORCE_COLOR=false 以停用彩色的輸出。使用 FORCE_COLOR 會覆寫所有其他色彩支援檢查。

--config=<path>​

別名：-c。指定如何尋找和執行測試的 Jest 設定檔路徑。如果設定檔中未設定 rootDir，則假設包含設定檔的目錄是專案的 rootDir。這也可以是 JSON 編碼的值，Jest 會將其用作設定檔。

--coverage[=<boolean>]​

別名：--collectCoverage。表示應收集測試涵蓋率資訊並在輸出中報告。選擇性傳遞 <boolean> 以覆寫組態中設定的選項。

--coverageDirectory=<路徑>​

Jest 應輸出其涵蓋率檔案的目錄。

--coverageProvider=<提供者>​

表示應使用哪個提供者來為涵蓋率設定程式碼。允許的值為 babel（預設）或 v8。

--debug​

列印有關 Jest 組態的偵錯資訊。

--detectOpenHandles​

嘗試收集並列印防止 Jest 乾淨結束的開啟處理。在需要使用 --forceExit 才能讓 Jest 結束以找出原因的情況下使用此選項。這表示 --runInBand，使測試串列執行。使用 async_hooks 實作。此選項有顯著的效能損失，僅應使用於偵錯。

--env=<環境>​

用於所有測試的測試環境。這可以指向任何檔案或節點模組。範例：jsdom、node 或 path/to/my-environment.js。

--errorOnDeprecated​

讓呼叫已棄用的 API 擲回有用的錯誤訊息。有助於簡化升級程序。

--expand​

別名：-e。使用此旗標顯示完整差異和錯誤，而不是修補程式。

--filter=<檔案>​

導向匯出篩選函式的模組。此非同步函式會收到一串測試路徑清單，可透過回傳形狀為 { filtered: Array<{ test: string }> } 的物件來排除執行測試。特別適用於與測試基礎架構搭配使用，以篩選已知的損毀測試，例如：

my-filter.js
module.exports = testPaths => {
  const allowedPaths = testPaths
    .filter(filteringFunction)
    .map(test => ({test})); // [{ test: "path1.spec.js" }, { test: "path2.spec.js" }, etc]

  return {
    filtered: allowedPaths,
  };
};

--findRelatedTests <spaceSeparatedListOfSourceFiles>​

找出並執行涵蓋傳入引數中以空格分隔的來源檔案清單的測試。適用於整合前置提交掛勾，以執行必要的最小測試量。可與 --coverage 搭配使用，以納入來源檔案的測試涵蓋範圍，不需要重複的 --collectCoverageFrom 引數。

--forceExit​

在所有測試執行完畢後強制 Jest 退出。當測試程式碼設定的資源無法適當地清除時，這很有用。

注意

此功能為逃生艙口。如果 Jest 在測試執行結束時未退出，表示外部資源仍被保留，或程式碼中仍有計時器待處理。建議在每次測試後清除外部資源，以確保 Jest 能夠正常關閉。您可以使用 --detectOpenHandles 來協助追蹤。

--help​

顯示說明資訊，類似於此頁面。

--ignoreProjects <project1> ... <projectN>​

忽略指定專案的測試。Jest 使用設定中的屬性 displayName 來識別每個專案。如果您使用此選項，您應該為所有專案提供一個 displayName。

--init​

產生一個基本設定檔。根據您的專案，Jest 會詢問您幾個問題，這些問題將有助於產生一個 jest.config.js 檔案，其中包含每個選項的簡短說明。

--injectGlobals​

將 Jest 的全域變數 (expect、test、describe、beforeEach 等) 插入全域環境中。如果您將此設定為 false，您應該從 @jest/globals 匯入，例如：

import {expect, jest, test} from '@jest/globals';

jest.useFakeTimers();

test('some test', () => {
  expect(Date.now()).toBe(0);
});
注意

此選項僅支援使用預設的 jest-circus 測試執行器。

--json​

以 JSON 格式列印測試結果。此模式會將所有其他測試輸出和使用者訊息傳送到 stderr。

--lastCommit​

執行最後一次提交中檔案變更影響的所有測試。行為類似於 --onlyChanged。

--listTests​

列出 Jest 會根據引數執行的所有測試檔案，然後結束。

--logHeapUsage​

在每個測試後記錄堆積使用量。有助於偵錯記憶體外洩。與 Node.js 中的 --runInBand 和 --expose-gc 一起使用。

--maxConcurrency=<num>​

防止 Jest 同時執行超過指定數量的測試。僅影響使用 test.concurrent 的測試。

--maxWorkers=<num>|<string>​

別名：-w。指定工作人員池將產生用於執行測試的最大工作人員數。在單次執行模式下，這預設為機器上可用的核心數減去主執行緒的一個。在監控模式下，這預設為機器上可用核心數的一半，以確保 Jest 不會造成干擾，也不會讓機器停擺。在資源有限的環境（例如 CI）中調整此設定可能很有用，但預設設定應足以應付大多數使用案例。

對於具有可變 CPU 可用的環境，可以使用基於百分比的設定：--maxWorkers=50%

--noStackTrace​

停用測試結果輸出中的堆疊追蹤。

--notify​

啟用測試結果通知。適合於您不希望意識集中在 JavaScript 測試以外的任何事物時。

--onlyChanged​

別名：-o。嘗試根據目前儲存庫中已變更的檔案，來識別要執行的測試。目前僅適用於在 git/hg 儲存庫中執行測試，且需要靜態相依關係圖（即沒有動態需求）。

--openHandlesTimeout=<milliseconds>​

當 --detectOpenHandles 和 --forceExit 已停用 時，如果處理程序在這個毫秒數之後沒有正常結束，Jest 會印出警告。值 0 會停用警告。預設為 1000。

--outputFile=<filename>​

當 --json 選項也已指定時，將測試結果寫入檔案。已回傳的 JSON 結構記載於 testResultsProcessor 中。

--passWithNoTests​

允許在找不到任何檔案時，測試套件通過。

--projects <path1> ... <pathN>​

從一個或多個專案執行測試，這些專案位於指定的路徑中；也採用路徑 glob。此選項等同於 CLI 中的 projects 設定選項。

注意

如果在指定的路徑中找到設定檔，則會執行這些設定檔中指定的所有專案。

--randomize​

將檔案中的測試順序隨機排列。隨機排列是根據種子進行的。請參閱 --seed=<num> 以取得更多資訊。

設定此選項時，會顯示種子值。等同於設定 CLI 選項 --showSeed。

jest --randomize --seed 1234
注意

此選項僅支援使用預設的 jest-circus 測試執行器。

--reporters​

使用指定的報告程式執行測試。無法透過 CLI 使用 報告程式選項。以下是使用多個報告程式的範例

jest --reporters="default" --reporters="jest-junit"

--resetMocks​

在每個測試之前自動重設模擬狀態。等同於在每個測試之前呼叫 jest.resetAllMocks()。這將導致所有模擬移除其偽實作，但不會還原其初始實作。

--restoreMocks​

在每個測試之前自動還原模擬狀態和實作。等同於在每個測試之前呼叫 jest.restoreAllMocks()。這將導致任何模擬移除其偽造實作並還原其初始實作。

--roots​

Jest 應使用來搜尋檔案的目錄路徑清單。

--runInBand​

別名：-i。在目前處理程序中依序執行所有測試，而非建立執行測試的子處理程序工作池。這可能有助於除錯。

--runTestsByPath​

僅執行使用其確切路徑指定的測試。這避免將其轉換為正規表示式並與每個檔案進行比對。

例如，給定下列檔案結構

__tests__
└── t1.test.js # test
└── t2.test.js # test

使用模式執行時，找不到任何測試

jest --runTestsByPath __tests__/t

輸出

No tests found

不過，傳遞確切路徑將僅執行給定的測試

jest --runTestsByPath __tests__/t1.test.js

輸出

PASS __tests__/t1.test.js
提示

預設的正規表示式比對在小規模執行時運作良好，但如果提供多個模式和/或針對大量測試時，速度會變慢。此選項取代正規表示式比對邏輯，並藉此最佳化 Jest 過濾特定測試檔案所需的時間。

--seed=<num>​

設定種子值，可透過 jest.getSeed() 在測試檔案中擷取。種子值必須介於 -0x80000000 和 0x7fffffff 之間（十進位制為 -2147483648（-(2 ** 31)）和 2147483647（2 ** 31 - 1））。

jest --seed=1324
提示

如果未指定此選項，Jest 會隨機產生值。您可以使用 --showSeed 旗標在測試報告摘要中列印種子。

--selectProjects <project1> ... <projectN>​

執行指定專案的測試。Jest 使用設定中的屬性 displayName 來識別每個專案。如果您使用此選項，您應該為所有專案提供 displayName。

--setupFilesAfterEnv <path1> ... <pathN>​

在每次測試之前執行一些程式碼來設定或設定測試架構的模組路徑清單。請注意，設定指令碼匯入的檔案在測試期間不會被模擬。

--shard​

使用 (?<shardIndex>\d+)/(?<shardCount>\d+) 格式執行的測試套件分片。

shardIndex 描述要選取的分片，而 shardCount 控制套件應分割的分片數目。

shardIndex 和 shardCount 必須是 1 為基底的正數，而且 shardIndex 必須小於或等於 shardCount。

當指定 shard 時，設定的 testSequencer 必須實作 shard 方法。

例如，將套件分割成三個分片，每個分片執行三分之一的測試

jest --shard=1/3
jest --shard=2/3
jest --shard=3/3

--showConfig​

列印您的 Jest 設定，然後退出。

--showSeed​

在測試報告摘要中列印種子值。有關詳細資訊，請參閱 --seed=<num>。

也可以在設定中設定。請參閱 showSeed。

--silent​

防止測試透過主控台列印訊息。

--testEnvironmentOptions=<json string>​

包含會傳遞給 testEnvironment 的選項的 JSON 字串。相關選項取決於環境。

--testLocationInResults​

將 location 欄位新增至測試結果。如果您想在報告程式中回報測試的位置，這會很有用。

注意

在結果物件中，column 是從 0 開始編號，而 line 則不是。

{
  "column": 4,
  "line": 5
}

--testMatch glob1 ... globN​

Jest 用於偵測測試檔案的 glob 模式。請參閱 testMatch 設定檔 以取得詳細資料。

--testNamePattern=<regex>​

別名：-t。僅執行名稱符合正規表示式的測試。例如，假設您只想執行與授權相關的測試，這些測試的名稱會像 'GET /api/posts with auth'，您可以使用 jest -t=auth。

提示

正規表示式與完整名稱相符，而完整名稱是測試名稱與其所有周圍的 describe 區塊的組合。

--testPathIgnorePatterns=<regex>|[array]​

單一或陣列的 regexp 模式字串，在執行測試前會針對所有測試路徑進行測試。與 --testPathPattern 相反，它只會執行路徑與提供的 regexp 表示式不符的那些測試。

要傳遞為陣列，請使用跳脫的括號和以空白分隔的 regexp，例如 \(/node_modules/ /tests/e2e/\)。或者，您可以透過將 regexp 合併成單一 regexp 來省略括號，例如 /node_modules/|/tests/e2e/。這兩個範例是等效的。

--testPathPattern=<regex>​

在執行測試前與所有測試路徑相符的 regexp 模式字串。在 Windows 上，您需要使用 / 作為路徑分隔符號，或將 \ 跳脫為 \\。

--testRunner=<path>​

讓您可以指定自訂測試執行程式。

--testSequencer=<路徑>​

讓您指定自訂測試順序器。請參閱testSequencer 組態以取得詳細資訊。

--testTimeout=<數字>​

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

--updateSnapshot​

別名：-u。使用此標記重新記錄在此測試執行期間失敗的每個快照。可與測試套件樣式或 --testNamePattern 搭配使用，以重新記錄快照。

--useStderr​

將所有輸出導向 stderr。

--verbose​

顯示個別測試結果，並附上測試套件階層。

--version​

別名：-v。列印版本並結束。

--watch​

監控檔案變更，並重新執行與變更檔案相關的測試。如果您想要在檔案變更時重新執行所有測試，請改用 --watchAll 選項。

提示

使用 --no-watch（或 --watch=false）明確停用監控模式（如果已使用 --watch 啟用）。在大部分 CI 環境中，這會自動為您處理。

--watchAll​

監控檔案變更，並在有變更時重新執行所有測試。如果您只想重新執行依賴於變更檔案的測試，請使用 --watch 選項。

提示

使用 --no-watchAll（或 --watchAll=false）明確停用監控模式（如果已使用 --watchAll 啟用）。在大部分 CI 環境中，這會自動為您處理。

--watchman​

是否使用 watchman 進行檔案爬取。預設為 true。使用 --no-watchman 停用。

--workerThreads​

是否使用 工作執行緒 進行平行處理。預設使用 子處理程序。

注意

這是實驗性功能。請參閱workerThreads 設定選項以取得更多詳細資訊。