ウォッチプラグイン

非公式ベータ版翻訳

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

Jestのウォッチプラグインシステムは、Jestの特定部分にフックする方法と、キー押下でコードを実行するウォッチモードのメニュープロンプトを定義する手段を提供します。これらの機能を組み合わせることで、ワークフローに合わせたインタラクティブな体験を構築できます。

ウォッチプラグインインターフェース

class MyWatchPlugin {
  // Add hooks to Jest lifecycle events
  apply(jestHooks) {}

  // Get the prompt information for interactive plugins
  getUsageInfo(globalConfig) {}

  // Executed when the key from `getUsageInfo` is input
  run(globalConfig, updateConfigAndRun) {}
}

Jestへのフック

ウォッチプラグインをJestに接続するには、Jest設定の watchPlugins にプラグインのパスを追加します：

jest.config.js

module.exports = {
  // ...
  watchPlugins: ['path/to/yourWatchPlugin'],
};

カスタムウォッチプラグインはJestイベントにフックを追加できます。これらのフックは、ウォッチモードメニューにインタラクティブキーを持つ場合と持たない場合のどちらでも追加可能です。

apply(jestHooks)

apply メソッドを実装することでJestフックをアタッチできます。このメソッドは jestHooks 引数を受け取り、プラグインがテスト実行ライフサイクルの特定部分にフックすることを可能にします。

class MyWatchPlugin {
  apply(jestHooks) {}
}

以下にJestで利用可能なフックを示します。

jestHooks.shouldRunTestSuite(testSuiteInfo)

テストを実行すべきかどうかを指定するブール値（非同期操作処理の場合は Promise<boolean>）を返します。

例：

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.shouldRunTestSuite(testSuiteInfo => {
      return testSuiteInfo.testPath.includes('my-keyword');
    });

    // or a promise
    jestHooks.shouldRunTestSuite(testSuiteInfo => {
      return Promise.resolve(testSuiteInfo.testPath.includes('my-keyword'));
    });
  }
}

jestHooks.onTestRunComplete(results)

各テスト実行終了時に呼び出され、テスト結果を引数として受け取ります。

例：

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.onTestRunComplete(results => {
      this._hasSnapshotFailure = results.snapshot.failure;
    });
  }
}

jestHooks.onFileChange({projects})

ファイルシステムに変更が発生するたびに呼び出されます

• projects: Array<config: ProjectConfig, testPaths: Array<string>: Jestが監視している全てのテストパスを含みます

例：

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.onFileChange(({projects}) => {
      this._projects = projects;
    });
  }
}

ウォッチメニュー統合

カスタムウォッチプラグインは、getUsageInfo メソッドでキー/プロンプトペアを指定し、キー実行用の run メソッドを実装することで、ウォッチメニュー機能を追加または上書きできます。

getUsageInfo(globalConfig)

ウォッチメニューにキーを追加するには、getUsageInfo メソッドを実装し、キーとプロンプトを返します：

class MyWatchPlugin {
  getUsageInfo(globalConfig) {
    return {
      key: 's',
      prompt: 'do something',
    };
  }
}

これによりウォッチモードメニューに一行追加されます (› Press s to do something.)

Watch Usage
 › Press p to filter by a filename regex pattern.
 › Press t to filter by a test name regex pattern.
 › Press q to quit watch mode.
 › Press s to do something. // <-- This is our plugin
 › Press Enter to trigger a test run.

メモ

プラグインのキーがデフォルトキーとして既に存在する場合、プラグインはそのキーを上書きします。

run(globalConfig, updateConfigAndRun)

getUsageInfo が返すキーからのキー押下イベントを処理するには run メソッドを実装します。このメソッドは Promise<boolean> を返し、プラグインが制御をJestに戻す際に解決されます。boolean は制御戻り後にJestがテストを再実行するかどうかを指定します。

• globalConfig: Jestの現在のグローバル設定を表します

• updateConfigAndRun: インタラクティブプラグイン実行中にテスト実行をトリガーできます

class MyWatchPlugin {
  run(globalConfig, updateConfigAndRun) {
    // do something.
  }
}

メモ

updateConfigAndRun を呼び出す場合、run メソッドは真値に解決しないでください。さもないと二重実行が発生します

許可された設定キー

安定性と安全性のため、updateConfigAndRun で更新可能なグローバル設定キーは一部のみです。現在の許可リストは次の通りです：

• bail

• changedSince

• collectCoverage

• collectCoverageFrom

• coverageDirectory

• coverageReporters

• notify

• notifyMode

• onlyFailures

• reporters

• testNamePattern

• testPathPatterns

• updateSnapshot

• verbose

カスタマイズ

プラグインはJestの設定を通じてカスタマイズできます。

jest.config.js

module.exports = {
  // ...
  watchPlugins: [
    [
      'path/to/yourWatchPlugin',
      {
        key: 'k', // <- your custom key
        prompt: 'show a custom prompt',
      },
    ],
  ],
};

推奨される設定名：

• key: プラグインのキーを変更

• prompt: プラグインのプロンプトテキストをカスタマイズ可能

ユーザーがカスタム設定を提供した場合、その設定はプラグインのコンストラクタ引数として渡されます。

class MyWatchPlugin {
  constructor({config}) {}
}

適切なキーの選択

Jestはサードパーティプラグインが組み込み機能キーの一部を上書きすることを許可していますが、全てではありません。特に以下のキーは上書き不可です：

• c (フィルタパターンをクリア)

• i (不一致スナップショットを対話的に更新)

• q (終了)

• u (全ての不一致スナップショットを更新)

• w (ウォッチモードの使用法/利用可能な操作を表示)

組み込み機能の以下のキーは上書き可能です：

• p (テストファイル名パターン)

• t (テスト名パターン)

組み込み機能で使用されていないキーは自由に使用できます。ただし各種キーボードで入力が難しいキー（例: é, €）や、デフォルトで表示されないキー（例: Macキーボードの |, \, [ など）は避けることを推奨します。

競合発生時の対応

プラグインが予約済みキーの上書きを試みた場合、Jestは以下のような詳細なエラーメッセージを表示します：

Watch plugin YourFaultyPlugin attempted to register key `q`, that is reserved internally for quitting watch mode. Please change the configuration key for this plugin.

サードパーティプラグインは、設定済みプラグインリスト（watchPlugins 配列設定）内で先行する別のサードパーティプラグインが予約したキーの上書きも禁止されています。この場合も問題解決に役立つエラーメッセージが表示されます：

Watch plugins YourFaultyPlugin and TheirFaultyPlugin both attempted to register key `x`. Please change the key configuration for one of the conflicting plugins to avoid overlap.