Плагины для режима наблюдения

Система плагинов 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, добавьте его путь в watchPlugins в вашей конфигурации Jest:

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');
    });

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

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 выдаст сообщение об ошибке, подобное:

Плагин наблюдения YourFaultyPlugin попытался зарегистрировать клавишу q, которая зарезервирована внутри для выхода из режима наблюдения. Пожалуйста, измените конфигурацию ключа для этого плагина.

Сторонние плагины также запрещено переопределять клавишу, уже зарезервированную другим сторонним плагином, расположенным ранее в списке настроенных плагинов (настройка массива watchPlugins). В этом случае вы также получите сообщение об ошибке, которое поможет вам это исправить:

Плагины наблюдения YourFaultyPlugin и TheirFaultyPlugin оба попытались зарегистрировать клавишу x. Пожалуйста, измените конфигурацию ключа для одного из конфликтующих плагинов, чтобы избежать перекрытия.