Jest 監(jiān)視插件

Jest 監(jiān)視插件系統(tǒng)提供了一種方法，可以連接 Jest 的特定部分，并定義在按鍵時執(zhí)行代碼的監(jiān)視模式菜單提示。結(jié)合這些功能，你可以范圍根據(jù)自己的工作流程開發(fā)自定義的交互式體驗。

監(jiān)視插件界面

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

要將你的監(jiān)視插件連接到 Jest，請將其路徑添加?watchPlugins?到你的 Jest 配置中：

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

自定義監(jiān)視插件可以為 Jest 事件添加鉤子。在監(jiān)視模式菜單中，可以使用或不使用交互鍵來添加這些掛鉤。

apply(jestHooks)

可以通過實現(xiàn)該?apply?方法來附加 Jest 鉤子。此方法接收一個?jestHooks?參數(shù)，該參數(shù)允許插件掛鉤到測試運行生命周期的特定部分。

class MyWatchPlugin {
  apply(jestHooks) {}
}

下面是 Jest 中可用的鉤子。

jestHooks.shouldRunTestSuite(testSuiteInfo)

返回一個布爾值（或?Promise<boolean>?用于處理異步操作）以指定是否應(yīng)運行測試。

例如：

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)

在每次測試運行結(jié)束時調(diào)用。它將測試結(jié)果作為參數(shù)。

例如：

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

jestHooks.onFileChange({projects})

每當文件系統(tǒng)發(fā)生變化時被調(diào)用

• ?projects: Array<config: ProjectConfig, testPaths: Array<string>?：包括 Jest 正在觀察的所有測試路徑。

例如：

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

監(jiān)視菜單集成

自定義監(jiān)視插件還可以通過在?getUsageInfo?方法中指定鍵/提示對和?run?執(zhí)行鍵的方法來向監(jiān)視菜單添加或覆蓋功能。

getUsageInfo(globalConfig)

要向監(jiān)視菜單添加一個鍵，請實現(xiàn)該?getUsageInfo?方法，返回一個鍵和提示：

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

這將在監(jiān)視模式菜單中添加一行( ?? 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?返回的鍵的按鍵事件，可以實現(xiàn)該run?方法。此方法返回一個?Promise<boolean>? ，當插件想要將控制權(quán)返回給 Jest 時，可以解析這個 Promise。?boolean?指定 Jest 在獲得控件后是否應(yīng)重新運行測試

• ?globalConfig?: Jest 當前全局配置的表示
• ?updateConfigAndRun?：允許在交互式插件運行時觸發(fā)測試運行。

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

注意：如果調(diào)用?updateConfigAndRun?，你的?run?方法不應(yīng)解析為真值，因為這會觸發(fā)雙重運行。

授權(quán)配置密鑰

出于穩(wěn)定性和安全原因，只有部分全局配置鍵可以使用?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?：允許用戶自定義插件提示中的文本。

如果用戶提供了自定義配置，它將作為參數(shù)傳遞給插件構(gòu)造函數(shù)。

class MyWatchPlugin {
  constructor({config}) {}
}

選擇一把好鑰匙

Jest 允許第三方插件覆蓋其一些內(nèi)置功能鍵，但不是全部。具體來說，以下鍵是不可覆蓋的：

• ?c ?（清除過濾模式）
• ?i ?（以交互方式更新不匹配的快照）
• ?q ?（退出）
• ?u ?（更新所有不匹配的快照）
• ?w? （顯示手表模式使用情況/可用操作）

可以覆蓋以下內(nèi)置功能鍵：

• ?p ?（測試文件名模式）
• ?t ?（測試名稱模式）

正如你所期望的那樣，可以聲明任何未由內(nèi)置功能使用的密鑰。盡量避免使用在各種鍵盤上難以獲得的鍵（例如?é?, ?€?），或者默認情況下不可見的鍵（例如，許多 Mac 鍵盤沒有諸如?|?, ?\`?,?[`? 等字符的視覺提示）

發(fā)生沖突時

如果你的插件嘗試覆蓋保留鍵，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?數(shù)組設(shè)置）中先前存在的另一個第三方插件已經(jīng)保留的密鑰。發(fā)生這種情況時，你還會收到一條錯誤消息，試圖幫助你解決此問題：

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.