メインコンテンツへスキップ
バージョン: 次へ

Jest CLI オプション

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。 エラーを見つけましたか？ 問題を報告 →

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 の実行速度が2倍以上低下します。

キャッシュを確認するには --showConfig を使用し cacheDirectory の値を確認してください。キャッシュをクリアするには --clearCache を使用します。

--changedFilesWithAncestor​

現在の変更と直前のコミットの変更に関連するテストを実行します。--onlyChanged と同様の動作をします。

--changedSince​

指定したブランチまたはコミットハッシュ以降の変更に関連するテストを実行します。現在のブランチが指定ブランチから分岐している場合、ローカルの変更のみがテスト対象となります。--onlyChanged と同様の動作をします。

--ci​

このオプション指定時、Jest は CI 環境で実行されているとみなします。新しいスナップショットが検出された場合の挙動が変化し、自動保存する代わりにテストが失敗し、--updateSnapshot 付きでの再実行が必要になります。

--clearCache​

Jestのキャッシュディレクトリを削除し、テストを実行せずに終了します。オプションが渡された場合はcacheDirectoryを削除し、指定がない場合はJestのデフォルトキャッシュディレクトリを削除します。デフォルトのキャッシュディレクトリはjest --showConfigを実行することで確認できます。

注意

キャッシュをクリアするとパフォーマンスが低下します。

--clearMocks​

各テストの前にモックの呼び出し、インスタンス、コンテキスト、結果を自動的にクリアします。jest.clearAllMocks()を各テスト前に呼び出すのと同等です。提供されたモックの実装は削除されません。

--collectCoverageFrom=<glob>​

カバレッジ情報を収集するファイルを指定するrootDirからの相対globパターン。

--colors​

標準出力がTTYでない場合でも、テスト結果の出力ハイライトを強制します。

メモ

代替方法として、環境変数FORCE_COLOR=trueを設定すると強制的に有効化され、FORCE_COLOR=falseでカラー出力を無効化できます。FORCE_COLORは他のすべてのカラーサポートチェックを上書きします。

--config=<path>​

エイリアス: -c。テストの検索と実行方法を指定するJest設定ファイルへのパス。設定内にrootDirが設定されていない場合、設定ファイルを含むディレクトリがプロジェクトのrootDirとみなされます。JSON形式でエンコードされた設定値も直接渡せます。

--coverage[=<boolean>]​

エイリアス: --collectCoverage。テストカバレッジ情報を収集して出力にレポートすることを示します。設定ファイルのオプションを上書きする場合は<boolean>値を渡せます。

--coverageDirectory=<path>​

Jestがカバレッジファイルを出力するディレクトリ。

--coverageProvider=<provider>​

カバレッジ用にコードをインストルメントするプロバイダを指定します。有効な値はbabel（デフォルト）またはv8です。

--debug​

Jest設定に関するデバッグ情報を出力します。

--detectOpenHandles​

Jestが正常に終了するのを妨げているオープンハンドルの収集と出力を試みます。Jestを終了させるために--forceExitが必要な場合に原因追跡に使用します。このオプションは--runInBandを暗黙的に含み、テストを直列実行します。async_hooksを使用して実装されています。パフォーマンスに大きな影響を与えるため、デバッグ専用で使用してください。

--env=<environment>​

全テストで使用するテスト環境を指定します。任意のファイルやnpmモジュールを指定可能（例: jsdom, node, path/to/my-environment.js）。

--errorOnDeprecated​

非推奨APIの呼び出し時に有用なエラーメッセージをスローします。アップグレードプロセスを円滑にするのに役立ちます。

--expand​

エイリアス: -e。差分とエラーをパッチ形式ではなく完全な形式で表示します。

--filter=<file>​

フィルタリング関数をエクスポートするモジュールへのパス。この非同期関数はテストパスのリストを受け取り、実行から除外するテストを操作できます。Jestが実行すべきテストを含む{ filtered: Array<string> }形式のオブジェクトを返す必要があります。既知の不具合があるテストをフィルタリングする際に特に有用です。

my-filter.js
// This filter when applied will only run tests ending in .spec.js (not the best way to do it, but it's just an example):
const filteringFunction = testPath => testPath.endsWith('.spec.js');

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

  return {
    filtered: allowedPaths,
  };
};

--findRelatedTests <spaceSeparatedListOfSourceFiles>​

