ウォッチプラグイン

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)

Jestフックは、`apply`メソッドを実装することでアタッチできます。このメソッドは、プラグインがテスト実行のライフサイクルの特定の部分にフックすることを可能にする`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',
    };
  }
}

これにより、ウォッチモードメニューに1行追加されます _( `› 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.

注意

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

`run(globalConfig, updateConfigAndRun)`

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

• `globalConfig`: Jestの現在のグローバル設定を表します。
• `updateConfigAndRun`：インタラクティブプラグインの実行中にテスト実行をトリガーできます。

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

注意

`updateConfigAndRun`を呼び出す場合、`run`メソッドはtruthy値に解決しないでください。そうすると、二重実行がトリガーされます。

許可された設定キー

安定性と安全性の理由から、`updateConfigAndRun`で更新できるのは、グローバル設定キーの一部のみです。現在のホワイトリストは次のとおりです。

• bail
• changedSince
• collectCoverage
• collectCoverageFrom
• coverageDirectory
• coverageReporters
• notify
• notifyMode
• onlyFailures
• reporters
• testNamePattern
• testPathPattern
• 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.