Плагіни спостереження

Система плагінів спостереження Jest надає спосіб зайти до певних частин Jest та визначити запити меню режиму спостереження, які виконуватимуть код при натисканні клавіш. У поєднанні, ці функції дозволяють розвивати інтерактивний досвід користувача для вашого робочого процесу.

Інтерфейс плагіну спостереження

class MyWatchPlugin {
  // Додавання хуку в події життєвого циклу Jest
  apply(jestHooks) {}

  // Отримання інформацію за запитом щодо інтерактивних плагінів
  getUsageInfo(globalConfig) {}

  // Виконання при натисканні ключів з `getUsageInfo`
  run(globalConfig, updateConfigAndRun) {}
}

Хуки в Jest

Для підключення вашого плагіну в Jest, додайте шлях до нього в watchPlugins у вашій конфігурації Jest:

jest.config.js

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

Користувацькі плагіни спостереження можуть додавати хуки до подій Jest. Ці хуки можна додати з/без інтерактивного ключа в меню режиму спостереження.

apply(jestHooks)

Jest хуки можуть бути прикріплені шляхом реалізації методу apply. Даний метод отримує аргумент jestHooks, який дозволяє плагіну підключатися до певних частин життєвого циклу виконання тестів.

class MyWatchPlugin {
  apply(jestHooks) {}
}

Нижче наведені хуки, доступні в Jest.

jestHooks.shouldRunTestSuite(testSuiteInfo)

Повертає boolean (або Promise<boolean> для обробки асинхронних операцій), щоб вказати, чи треба запускати тест.

Наприклад:

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.shouldRunTestSuite(testSuiteInfo => {
      return testSuiteInfo.testPath.includes('my-keyword');
    });

    // або 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;
    });
  }
}

Інтеграція меню спостереження

Користувальницькі плагіни спостереження також можуть додавати або перевизначати функціонал в меню спостереження, визначаючи пару key/prompt в методі getUsageInfo та метод run для виконання ключа.

getUsageInfo(globalConfig)

Щоб додати ключ до меню спостереження, реалізуйте метод getUsageInfo, повертаючи key/prompt:

class MyWatchPlugin {
  getUsageInfo(globalConfig) {
    return {
      key: 's',
      prompt: '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. // <-- це наш плагін
 › Press Enter to trigger a test run.

note

Якщо ключ вашого плагіну вже існує як ключ за замовчуванням, ваш плагін перевизначить цей ключ.

run(globalConfig, updateConfigAndRun)

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: A representation of Jest's current global configuration
• updateConfigAndRun: дозволяє запуск тестів паралельно роботі інтерактивного плагіну.

class MyWatchPlugin {
  run(globalConfig, updateConfigAndRun) {
    // щось виконуватиметься.
  }
}

note

Якщо викличете метод updateConfigAndRun, ваш метод run не повинен приводити до значення true, бо це може викликати подвійний запуск.

Авторизовані ключі конфігурації

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

Персональні налаштування

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: змінює ключ плагіну.
• prompt: дозволяє користувачеві налаштувати текст у запиті плагіну.

If the user provided a custom configuration, it will be passed as an argument to the plugin constructor.

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

Вибір хорошого ключа

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 (очищення шаблонів фільтру)
• i (інтерактивне оновлення невідповідних знімків)
• q (вихід)
• u (оновлення всіх невідповідних знімків)
• w (вивід використання режиму спостереження / доступних дій)

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

• p (патерн імені тестового файлу)
• p (патерн імені тесту)

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

Коли трапляється конфлікт

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

Плагін спостереження YourFaultyPlugin спробував зареєструвати ключ `q`, який зарезервований внутрішньо для виходу з режиму спостереження. Please change the configuration key for this plugin.

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:

Плагін спостереження YourFaultyPlugin і TheirFaultyPlugin обидва намагаються зареєструвати ключ `x`. Please change the key configuration for one of the conflicting plugins to avoid overlap.