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，请将其路径添加​watchPlugins​到你的 Jest 配置中：

// 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(全局配置, 更新配置并运行)

要处理来自​getUsageInfo​返回的键的按键事件，可以实现该run​方法。此方法返回一个​Promise<boolean>​ ，当插件想要将控制权返回给 Jest 时，可以解析这个 Promise。​boolean​指定 Jest 在获得控件后是否应重新运行测试

• ​globalConfig​: Jest 当前全局配置的表示
• ​updateConfigAndRun​：允许在交互式插件运行时触发测试运行。

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

注意：如果调用​updateConfigAndRun​，你的​run​方法不应解析为真值，因为这会触发双重运行。

授权配置密钥

出于稳定性和安全原因，只有部分全局配置键可以使用​updateConfigAndRun​. 目前白名单如下：

• ​bail​
• ​changedSince​
• ​collectCoverage​
• ​collectCoverageFrom​
• ​collectCoverageOnlyFrom​
• ​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.