API препроцессоров

Препроцессор — это плагин, отвечающий за подготовку файла поддержки или файла теста для браузера.

Препроцессор может транспилировать ваш файл из другого языка (CoffeeScript или ClojureScript) или из более новой версии JavaScript (ES2017).

Препроцессор также обычно отслеживает исходные файлы на предмет изменений, снова обрабатывает их и уведомляет Cypress о повторном запуске тестов.

Примеры

Мы создали три препроцессора в качестве примеров для вашего ознакомления. Это полностью функциональные препроцессоры.

Код содержит комментарии, которые объясняют, как он использует API препроцессора.

• Препроцессор webpack
• Препроцессор Browserify
• Препроцессор Watch

См. также

В блоге Write Cypress Markdown Preprocessor показано, как написать собственный препроцессор файлов.

Значения по умолчанию

По умолчанию Cypress поставляется с уже установленным препроцессором webpack.

Препроцессор webpack обрабатывает:

• ES2015 и JSX через Babel
• TypeScript
• CoffeeScript 1.x.x
• Отслеживание и кэширование файлов

Вы хотите изменить значения по умолчанию для webpack?

Если вы уже используете webpack в своем проекте, вы можете передать свою конфигурацию webpack, как показано здесь.

Если вы не используете webpack в своем проекте или хотите сохранить большинство значений по умолчанию, вы можете изменить значения по умолчанию. Изменение настроек позволяет:

• Добавить собственные плагины Babel
• Изменить параметры для компиляции TypeScript
• Добавить поддержку CoffeeScript 2.x.x

Использование

⚠️ Этот код является частью файла плагинов и, следовательно, выполняется в среде Node.js. Вы не можете вызывать Cypress или cy команды в этом файле, но у вас есть прямой доступ к файловой системе и остальной операционной системе.

Для использования препроцессора, вам следует привязаться к событию file:preprocessor в вашем файле плагинов:

// plugins file
module.exports = (on, config) => {
  on('file:preprocessor', (file) => {
    // ...
  })
}

Функция обратного вызова должна возвращать одно из следующего:

• Promise*, который в конечном итоге разрешает путь к сгенерированному файлу**.
• Promise*, который в конечном итоге отклоняется с ошибкой, возникшей во время обработки.

* Promise должен разрешиться только после завершения записи файла на диск. Разрешение Promise — это сигнал о том, что файл готов к передаче в браузер.

** Сгенерированный файл — это файл, созданный препроцессором, который в конечном итоге будет передан в браузер.

Например, если исходный файл — это spec.coffee, препроцессор должен:

1. Скомпилировать CoffeeScript в JavaScript spec.js
2. Записать этот файл JavaScript на диск (пример: /Users/foo/tmp/spec.js)
3. Разрешить абсолютный путь к этому файлу: /Users/foo/tmp/spec.js

Эта функция обратного вызова может и будет вызываться несколько раз с тем же filePath.

Функция обратного вызова вызывается всякий раз, когда браузер запрашивает файл. Это происходит при каждом запуске тестов.

Не следует запускать новый наблюдатель каждый раз при вызове. Вместо этого кэшируйте наблюдатель и при последующих вызовах возвращайте promise, разрешающийся, когда последняя версия файла была обработана.

Объект файла

Объект file, переданный в функцию обратного вызова, имеет следующие свойства:

События файлов

Объект file, переданный в функцию обратного вызова, является обработчиком событий.

Получение события 'close'

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

// example
const watcher = fs.watch(filePath /* ... */)

file.on('close', () => {
  watcher.close()
})

Отправка события 'rerun'

Если отслеживать изменения файлов, отправьте rerun после завершения обработки файла, чтобы сообщить Cypress о необходимости повторного запуска тестов.

// example
fs.watch(filePath, () => {
  file.emit('rerun')
})

Публикация

Опубликуйте препроцессоры в npm с соглашением об именовании cypress-*-preprocessor (например, cypress-clojurescript-preprocessor).

Используйте следующие npm теги:

"keywords": [
  "cypress",
  "cypress-plugin",
  "cypress-preprocessor"
]

Вы можете отправить опубликованные плагины в наш список плагинов.