Jest Watch 插件开发实战掌握 watchPlugins 生命周期钩子与交互式菜单【免费下载链接】jestDelightful JavaScript Testing.项目地址: https://gitcode.com/gh_mirrors/je/jestJest 的 Watch 插件系统watchPlugins允许开发者钩入 Jest 在 watch 模式下的生命周期事件并在 watch 菜单中注册自定义按键交互从而把测试运行器深度整合进自己的工作流。本文以 docs/WatchPlugins.md 为骨架结合仓库中jest-watcher、jest-core、jest-config的源码实现完整讲解插件接口、三大生命周期钩子、交互菜单集成、配置白名单与按键冲突机制读完即可写出可复用、可发布的 Jest watch 插件。Watch 插件系统是什么Jest 的 watch 模式本身是一个围绕文件变更 → 重跑测试循环构建的交互式 CLI。内置功能如p按文件名过滤、t按测试名过滤、u更新快照、q退出本质上都是菜单项 按键处理的组合。Watch 插件系统把这种能力对外开放插件既能静默钩入Jest 的测试生命周期无需出现在菜单中也能注册交互项在菜单中显示提示按键后执行自定义代码。两者结合就可以做出贴合个人或团队工作流的交互体验。该能力由packages/jest-watcher包提供类型与基础设施WatchPlugin接口、JestHooks、BaseWatchPlugin、PatternPrompt、Prompt等见 packages/jest-watcher/src/index.ts由packages/jest-core的 watch 主循环负责加载、调度与按键分发见 packages/jest-core/src/watch.ts。Watch 插件的接口与最小实现一个 watch 插件就是一个类可选实现以下三个方法来自 packages/jest-watcher/src/types.ts 中的WatchPlugin接口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) {} }apply(jestHooks)向 Jest 生命周期注册钩子插件可以只有钩子、不参与菜单getUsageInfo(globalConfig)返回{key, prompt}让插件出现在 watch 菜单中返回null表示不参与菜单run(globalConfig, updateConfigAndRun)用户按下对应按键后执行返回Promisevoid | boolean。源码中WatchPlugin接口还声明了一个可选的onKey(value)方法见 packages/jest-watcher/src/types.ts用于在非激活状态下接收按键输入适合实现无菜单的轻量监听。基类 BaseWatchPlugin不想手写全部方法时可以继承packages/jest-watcher/src/BaseWatchPlugin.ts提供的抽象基类。它给出了各方法的默认实现apply为空操作、getUsageInfo返回null、run返回已 resolved 的 Promise并在构造函数中注入stdin/stdout两个流供插件读取键盘输入、向终端输出abstract class BaseWatchPlugin implements WatchPlugin { protected _stdin: ReadStream; protected _stdout: WriteStream; constructor({stdin, stdout}: {stdin: ReadStream; stdout: WriteStream}) {...} apply(_hooks: JestHookSubscriber): void {} getUsageInfo(_globalConfig: Config.GlobalConfig): UsageData | null { return null; } onKey(_key: string): void {} run(...): Promisevoid | boolean { return Promise.resolve(); } }注册到 Jest 配置在 Jest 配置中通过watchPlugins数组声明插件路径module.exports { // ... watchPlugins: [path/to/yourWatchPlugin], };配置规范化逻辑位于 packages/jest-config/src/normalize.tswatchPlugins分支字符串形式的条目会被解析为{config: {}, path: resolveWatchPlugin(...)}resolveWatchPlugin会基于rootDir和项目的 resolver 解析插件模块路径因此既支持 npm 包名也支持相对路径rootDir/path/to/plugin。如果模块无法解析Jest 会报错Watch plugin name cannot be found...该行为在 packages/jest-config/src/tests/normalize.test.ts 中有测试覆盖。通过 apply 钩入 Jest 生命周期apply(jestHooks)收到一个jestHooks订阅器对象它暴露三个钩子。底层机制在 packages/jest-watcher/src/JestHooks.tsJestHooks内部维护_listeners数组getSubscriber()返回的订阅器把监听函数 push 进数组getEmitter()返回的发射器在对应事件发生时依次调用所有监听器——因此多个插件可以同时订阅同一个事件。class MyWatchPlugin { apply(jestHooks) {} }jestHooks.shouldRunTestSuite(testSuiteInfo)返回布尔值或Promiseboolean决定某个测试套件是否应当运行。testSuiteInfo的结构见 packages/jest-watcher/src/types.ts 的TestSuiteInfo为{config: ProjectConfig, duration?: number, testPath: string}。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)); }); } }注意语义从 packages/jest-watcher/src/JestHooks.ts 的实现可见发射器对所有订阅者的返回值执行Promise.all后取every(Boolean)——即所有订阅了该钩子的插件都返回 true 时该套件才会被运行。这是实现按条件跳过套件例如只跑改动相关文件、按目录白名单过滤的关键约束。jestHooks.onTestRunComplete(results)每次测试运行结束时被调用参数为本次运行聚合后的完整测试结果AggregatedResult来自jest/test-result。class MyWatchPlugin { apply(jestHooks) { jestHooks.onTestRunComplete(results { this._hasSnapshotFailure results.snapshot.failure; }); } }典型用途是缓存运行结果供菜单交互使用例如记录本次是否有快照失败从而在菜单中动态决定是否显示更新快照入口。jestHooks.onFileChange({projects})文件系统发生变化watch 模式扫描到文件变更时被调用参数结构为见 packages/jest-watcher/src/types.ts 的JestHookExposedFSprojects: Array{config: ProjectConfig, testPaths: Arraystring}包含 Jest 正在监听的全部测试路径按项目分组多项目场景下每个项目一组。class MyWatchPlugin { apply(jestHooks) { jestHooks.onFileChange(({projects}) { this._projects projects; }); } }配合shouldRunTestSuite可以在onFileChange中记录最新的testPaths集合供运行时判断使用。交互式菜单集成要让插件出现在 watch 菜单中需要同时实现getUsageInfo声明按键与提示文案和run按键后的执行逻辑。getUsageInfo(globalConfig)返回{key, prompt}即可在菜单中增加一行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.:::note如果插件的 key 与内置默认 key 冲突你的插件会覆盖该内置 key但并非所有内置 key 都可覆盖见下文选择合理的按键。:::从源码看菜单中插件的排序并不完全按配置顺序packages/jest-core/src/lib/watchPluginsHelpers.ts会把内置插件isInternal: true排在第三方插件之前。run(globalConfig, updateConfigAndRun)按键事件到达时Jest 会先检查当前是否正在运行测试packages/jest-core/src/watch.ts中若isRunning为真会把testWatcher标记为interrupted并忽略该按键否则将插件置为activePlugin此时 Jest 不再自行处理按键把控制权交给插件随后调用插件的run方法class MyWatchPlugin { run(globalConfig, updateConfigAndRun) { // do something. } }run返回的 Promise 在插件想交还控制权时 resolve返回的布尔值表示交还控制后 Jest 是否要重跑测试对应 packages/jest-core/src/watch.ts 中shouldRerun为真时调用updateConfigAndRun()的逻辑。globalConfigJest 当前全局配置的表示类型为jest/types中的Config.GlobalConfig可更新的子集由 packages/jest-watcher/src/types.ts 的AllowedConfigOptions限定updateConfigAndRun允许插件在交互过程中触发一次带新配置的测试运行。:::note如果你调用了updateConfigAndRunrun方法就不应 resolve 为真值否则会触发双重运行。:::可授权的配置更新白名单出于稳定性与安全性考虑updateConfigAndRun只能更新白名单内的全局配置键。当前白名单如下点击链接可查看对应配置/CLI 参数的完整说明配置键对应文档baildocs/Configuration.mdchangedSincedocs/CLI.mdcollectCoveragedocs/Configuration.mdcollectCoverageFromdocs/Configuration.mdcoverageDirectorydocs/Configuration.mdcoverageReportersdocs/Configuration.mdnotifydocs/Configuration.mdnotifyModedocs/Configuration.mdonlyFailuresdocs/Configuration.mdreportersdocs/Configuration.mdtestNamePatterndocs/CLI.mdtestPathPatternsdocs/CLI.mdupdateSnapshotdocs/CLI.mdverbosedocs/Configuration.md从 packages/jest-watcher/src/types.ts 的AllowedConfigOptions源码看该类型还包含findRelatedTests、nonFlagArgs以及mode: watch | watchAll注意testPathPatterns在 watch 模式下是字符串数组形式。packages/jest-core/src/watch.ts中updateConfigAndRun的实现正是按这些键逐一解构并updateGlobalConfig后startRun其中updateSnapshot在每次运行结束后会被重置为非粘性状态。插件定制化插件可以通过配置数组形式传入额外选项module.exports { // ... watchPlugins: [ [ path/to/yourWatchPlugin, { key: k, // - your custom key prompt: show a custom prompt, }, ], ], };推荐的配置项名称key修改插件使用的按键prompt自定义插件在菜单中的提示文案。用户提供的自定义配置会被原样传给插件构造函数。从 packages/jest-watcher/src/types.ts 的WatchPluginClass定义可见构造器实际收到的 options 为{config, stdin, stdout}而 packages/jest-config/src/normalize.ts 会把数组形式的第二个元素存为config。因此插件中这样接收class MyWatchPlugin { constructor({config}) {} }注意这里的config即用户在watchPlugins数组里写的第二个元素默认{}与 Jest 的项目配置无关stdin/stdout则由 Jest 在实例化时注入见 packages/jest-core/src/watch.ts 中new ThirdPartyPlugin({config, stdin, stdout: outputStream})。选择合理的按键保留键与冲突处理Jest 允许第三方插件覆盖部分内置按键但并非全部。不可覆盖的保留键c清除过滤模式i交互式更新不匹配快照q退出 watch 模式u更新所有不匹配快照w显示 watch 模式用法/可用操作可以覆盖的内置键p测试文件名正则过滤t测试名正则过滤其余未被内置功能使用的键都可以自由认领。建议避免使用各种键盘上难以敲出的字符如é、€或默认不可见的字符例如许多 Mac 键盘对|、\、[等没有可视化提示。从源码看保留键的强制机制在 packages/jest-core/src/watch.ts 的RESERVED_KEY_PLUGINS映射中内置的UpdateSnapshotsPlugin键u用途updating snapshots与UpdateSnapshotsInteractivePlugin键i用途updating snapshots interactively带有forbiddenOverwriteMessageQuitPluginq也在映射中见 packages/jest-core/src/plugins/Quit.ts声明了isInternal: true。c、w则在内置按键的switch分发中直接处理。冲突发生时的行为若插件尝试注册保留键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.冲突检查实现在 packages/jest-core/src/watch.ts 的checkForConflicts函数中内置插件键先被登记进watchPluginKeys映射第三方插件逐个注册时若发现键已被占用且不可覆盖forbiddenOverwriteMessage存在或已被更早的第三方插件以overwritable: false占用即抛出ValidationError。这两类错误场景在 packages/jest-core/src/tests/watch.test.js 中均有回归测试forbids WatchPlugins overriding reserved internal plugins与第三方插件键冲突用例。若插件未实现getUsageInfo或返回的key为空getPluginKey返回null该插件不参与键注册自然也不产生冲突。端到端验证仓库中的插件示例仓库在e2e/watch-plugins/下提供了可运行的示例覆盖了 CommonJSjs/、ESMmjs/、.cjs与js-type-module等多种模块格式。以 e2e/watch-plugins/js/my-watch-plugin.js 为例其形态与文档接口完全一致apply/getUsageInfo/run三方法getUsageInfo中还演示了向控制台输出调试信息配套的 e2e/watch-plugins/js/tests/index.js 是一个普通测试文件用于验证插件的加载与运行。编写自己的插件时可以参照此结构在watch模式下用jest --watch启动验证菜单显示、按键分发与钩子触发是否符合预期。小结Jest 的 watch 插件系统由三个层次构成生命周期钩子applyshouldRunTestSuite/onTestRunComplete/onFileChange适合静默集成与智能过滤、交互菜单getUsageInforun适合需要用户输入的交互体验与配置白名单updateConfigAndRun的受控更新。理解 packages/jest-watcher/src/JestHooks.ts 的订阅/发射模型shouldRunTestSuite取所有订阅者结果与集、packages/jest-core/src/watch.ts 的按键调度与冲突校验以及 packages/jest-config/src/normalize.ts 的配置解析就能安全地设计出不与内置功能冲突、可在团队中共享的 watch 插件。【免费下载链接】jestDelightful JavaScript Testing.项目地址: https://gitcode.com/gh_mirrors/je/jest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考