Insomnia - Инструкция по применению
Надежда Дудник - @protestinginfoСодержание:
* Введение
* Импорт коллекции
* Создание пользователя
* Работа с переменными и окружение
* Авторизация пользователя
* Получение токена
* Создание проекта
* аутентификация через вкладку "Headers"
* аутентификация через вкладку "Auth"
**Дополнение про автоматизацию получения токена для
методов, которые требуют токен на предъявителя.
* Общая информация про Insomnia
* Установка сертификата
* Возможности автоматизации
* Импорт OpenAPI документации
* Создание первого автотеста при создания пользователя
* Заключение
Введение
Прежде чем прочесть статью предлагаю подписаться на канал @protestinginfo, канал с тестами, полезными материалами и инструкциями.
Insomnia - инструмент для тестирования REST API (клиент взаимодействия с API)
Для примера я буду использовать мной любимый сайт Vikunja.
UI: https://try.vikunja.io/login
API documentation: https://try.vikunja.io/api/v1/docs
Скачать API Документацию из https://try.vikunja.io/api/v1/docs (найти "Download OpenAPI specification на странице")
_______________
Импорт коллекции
Открыть приложение Insomnia (версия Insomnia.Core-2023.4.0 для Mac / Windows). Я буду использовать приложение на Mac.
Найти кнопку "Import" и нажать на нее. Система предлагает загрузить данные.
Выбрать наш файл docs.json, скачанный из https://try.vikunja.io/api/v1/docs
Нажать на кнопку "Scan" -> "Import"
Коллекция загружена:
Выбрать коллекцию, и открывается содержимое коллекции:
_______________
Создание пользователя
Разберу самый первый запрос, который связан с регистрацией пользователя на сайте.
Папка "auth" -> запрос POST Register
_______________
Работа с переменными и окружение
Прежде чем разобраться с отправкой самого запроса, проанализирую, а где создать переменную, и где она хранится.
В адресной строке для POST запроса отображена переменная "_.base_url".
Выбрать "No Environment" в левом верхнем углу
Нажать на "Manage Environments".
Нажать на "+".
Указать название новой коллекции "Vikunja", создать переменную base_url внести данные как
{"base_url": "https://try.vikunja.io/api/v1"}
Нажать на кнопку "Close".
Окружение "Environment" как "Vikunja" выбрано сразу по умолчанию.
_______________
Нажать на "_.base_url" в адресной строке -> откроется всплывающее окно для редактирования переменной в окружении.
Проверить, что наше созданное значение base_url имеет следующий вид:
Нажать на кнопку "Done".
Указать в теле запроса значения на вкладке "Body -> JSON":
Нажать на кнопку "Send". Создан новый пользователь в системе. Ура :)!
Также есть вкладки "Auth", "Query", ''Headers", "Docs", их разберем чуть ниже.
_______________
Авторизация пользователя
Далее отправить следующий запрос на авторизацию пользователя
Папка "auth" -> запрос POST Login
Получение токена
и получить токен в ответе от сервера. Согласно документации используется JWT-Auth:
Authorization: Bearer <jwt-token>Указать в теле запроса значения на вкладке "Body -> JSON":
Нажать на кнопку "Send". Пользователь авторизован в систему. Получен токен. Ура :)!
_______________
Создание проекта
Теперь используем созданный токен в запросе для создания проекта.
Найти папку "project", раскрыть ее, выбрать запрос
Папка "project" -> PUT Creates a new project
Есть два способа, где можно указать переменную для токена (время жизни токена 30 минут или пользователь будет удален из системы через 30 минут).
- способ через вкладку "Headers"
- способ через вкладку "Auth"
Предусловие: Выбрать "Vikunja" окружение в левом верхнем углу -> Выбрать "Manage Environments" -> Добавить новую переменную c значением:
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6IiIsImVtYWlsUmVtaW5kZXJzRW5hYmxlZCI6ZmFsc2UsImV4cCI6MTY5MjYyNTE3NSwiaWQiOjIsImlzTG9jYWxVc2VyIjp0cnVlLCJsb25nIjp0cnVlLCJuYW1lIjoiIiwidHlwZSI6MSwidXNlcm5hbWUiOiJVc2VyTmFtZSJ9.QFcn0BDkmh2bF2fpZocxOrUoVVSra8c1cNE9beROYZA"
Нажать на кнопку "Close".
_______________
* Аутентификация через вкладку "Headers"
Разберем 1 способ через вкладку "Headers".
Выбрать вкладку "Headers".
Нажать на "_.api_key" -> откроется всплывающее окно для редактирования переменной в окружении.
Отредактировать "_.api_key" на "_.token" и нажать на кнопку "Done"
Установленная переменная имеет вид как "_.token", и в начале обязательно добавить слово "Bearer" и пробел - важно указать для заголовка "Authorization", так как токен на предъявителя.
Отредактировать тело запроса на вкладке "JSON" согласно требованию и нажать на кнопку "Send".
Если честно, можно просто в теле запроса указать только :)
{ "title": "my project"}
_______________
* Аутентификация через вкладку "Auth"
Разберем 2 способ через вкладку "Auth".
Выбрать вкладку "Auth" , нажать на стрелочку вниз (точнее раскрыть) и выбрать тип аутентификации "Bearer Token"
Отображается следующий вид:
Начать вводить значение {{_ в поле "TOKEN"
и выбрать переменную "_.token". Нажать на кнопку "Send".
Создан новый проект! Ура!)
**Дополнение про автоматизацию получения токена для методов, которые требуют токен на предъявителя.
Предусловие: Выбрать "Vikunja" окружение в левом верхнем углу -> Выбрать "Manage Environments" -> Добавить новую переменную c значением:
Request -> OAuth 2.0 Access Token
После того как выбрано данное значение будет следующий вид:
Нажать на {% request 'oauth2', '', 0 %}
Далее выполнить конфигурацию, выбрать "Response - reference values from other request's responses"
Будет отображено следующее окно, данные поля важно заполнить следующими значениями:
- Атрибут - значение из тела ответа от сервера
- Запрос - авторизация пользователя "POST Login"
- Указать конкретный ключ, начиная с $., а именно $.token, и в "Live Preview" сразу отображается значение токена.
- Trigger Behavior говорит о том, что когда токен затухает, то еще раз отправить запрос на авторизацию пользователя
- Можно нажать на "Refresh", токен обновится
- Нажать на "Done"
Будет отображаться следующее окно, ВАЖНО указать значение токена в кавычках!
"token": "Response -> Body Attribute"
сама команда выглядит так:
"token": "{% response 'body', 'req_d2e9a976eb4d4e6595011784f232df4a', 'b64::JC50b2tlbg==::46b', 'when-expired', 60 %}"
Закрыть окно "Manage Environments".
Выбрать вкладку "Auth" , нажать на стрелочку вниз (точнее раскрыть) и выбрать тип аутентификации "Bearer Token". Начать вводить значение {{_ в поле "TOKEN" и выбрать переменную "_.token". Нажать на кнопку "Send".
Ура! Проект создан! Главное не забываем создать пользователя, авторизоваться в систему, и токен таким способом будет получаться автоматически.
Для других запросов можно также "вытащить" необходимые значения.
___________________
Общая информация про Insomnia
Insomnia поддерживает отправку запросов через HTTP, gRPC, GraphQL, WebSocket.
для HTTP request:
Вкладки "Body" (указание тела запроса), "Auth" (указание типа авторизации), "Query" (указание параметров), ''Headers" (указание HTTP заголовков запроса), "Docs" (указание документации OpenApi для запроса
Для запроса можно сделать следующие действия:
Особенно важная функция как "Generate Code".
Для HTTP response:
Вкладки "Preview or Source or Raw" (указание тела ответа от сервера), ''Headers" (указание HTTP заголовков ответа), "Cookies", "Timeline" (информация про временные особенности)
Например, Timeline при создании проекта
Preparing request to https://try.vikunja.io/api/v1/projects
* Current time is 2023-07-22T21:30:46.171Z
* Enable automatic URL encoding
* Using default HTTP version
* Enable SSL validation
* Too old connection (567 seconds), disconnect it
* Connection 6 seems to be dead!
* Closing connection 6
* TLSv1.2 (IN), TLS header, Supplemental data (23):
* TLSv1.2 (OUT), TLS header, Supplemental data (23):
* TLSv1.3 (OUT), TLS alert, close notify (256):
* Hostname in DNS cache was stale, zapped
* Trying 116.203.32.97:443... и т.д
___________________
Установка сертификата
Про установку сертификата (например, для финтеха это самое первое, что нужно сделать прежде чем отправить запрос).
Выбрать "Collection Settings" -> "Client Certificates". Нажать "New Certificate"
Все необходимые файлы и хосты должны предоставить коллеги (админы, спросите в общем чате).
Указать "Host", нажать на "Choose Cert" и "Choose Key", добавить файлы.
Нажать на кнопку "Create Certificate".
Режим просмотра:
Для нашей работе в настройках запроса убрать галочки в чек-боксах "Send cookies automatically" и "Store cookies automatically":
___________________
Возможности автоматизации
Инструмент позволяет сделать тестовые сценарии: негативные и позитивные, используется язык JS для автоматизации, позволяет проводить прогоны и получать отчет прогона и сформировать CI для автозапуска из консоли.
Импорт OpenAPI документации
Нажать на иконку "Домашняя страница" -> "Найти All Files" -> "Documents" -> Нажать на "+"
Система отображает всплывающее окно "Create New Design Document", оставить "my-spec.yaml" и нажать на кнопку "Create"
Создан New Document. Отображены три вкладки "DESIGN", "DEBUG", "TEST".
Нажать на кнопку "Import OpenAPI" -> Выбрать "File".
Выбрать наш файл docs.json, скачанный из https://try.vikunja.io/api/v1/docs
Отображена документация "Vikunja API".
___________________
Создание первого автотеста при создания пользователя
Выбрать вкладку "DEBUG" - > Добавить запрос на создание пользователя ->
Предупреждаю, что при повторном создании пользователя необходимо изменить почту и имя пользователя.
Так как я уже создала пользователя, то для автотеста я изменю значения почты и имени для пользователя.
Выбрать вкладку "TEST" - > Найти и нажать "New Test Suite" ->
Указать название "Tests" -> Нажать на кнопку "Create Suite"
Нажать на кнопку "New Test" -> Оставить дефолтное название "Returns 200" (так как при создании пользователя возвращается статус код 200) -> нажать на "New Test"
Выбрать dropdown "Select Request" -> Выбрать наш запрос на "Создание пользователя (регистрация)" из вкладки "DEBUG"
Insomnia предлагает дефолтный фрагмент кода:
const response1 = await insomnia.send();
expect(response1.status).to.equal(200);
Нажать на кнопку "Run Tests".
Успешно выполнен тест, статус указан "Passed".
Повторно нажать на кнопку "Run Tests".
Тест провален, статус указан "Failed".
Ура, написан простейший автотест.
Еще примеры:
Предусловия: изменены почта и имя пользователя на вкладке "DEBUG"
Добавлены два теста на отправку регистрации пользователя "Response body has property Id" и ''Response body is json object". Каждый раз отправляется новый тест, поэтому второй тест будет отображать ошибку, что такой пользователь существует (для этого случая будет создан новый тест "User already exists".
Код для тренировки:
1 тест "Response body has property Id"
const response1 = await insomnia.send();
const body = JSON.parse(response1.data);
const item = body;
expect(item).to.have.property("id");
2 тест ''Response body is json object"
const response1 = await insomnia.send();
const resp_body = JSON.parse(response1.data);
expect(resp_body).to.be.an('object');
3 тест на проверку, что такой пользователь существует ("User already exists").
const response1 = await insomnia.send();
expect(response1.status).to.equal(400);
const body = JSON.parse(response1.data);
const item = body;
expect(item).to.have.property("code");
expect(item).to.have.property("message");
Больше информации про скрипты в официальной документации.
___________________
Заключение
А еще есть такие возможности: встроенный DevTools, конвертация запроса в код, JSON|XML - читабельный вид (Beautify JSON), есть подсказки на валидацию введенных значений, история запросов.
Следующие посты хочу написать про Cookies в Insomnia и про console.log и встроенный DevTools, а также про другие возможности Insomnia!
P.S. Подписи к картинкам обязательно добавлю.
Ставьте реакцию для вдохновения, рекомендуйте статью для коллег!
Благодарю за прочтение.
С уважением, Надежда Дудник, главный инженер по тестированию в финтехе и ментор по тестированию ПО.