Осваиваем быстрый, маленький и простой инструмент тестирования API
“Когда я начал изучать HTTP-протокол и надо было работать с URL-ами и передаваемыми в них данными, в каждом найденном инструменте не хватало хорошей документации, или она была, но в виде избыточно сложных инструкций для простых вещей, типа отправки простого HTTP-запроса. Однажды обратил внимание на curl, которым раньше скачивал файлы, и это оказался лучший инструмент для изучения веб-API.
Этот материал требует базового знакомства с HTTP-протоколом, понимания что такое веб-API, а также умения работать с командной строкой в Windows, надеемся ты это умеешь.
Итак, поехали.
Настройка
Как всякий серьезный софт, curl требует установки в операционной системе. Хорошая новость: скорее всего, он уже установлен! Точнее, встроен в операционку. Уважающий себя тестировщик, разумеется, работает в Linux, а почти каждый дистрибутив Linux уже идет с curl. Более того, даже Windows 10 (начиная с версии 1803) поставляется с curl.
Проверим, есть ли в системе curl.
В Linux набираем в терминале:
curl --version
Если все-таки работаешь в Windows, то запускаешь cmd или, лучше, PowerShell:
curl.exe --version
Команда покажет версию curl, прикрепленные библиотеки, дату релиза, поддерживаемые протоколы и поддерживаемые функции. В Linux увидим следующее:
curl 7.68.0 (x86_64-pc-linux-gnu) libcurl/7.68.0 OpenSSL/1.1.1f zlib/1.2.11 brotli/1.0.7 libidn2/2.2.0 libpsl/0.21.0 (+libidn2/2.2.0) libssh/0.9.3/openssl/zlib nghttp2/1.40.0 librtmp/2.3 Release-Date: 2020-01-08 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp Features: AsynchDNS brotli GSS-API HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM NTLM_WB PSL SPNEGO SSL TLS-SRP UnixSockets
Если введенная команда выдала ошибку, то curl не установлен, значит его надо скачать и поставить. Еще одна хорошая новость: он бесплатный (но есть нюансы, о которых в конце). Есть версии для практически всех операционных систем, размер ехе-шника не превышает 5 Мб.
Если понадобилось ознакомиться с curl, а опыта с API нет, ситуацию облегчит тестовый httpbin-сервис, примеры с которым приведены далее в этом посте.
Примечание. С этого момента, будут приводиться исключительно «линуксовые» bash-команды, для ясности и читабельности. Если ты сидишь в Windows и примеры почему-то не работают, попробуй добавлять «.exe» после команды curl, или удалять (возможные) лишние пробелы в строках (line breaks).
Базовые опции
Несмотря на то, что Curl очень простой инструмент, он имеет множество различных функций. Начнем с ними знакомиться:
--requestили-X: Указывает нужный http-метод (здесь подробнее — желательно хорошо разобраться). Если опции нет, запрос по умолчанию обрабатывается как GET. Например:curl -X POST ...
--headerили-H: В HTTP-запрос добавляется дополнительный заголовок, их может быть сколько угодно. Например:curl -H "X-First-Name: John" -H "X-Last-Name: Doe" ...
--dataили-d: В запрос включаются какие-то данные. Они могут добавляться в той же строке, или указывать на текстовый файл, откуда считываются. Пример:curl -d "тут текстовые данные" ...
- —
-formили-F: curl эмулирует заполненную форму, с нажатием кнопки отправки. Допускается отправка бинарных файлов. Пример:curl -F name=John -F shoesize=11 ...
--user <user:password>или-u <user:password>: Логин и пароль для аутентификации на сервере.
curl показывает логи HTTP-транзакций в терминале. Если нужно еще больше подробностей, то curl сохраняет все в файлы для проверки при необходимости. Для это есть функции:
--dump-headerили-D: Сохраняет в указанный дамп-файл полученные заголовки. Пример:curl -D result.header ...--outputили-O: Выводит в указанный дамп-файл, минуя stdout. Пример:curl -o result.json ...
GET-метод
Мы познакомились с основами, пора перейти к более серьезным вещам.
Во первых, меняем текущую папку в командной оболочке, на домашнюю папку или на рабочий стол (desktop), чтобы легче было найти выведенные из curl файлы.
Делаем первые запросы:
curl -X GET "https://httpbin.org/get" \ -H "accept: application/json" \ -D result.headers \ -o result.json
В первой строке указываем curl выполнить HTTP-запрос GET-методом, по такому-то URL. Во второй строке добавляем заголовок, чтобы сервер знал, что нам отправить в ответе. В третьей строке прописываем вывод полученных заголовков в файл дампа, который мы назовем result.headers. В последней строчке даем указание вывести результат запроса в файл result.json.
Если все пошло как надо, после запуска команды в прописанной на первом этапе домашней папке появятся нужные файлы. В данном случае будет выглядеть так.
файл result.headers
HTTP/2 200 date: Thu, 02 Sep 2021 05:47:14 GMT content-type: application/json content-length: 169
В файле result.headers видим, что запрос успешно выполнен, с кодом ответа 200 (все ОК), от сервера получен таймкод ответа (timestamp), и все заголовки.
Файл result.json
{
"args": {},
"headers": {
"Accept": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/7.68.0"
},
"url": "https://httpbin.org/get"
}
В этом файле result.json находится тело ответа. Это данные, возвращенные сервером, в красивом JSON-формате (об особенностях формата читаем здесь).
POST-метод
Отправка простого текста
Сейчас попробуем отправить обычный текст (plaintext) на сервер, с помощью метода POST.
curl -X POST "https://httpbin.org/post" \ -H "accept: application/json" \ -H "Content-Type: text/plain" \ -H "Custom-Header: Testing" \ -d "I love hashnode" \ -D result.headers \ -o result.json
Как видим, в запрос включен кастомный заголовок "Custom-Header: Testing". Он должен отображаться в теле ответа.
Смотрим теперь в файл result.headers
HTTP/2 200 date: Fri, 03 Sep 2021 03:16:20 GMT content-type: application/json content-length: 182
и файл result.json
{
"data": "I love hashnode",
"headers": {
"Accept": "application/json",
"Content-Length": "15",
"Content-Type": "text/plain",
"Custom-Header": "Testing"
}
}
Видим, что сервер получил plaintext-сообщение с тестовым заголовком и вернул его обратно без изменений.
Параметры строки запроса
В curl поддерживается не только простой текст, но и достаточно сложные параметры типа:
curl -X POST "https://httpbin.org/post?name=Carlos&last=Jasso" \ -H "accept: application/json" \ -D result.headers \ -o result.json
файл result.headers
HTTP/2 200 date: Fri, 03 Sep 2021 03:30:47 GMT content-type: application/json content-length: 120
файл result.json
{
"args": {
"lastname": "Jasso",
"name": "Carlos"
},
"headers": {
"Accept": "application/json"
}
}
Сервер, как и предыдущем примере, правильно «зеркалит» параметры, которые curl отправил.
Отправка JSON-объекта
Поставим curl-у задачу посложнее, попытаемся отправить на сервер json-файл и посмотрим что получится:
curl -X POST "https://httpbin.org/post" \ -H "Content-Type: application/json; charset=utf-8" \ -d @data.json \ -o result.json
Тут мы добавили специальный заголовок Content-Type, сообщающий серверу, что ему посылается json-файл. Путь к файлу с данными указывается флагом -d с собачкой @, и далее путь к файлу (в нашем случае это будет текущая папка).
Вот содержимое файла data.json, который надо создать:
{
"name": "Jane",
"last": "Doe"
}
И файл result.json:
{
"data": "{ \"name\": \"Jane\", \"last\": \"Doe\"}",
"headers": {
"Accept": "*/*",
"Content-Length": "38",
"Content-Type": "application/json; charset=utf-8"
},
"json": {
"last": "Doe",
"name": "Jane"
}
}
И снова видим, как curl умеет корректно отправлять контент JSON-файлов на сервер.
Эмуляция отправки значений формы
Иногда может понадобиться имитировать отправку формы. Curl умеет и это:
curl -X POST "https://httpbin.org/post" \ -H "Content-Type: multipart/form-data" \ -F "FavoriteFood=Pizza" \ -F "FavoriteBeverage=Beer" \ -o result.json
Чтобы обозначить для сервера, что посылаются данные формы, добавляется заголовок с соответствующим MIME-типом (как показано выше), плюс параметр -F в каждом из полей и значений.
result.json:
{
"form": {
"FavoriteBeverage": "Beer",
"FavoriteFood": "Pizza"
},
"headers": {
"Accept": "*/*",
"Content-Length": "261",
"Content-Type": "multipart/form-data;"
}
}
Видим, что сервер получил форму и правильно обработал все поля.
Отправка файла
Выше мы демонстрировали достаточно простые действия. А как насчет передачи файла? Файлы передаются таким же образом, как формы выше. Отправим изображение из текущей папки:
curl -X POST "https://httpbin.org/post" \ -H "Content-Type: multipart/form-data" \ -F "FileComment=This is a JPG file" \ -F "image=@image.jpg" \ -o result.json
result.json:
{
"files": {
"image": "data:image/jpeg;base64,/9j/4AAQSkZJ..."
},
"form": {
"FileComment": "This is a JPG file"
},
"headers": {
"Accept": "*/*",
"Content-Length": "78592",
"Content-Type": "multipart/form-data;"
}
}
curl может потребоваться некоторое время чтобы отправить большой файл, а потом сервер вернет этот файл (причем закодированный в Base64). Curl должен правильно обработать такой запрос.
Другие методы
Можно попробовать «погонять» любые запросы, чтобы убедиться, как полезен бывает curl при тестировании API. В целом, обработка запросов зависит от типа API и имплементации метода.
Аутентификация
curl умеет проводить аутентификацию на сервере, когда по URL-адресу нужен ввод пользовательских имени-пароля. В этом случае httpbin получает ожидаемые имя и пароль в формате /basic-auth/{user}/{passwd} и сопоставляет значения с введенными. Если эти данные не введены, получается следующее:
curl -X GET "https://httpbin.org/basic-auth/carlos/secret" \ -H "accept: application/json" \ -D result.headers
result.headers:
HTTP/2 401 date: Fri, 03 Sep 2021 04:08:44 GMT content-length: 0
То есть код 401 (не прошла авторизация).
Добавим в запрос логин и пароль:
curl -X GET "https://httpbin.org/basic-auth/carlos/secret" \ -u carlos:secret -H "accept: application/json" \ -D result.headers
result.headers:
HTTP/2 200 date: Fri, 03 Sep 2021 04:14:19 GMT content-type: application/json content-length: 48
result.json:
{
"authenticated": true,
"user": "carlos"
}
Все хорошо, авторизация прошла успешно.
Curl позволяет авторизоваться и другими методами — например, с помощью токена. Токен просто отправляется в соответствующем заголовке.
Платный тариф
Уже должно быть понятно, что curl — полезная вещь для тестировщика. Чтобы в этом мнении укрепиться, рассмотрим еще некоторые нюансы.
Распространенные инструменты тестирования API — бесплатные, но в них чаще всего бывают платными функции командной работы. Или например, запросы к социальным сетям (Вконтакте и Facebook) блокированы в бесплатном тарифе, и это один из немногих минусов в столь приятном продукте.
В других похожих инструментах бывает слишком сложный интерфейс, но это не об curl. Для простоты, рекомендую работать в VSCode. Связка VSCode c curl — идеальная.
На скрине слева отрендеренный markdown-документ, справа полученные result.headers и result.json, и терминал внизу, куда тестировщику приходится глядеть чаще всего.
Вопреки убеждению, бытующему в определенных кругах, curl хорошо работает не только в REST-архитектуре, но и в SOAP.
Конечно, раскрыть все нюансы в одной статье невозможно, и чтобы продолжить знакомство с такой полезной вещью как curl, не обойтись без чтения официальной документации на их сайте. Там же и примеры использования.”