监视插件

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

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)

通过实现 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(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（显示监视模式用法/可用操作）

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

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