引数として渡されたスペース区切りのソースファイルリストをカバーするテストを検索して実行します。最小限のテスト実行が必要なpre-commitフックとの連携に最適です。--coverageと組み合わせて使用すると、ソースファイルのテストカバレッジを含められます（重複した--collectCoverageFrom引数は不要）。

--forceExit​

すべてのテスト実行完了後にJestを強制終了します。テストコードでセットアップされたリソースが適切にクリーンアップできない場合に有用です。

注意

この機能は緊急避難用です。Jestがテスト終了後に終了しない場合、外部リソースが保持されたままになっているか、コード内にタイマーが残っていることを意味します。各テスト後に外部リソースを解放し、Jestが正常に終了できるようにすることを推奨します。原因調査には--detectOpenHandlesの使用が有効です。

--help​

このページと同様のヘルプ情報を表示します。

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

指定されたプロジェクトのテストを無視します。Jestは設定内のdisplayName属性で各プロジェクトを識別します。このオプションを使用する場合、全プロジェクトにdisplayNameを設定する必要があります。

--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では--runInBandと--expose-gcと併用してください。

--maxConcurrency=<num>​

同時に実行するテスト数を指定値以下に制限します。test.concurrentを使用するテストのみに影響します。

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

エイリアス：-w。テスト実行用のワーカープールが生成する最大ワーカー数を指定します。シングル実行モードではデフォルトで（マシンのコア数 - 1）、ウォッチモードではデフォルトで（利用可能コア数の半分）になります。CIなどリソース制限環境での調整に有用ですが、デフォルト値がほとんどのケースで適切です。

CPU数が変動する環境ではパーセンテージ指定が可能です：--maxWorkers=50%

--noStackTrace​

テスト結果出力からスタックトレースを除外します。

--notify​

テスト結果をOSネイティブの通知で表示します。JavaScriptテスト以外に集中できない状況で有用です。通知機能には別途node-notifierパッケージのインストールが必要です。

--onlyChanged​

エイリアス：-o。現在のリポジトリで変更されたファイルに基づき実行するテストを自動判別します。git/hgリポジトリ内でのみ動作し、依存関係が静的な場合（動的requireなし）に限定されます。

--onlyFailures​

エイリアス：-f。前回実行で失敗したテストのみを再実行します。

--openHandlesTimeout=<milliseconds>​

--detectOpenHandlesと--forceExitが無効な場合、Jestはこのミリ秒数後にプロセスが正常終了していないと警告を表示します。値0を指定すると警告は無効化されます。デフォルト値は1000です。

--outputFile=<filename>​

--jsonオプションと併用した場合、テスト結果を指定ファイルに書き込みます。返されるJSON構造はtestResultsProcessorで定義されています。

--passWithNoTests​

テストファイルが見つからなかった場合でもテストスイートを成功終了させます。

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

指定パス内にある1つ以上のプロジェクトからテストを実行します。パスグロブも指定可能です。このオプションはCLI版のprojects設定オプションに相当します。

メモ

指定パス内に設定ファイルが見つかった場合、それらの設定ファイル内で指定されたすべてのプロジェクトが実行されます。

--randomize​

ファイル内のテスト順序をシャッフルします。シャッフルはシード値に基づきます。詳細は--seed=<num>を参照してください。

このオプションを指定するとシード値が表示されます。--showSeed CLIオプションの指定と同等です。

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
ヒント

デフォルトの正規表現マッチングは小規模実行では問題ありませんが、複数パターン指定や大量テスト時には遅延要因となります。本オプションは正規表現マッチングロジックを置換し、特定テストファイルのフィルタリング時間を最適化します。

--seed=<num>​

jest.getSeed() を通じてテストファイル内で取得可能なシード値を設定します。シード値は -0x80000000 から 0x7fffffff の範囲内（10進数で -2147483648 (-(2 ** 31)) から 2147483647 (2 ** 31 - 1)）でなければなりません。

jest --seed=1324
ヒント

このオプションが指定されていない場合、Jestはランダムに値を生成します。テストレポートのサマリーにシード値を表示するには --showSeed フラグを使用できます。

Jestはこのシード値を内部で使用し、テストスイートの実行順序をシャッフルします。--randomize オプションが使用されている場合、各describeブロック内のテスト順序のシャッフルにもこのシード値が使用されます。不安定なテスト（Flaky Test）に対処する際、同じシード値で再実行すると失敗の再現に役立つ可能性があります。

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

