Написание плагина

API плагинов позволяет вам подключаться к поведению Cypress и расширять его.

Примечание: Этот документ предполагает, что вы ознакомились с Руководством по плагинам.

API плагинов

Для начала откройте этот файл:

cypress/plugins/index.js

Файл плагина должен экспортировать функцию со следующей сигнатурой:

// cypress/plugins/index.js

// export a function
module.exports = (on, config) => {
  // configure plugins here
}

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

Экспортируемая функция вызывается всякий раз, когда проект открывается либо с помощью cypress open, либо с помощью cypress run.

Ваша функция будет получать 2 аргумента: on и config.

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

Если вы вернете или разрешите объект, Cypress объединит его с config, что позволит вам перезаписать конфигурацию или переменные среды.

on

on — это функция, которую вы будете использовать для регистрации слушателей на различных событиях, которые предоставляет Cypress.

Регистрация для прослушивания события выглядит так:

module.exports = (on, config) => {
  on('<event>', (arg1, arg2) => {
    // plugin stuff here
  })
}

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

config

config — это разрешенная конфигурация Cypress открытого проекта.

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

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

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

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

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

• configFile: Абсолютный путь к файлу конфигурации. По умолчанию это <projectRoot>/cypress.json, но может быть настроенным путем или false при использовании --config-file флага.
• projectRoot: Абсолютный путь к корню проекта (например, /Users/me/dev/my-project)
• version: Номер версии Cypress. Это может использоваться для обработки критических изменений.

Пожалуйста, ознакомьтесь с нашей документацией по API для изменения конфигурации здесь.

Список событий

Доступные события:

Контекст выполнения

Ваша pluginsFile вызывается при открытии Cypress проекта.

Cypress делает это, запуская независимый child_process, который затем requires в вашем pluginsFile. Это аналогично тому, как работают Visual Studio Code или Atom.

Код в этом файле будет выполнен с использованием версии Node, с которой запущен Cypress.

Модули npm

Когда Cypress выполняет вашу pluginsFile , он будет выполняться с process.cwd() , установленным в путь вашего проекта. Кроме того - вы сможете require любой модуль node, который вы установили.

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

Например, если ваш package.json выглядел так:

{
  "name": "My Project",
  "dependencies": {
    "debug": "x.x.x"
  },
  "devDependencies": {
    "lodash": "x.x.x"
  }
}

Тогда вы можете сделать любое из следующего в вашей pluginsFile:

// cypress/plugins/index.js

const _ = require('lodash') // yup, dev dependencies
const path = require('path') // yup, built in node modules
const debug = require('debug') // yup, dependencies
const User = require('../../lib/models/user') // yup, relative local modules

console.log(__dirname) // /Users/janelane/Dev/my-project/cypress/plugins/index.js

console.log(process.cwd()) // /Users/janelane/Dev/my-project

Обработка ошибок

Cypress запускает вашу pluginsFile в собственном дочернем процессе, поэтому она изолирована от контекста, в котором работает сам Cypress. Это означает, что вы не можете случайно изменить или изменить выполнение самого Cypress.

Если ваша pluginsFile имеет непредвиденное исключение, необработанное отклонение от Promise или синтаксическую ошибку - мы автоматически поймаем их и отобразим в консоли, а также в самом тестовом просмотре.

Ошибки из ваших плагинов не приведут к сбою Cypress.

Изменения файлов

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

С помощью Cypress мы автоматически следим за вашими pluginsFile и любые внесенные изменения вступят в силу немедленно. Мы прочитаем файл и снова выполним экспортированную функцию.

Это позволяет вам итерировать код плагина даже при уже запущенном Cypress.