Version: Next

Watch プラグイン

JestのWatchプラグイン機能は、Jestの指定した箇所にフックする方法を提供し、キーの押下時にコードを実行するwatchモードのメニュープロンプトを定義します。これらの機能を組み合わせることで、あなたのワークフロー向けにカスタマイズされた対話型な開発環境を作成できます。

Watchプラグインインターフェース

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 にフックする

Watchプラグインを Jest に接続するには、Jest の設定で watchPlugins にそのパスを追加します。

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

独自のwatchプラグインはJestイベントにフックを追加できます。これらのフックは、watchモードメニューでインタラクティブキーの有無にかかわらず追加できます。

`apply(jestHooks)`

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

class MyWatchPlugin {
  apply(jestHooks) {}
}

以下で、Jest で使用可能なフックを紹介します。

`jestHooks.shouldRunTestSuite(testSuiteInfo)`

テストを実行するべきか否かを指定するために、boolean (または、非同期の操作をハンドリングする場合は 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;
    });
  }
}

Watch メニューの統合

カスタムWatchプラグインは、 getUsageInfo メソッドでキー/プロンプトの組み合わせを指定し、キーの実行を行うための run メソッドを指定することで、Watchメニューに機能を追加またはオーバーライドすることもできます。

`getUsageInfo(globalConfig)`

Watchメニューにキーを追加するには、 getUsageInfo メソッドを実装し、キーとプロンプトの組み合わせを返します:

class MyWatchPlugin {
  getUsageInfo(globalConfig) {
    return {
      key: 's',
      prompt: '何かをする',
    };
  }
}

これによりWatchモードメニューに行が追加されます (› 何かをするにはsを押します。 )

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.

note

If the key for your plugin already exists as a default key, your plugin will override that key.

`run(globalConfig, updateConfigAndRun)`

getUsageInfoによって返されるキーからのキー押下イベントをハンドルするために、 run メソッドを実装できます。このメソッドは Promise<boolean> を返します。このPromiseはプラグインが Jest にコントロールを返す際に解決されます。 boolean は、 Jest にコントロールが戻った後にテストを再実行するかどうかを指定します。

globalConfig: A representation of Jest's current global configuration
updateConfigAndRun: 対話型プラグインの実行中にテスト実行をトリガーできます。

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

note

If you do call updateConfigAndRun, your run method should not resolve to a truthy value, as that would trigger a double-run.

認証済みの設定キー

安定性と安全性の理由から、 updateConfigAndRunでグローバル設定キーの一部のみを更新できます。現在のホワイト・リストは以下の通りです。

カスタマイズ

Plugins can be customized via your Jest configuration.

jest.config.js
module.exports = {
  // ...
  watchPlugins: [
    [
      'path/to/yourWatchPlugin',
      {
        key: 'k', // <- 任意のキー
        prompt: 'カスタムのプロンプトを表示する',
      },
    ],
  ],
};

Recommended config names:

key: Modifies the plugin key.
prompt: Allows user to customize the text in the plugin prompt.

If the user provided a custom configuration, it will be passed as an argument to the plugin constructor.

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.