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)

可以通过实现 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;
    });
  }
}

Watch 菜单集成

自定义 watch 插件还可以通过在 getUsageInfo 方法中指定键/提示对，以及在 run 方法中指定键的执行来添加或覆盖 watch 菜单的功能。

getUsageInfo(globalConfig)

要向 watch 菜单添加键，请实现 getUsageInfo 方法，返回键和提示

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

这将在 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.

注意

如果您的插件的键已经作为默认键存在，您的插件将覆盖该键。

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
• 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（显示 watch 模式用法/可用操作）

以下内置功能的键**可以覆盖** 

• 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.