指定したプロジェクトのテストを実行します。Jestは設定内のdisplayName属性を使用して各プロジェクトを識別します。このオプションを使用する場合、すべてのプロジェクトにdisplayNameを設定する必要があります。

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

各テストの前にテストフレームワークを設定または初期化するコードを実行するモジュールへのパスリスト。注意点：セットアップスクリプトでインポートされたファイルはテスト中にモック化されません。

--shard​

(?<shardIndex>\d+)/(?<shardCount>\d+) 形式で実行するテストスイートのシャードを指定します。

shardIndexは選択するシャードを指定し、shardCountはスイートを分割する総シャード数を制御します。

shardIndexとshardCountは1から始まる正の整数でなければならず、shardIndexはshardCount以下である必要があります。

shardが指定された場合、設定されたtestSequencerはshardメソッドを実装している必要があります。

例：スイートを3つのシャードに分割し、各シャードでテストの1/3を実行する場合：

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は1から始まる通常の行番号です。

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

--testMatch glob1 ... globN​

Jestがテストファイルを検出するために使用するグロブパターン。詳細はtestMatch設定を参照してください。

--testNamePattern=<regex>​

エイリアス: -t. 正規表現に一致する名前のテストのみを実行します。例えば、'GET /api/posts with auth' のような認証関連のテストのみを実行したい場合、jest -t=auth を使用できます。

ヒント

正規表現は、テスト名とそれを囲むすべての describe ブロックを組み合わせた完全名に対して照合されます。

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

テスト実行前にすべてのテストパスに対して評価される正規表現パターンの文字列または配列。--testPathPatternsとは対照的に、提供された正規表現に一致しないパスのテストのみを実行します。

配列として渡すには、\(/node_modules/ /tests/e2e/\)のようにエスケープされた括弧とスペース区切りの正規表現を使用します。代わりに、/node_modules/|/tests/e2e/のように正規表現を単一の式に結合して括弧を省略することもできます。これら2つの例は同等です。

--testPathPatterns=<regex>​

テスト実行前にすべてのテストパスに対して照合される正規表現パターン文字列。Windowsでは、パス区切り文字として/を使用するか、\を\\としてエスケープする必要があります。

--testRunner=<path>​

カスタムテストランナーを指定できます。

--testSequencer=<path>​

カスタムテストシーケンサーを指定できます。詳細はtestSequencer設定を参照してください。

--testTimeout=<number>​

テストのデフォルトタイムアウト（ミリ秒）。デフォルト値: 5000。

--updateSnapshot​

エイリアス: -u. このテスト実行中に失敗したすべてのスナップショットを再記録します。テストスイートのパターンや--testNamePatternと組み合わせて使用できます。

--useStderr​

すべての出力を標準エラー(stderr)にリダイレクトします。

--verbose​

テストスイートの階層構造と個々のテスト結果を表示します。

--version​

エイリアス: -v. バージョンを表示して終了します。

--waitForUnhandledRejections​

rejectionHandled、uncaughtException、unhandledRejectionを処理するために1イベントループの猶予を与えます。

このフラグがない場合、Jestは誤検知エラー（実際には処理されたリジェクトが報告される）を報告したり、実際の未処理リジェクトを報告しない（または別のテストケースとして報告する）可能性があります。

このオプションは高速なテストスイートでは顕著なオーバーヘッドを生む場合があります。

--watch​

ファイルの変更を監視し、変更されたファイルに関連するテストを再実行します。ファイルが変更されたときにすべてのテストを再実行したい場合は、代わりに--watchAllオプションを使用してください。

ヒント

--watchで有効にされたウォッチモードを明示的に無効にするには、--no-watch（または--watch=false）を使用します。ほとんどのCI環境では、これは自動的に処理されます。

--watchAll​

ファイルの変更を監視し、変更が検出されたときにすべてのテストを再実行します。変更されたファイルに依存するテストのみを再実行したい場合は、--watchオプションを使用してください。

ヒント

--watchAllで有効にされたウォッチモードを明示的に無効にするには、--no-watchAll（または--watchAll=false）を使用します。ほとんどのCI環境では、これは自動的に処理されます。

--watchman​

watchman を使用してファイルクロールを行うかどうか。デフォルトは true です。--no-watchman で無効化できます。

--workerThreads​

並列化に worker threads を使用するかどうかを指定します。デフォルトでは child processes が使用されます。

注意

これは 実験的な機能 です。詳細は workerThreads 設定オプション を参照してください。