Если вы уже тестировали API с помощью Postman или какого-либо другого инструмента, никаких особых трудностей возникнуть не должно. Cypress — отличный инструмент для тестирования, который в том числе очень полезен при тестировании API. В этой статье я расскажу о том, как написать тест API в Cypress. 

Эта статья является частью цикла статей об основах Cypress. Вы можете ознакомиться и с другими статьями в моем блоге, где я даю пошаговые объяснения основ Cypress, а также привожу советы о том, как сделать еще один шаг вперед. На какие темы я писал:

• Выбор элементов

• Куда пропали мои куки?

• Проверка существования элемента

• before(), beforeEach(), after() and afterEach()

• Проверка атрибутов, значения и текста

• xpath vs. CSS-селекторы

• Переменные

Команда .request()

Эта команда будет центром всего этого. Чтобы отправить простой запрос с помощью метода GET, можно вызвать его вот так:

cy.request('/api/boards')

Заметьте — на самом деле вам не нужно добавлять метод. Cypress оптимизирует свои команды для максимальной читабельности. Поэтому, если вы напишете подобный запрос, он автоматически будет с методом GET.

Если передать два аргумента в команду .request(), первый аргумент будет считаться методом, а второй будет URL-ом.

cy.request('DELETE', '/api/boards/9873789121')

Кроме того, я не указал полный URL. Это связано с тем, что /api/boards будут автоматически добавляться ко всему, что определено как baseUrl в cypress.json. 

Команда .request() может принимать максимум 3 аргумента. Третий будет телом запроса.

cy.request('POST', '/api/boards', {
  name: 'space travel plan'
})

Этот простой синтаксис очень полезен в тех случаях, когда вы хотите отправить кучу запросов в базу данных, чтобы быстро настроить данные для UI-теста. Мой друг Фурбо написал об этом отличную статью.

Передача нескольких атрибутов в команду .request()

Если вы хотите задать больше опций или просто дать команде .request больше контекста, можно передать один объект. Тот же запрос из предыдущего примера можно записать так:

cy.request({
  method: 'POST', 
  url: '/api/boards', 
  body: {
    name: 'space travel plan'
  }
})

Это также дает вам возможность передавать больше параметров, например, заголовки или параметры запроса:

cy.request({
  method: 'GET', 
  url: '/api/boards', 
  qs: {
    starred: 'true'
  },
  headers: {
    accept: 'application/json'
  }
})

Получение данных из запроса

Как только на запрос поступает ответ от сервера, вы можете получить доступ к информации с помощью команды .then(). Команда вернет все виды атрибутов, таких как тело ответа, код состояния, продолжительность и так далее.

cy.request({
  method: 'POST', 
  url: '/api/boards', 
  body: {
    name: 'space travel plan'
  }
}).then( (board) => {

  console.log(board.status) // 201
  console.log(board.duration) // 11
  console.log(board.body) 
/* 
  { 
    "name": "new board",
    "id": 39871447524,
    "starred": false,
    "created": "2022-01-17"
  }
*/
})

alias board, который используется в качестве параметра в функции .then(), может быть пропущен, если вы используете деструктурирование.

cy.request({
  method: 'POST', 
  url: '/api/boards', 
  body: {
    name: 'space travel plan'
  }
}).then( ({ status }) => {
  console.log(status) // 201
})

Таким образом, вам не нужно создавать именованный alias каждый раз, когда вы хотите получить некоторые данные из запроса. Если вы хотите узнать больше о деструктурировании, читайте мои статьи на эту тему.

Если вы хотите использовать данные из ответа где-то в другом месте теста, рекомендую к прочтению эту статью о работе с данными API или вот эту об использовании переменных в Cypress.

Проверка данных ответа

Теперь, когда мы получили данные с сервера, мы можем приступить к их проверке. В Cypress есть встроенная библиотека chai, которую вы можете использовать внутри своей команды .then().

cy.request({
  method: 'POST', 
  url: '/api/boards', 
  body: {
    name: 'space travel plan'
  }
}).then( ({ status }) => {
  expect(status).to.eq(201)
})

Тело ответа обычно хранится в формате JSON, а это означает, что если вы хотите найти определенный элемент в ответе и проверить его, вам нужно найти правильный путь. Более глубоко я погрузился в эту тему в этой статье, а простой пример будет выглядеть примерно так:

cy.request({
  method: 'GET', 
  url: '/api/boards', 
}).then( ({ body }) => {
  
  expect(body).to.have.length(2) // check number of items 
  expect(body[0].name).to.eq('space travel plan') // check first item in array

})

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

cy.request({
  method: 'GET', 
  url: '/api/boards', 
}).then( ({ body }) => {
  
  expect(body.length).to.be.greaterThan(1) // more than 1 item is in list
  expect(body[0].name).to.be.a('string') // the text 'space travel plan' is a string
  expect(body[0].id).to.satisfy((num) => { return num > 0 }) // id must be bigger than 0

})

Использование плагина cy-api 

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

Однако с плагином cy-api запрос и ответ отображаются в окне браузера, что позволяет удобно наблюдать за APi даже в GUI браузера. Этот плагин добавит команду .api() в библиотеку Cypress, а синтаксис очень похож на команду .request(). Единственное основное отличие состоит в том, что нельзя использовать простой синтаксис, показанный в начале статьи, а нужно каждый раз передавать полный объект.

cy
  .api({
    method: 'POST', 
    url: '/api/boards', 
    body: { name: 'new board' }
  })

Затем этот тест выполняет такую визуализацию в тесте:

Приглашаем всех желающих на открытое занятие «Отчет для автотестов», на котором обсудим, что происходит, когда автотест находит ошибку. Регистрация по ссылке.