监视插件

Jest 监视插件系统提供了一种方法来连接 Jest 的特定部分并定义在按键时执行代码的监视模式菜单提示。结合起来，这些功能使你可以开发适合你的工作流程的交互式体验。

¥The Jest watch plugin system provides a way to hook into specific parts of Jest and to define watch mode menu prompts that execute code on key press. Combined, these features allow you to develop interactive experiences custom for your workflow.

监视插件接口

¥Watch Plugin Interface

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

¥Hooking into Jest

要将监视插件连接到 Jest，请在 Jest 配置中的 watchPlugins 下添加其路径：

¥To connect your watch plugin to Jest, add its path under watchPlugins in your Jest configuration:

jest.config.js

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

自定义监视插件可以向 Jest 事件添加钩子。可以在监视模式菜单中使用或不使用交互键来添加这些钩子。

¥Custom watch plugins can add hooks to Jest events. These hooks can be added either with or without having an interactive key in the watch mode menu.

apply(jestHooks)

可以通过实现 apply 方法来附加 Jest 钩子。此方法接收 jestHooks 参数，该参数允许插件钩子到测试运行生命周期的特定部分。

¥Jest hooks can be attached by implementing the apply method. This method receives a jestHooks argument that allows the plugin to hook into specific parts of the lifecycle of a test run.

class MyWatchPlugin {
  apply(jestHooks) {}
}

以下是 Jest 中可用的钩子。

¥Below are the hooks available in Jest.

jestHooks.shouldRunTestSuite(testSuiteInfo)

返回一个布尔值（或 Promise<boolean> 用于处理异步操作）以指定是否应运行测试。

¥Returns a boolean (or Promise<boolean> for handling asynchronous operations) to specify if a test should be run or not.

例如：

¥For example:

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)

在每次测试运行结束时被调用。它以测试结果作为参数。

¥Gets called at the end of every test run. It has the test results as an argument.

例如：

¥For example:

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

jestHooks.onFileChange({projects})

每当文件系统发生更改时就会被调用

¥Gets called whenever there is a change in the file system

• projects: Array<config: ProjectConfig, testPaths: Array<string>：包括 Jest 正在观察的所有测试路径。

  ¥projects: Array<config: ProjectConfig, testPaths: Array<string>: Includes all the test paths that Jest is watching.

例如：

¥For example:

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

监视菜单集成

¥Watch Menu Integration

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

¥Custom watch plugins can also add or override functionality to the watch menu by specifying a key/prompt pair in getUsageInfo method and a run method for the execution of the key.

getUsageInfo(globalConfig)

要向监视菜单添加按键，请实现 getUsageInfo 方法，返回按键和提示：

¥To add a key to the watch menu, implement the getUsageInfo method, returning a key and the prompt:

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

这将在监视模式菜单中添加一行（› Press s to do something.）

¥This will add a line in the watch mode menu (› 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.

注意

如果你的插件的密钥已作为默认密钥存在，则你的插件将覆盖该密钥。

¥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>，当插件想要将控制权返回给 Jest 时可以解析该 Promise<boolean>。boolean 指定 Jest 在取回控制权后是否应重新运行测试。

¥To handle key press events from the key returned by getUsageInfo, you can implement the run method. This method returns a Promise<boolean> that can be resolved when the plugin wants to return control to Jest. The boolean specifies if Jest should rerun the tests after it gets the control back.

• globalConfig：Jest 当前全局配置的表示

  ¥globalConfig: A representation of Jest's current global configuration

• updateConfigAndRun：允许你在交互式插件运行时触发测试运行。

  ¥updateConfigAndRun: Allows you to trigger a test run while the interactive plugin is running.

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

注意

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

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

授权配置密钥

¥Authorized configuration keys

出于稳定性和安全原因，只有部分全局配置密钥可以使用 updateConfigAndRun 进行更新。目前白名单如下：

¥For stability and safety reasons, only part of the global configuration keys can be updated with updateConfigAndRun. The current white list is as follows:

• bail

• changedSince

• collectCoverage

• collectCoverageFrom

• coverageDirectory

• coverageReporters

• notify

• notifyMode

• onlyFailures

• reporters

• testNamePattern

• testPathPattern

• updateSnapshot

• verbose

定制化

¥Customization

插件可以通过你的 Jest 配置进行自定义。

¥Plugins can be customized via your Jest configuration.

jest.config.js

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

推荐的配置名称：

¥Recommended config names:

• key：修改插件密钥。

  ¥key: Modifies the plugin key.

• prompt：允许用户自定义插件提示中的文本。

  ¥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}) {}
}

选择一个好键

¥Choosing a good key

Jest 允许第三方插件覆盖其某些内置功能键，但不是全部。具体来说，以下键不可覆盖：

¥Jest allows third-party plugins to override some of its built-in feature keys, but not all. Specifically, the following keys are not overwritable :

• c（清除过滤模式）

  ¥c (clears filter patterns)

• i（交互式更新不匹配的快照）

  ¥i (updates non-matching snapshots interactively)

• q（退出）

  ¥q (quits)

• u（更新所有不匹配的快照）

  ¥u (updates all non-matching snapshots)

• w（显示监视模式使用情况/可用操作）

  ¥w (displays watch mode usage / available actions)

以下内置功能键可以被覆盖：

¥The following keys for built-in functionality can be overwritten :

• p（测试文件名模式）

  ¥p (test filename pattern)

• t（测试名称模式）

  ¥t (test name pattern)

正如你所期望的，任何未由内置功能使用的密钥都可以被声明。尽量避免使用在各种键盘上难以获取的按键（例如 é、€），或者默认情况下不可见的按键（例如许多 Mac 键盘没有 |、\、[ 等字符的视觉提示）

¥Any key not used by built-in functionality can be claimed, as you would expect. Try to avoid using keys that are difficult to obtain on various keyboards (e.g. é, €), or not visible by default (e.g. many Mac keyboards do not have visual hints for characters such as |, \, [, etc.)

当冲突发生时

¥When a conflict happens

如果你的插件尝试覆盖保留密钥，Jest 将出错并显示一条描述性消息，例如：

¥Should your plugin attempt to overwrite a reserved key, Jest will error out with a descriptive message, something like:

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 数组设置）中先前存在的另一个第三方插件保留的密钥。发生这种情况时，你还会收到一条错误消息，试图帮助你解决该问题：

¥Third-party plugins are also forbidden to overwrite a key reserved already by another third-party plugin present earlier in the configured plugins list (watchPlugins array setting). When this happens, you’ll also get an error message that tries to help you fix that:

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.