О проекте
api-tests - утилита для автоматизированного тестирования REST API с поддержкой HTTP запросов и websocket соединений.
Для кого
Для всех, кто хочет быть уверен что все методы его API работают как требуется.
Общее описание
Утилита на основе конфигурационных файлов отправляет запросы к серверу и сверяет ответ с заданным. Можно описывать последовательные запросы с передачей промежуточных данных.
Все настройки описываются в файлах в формате YAML, отдельный файл - отдельное действие. Файлы можно группировать в папки. Тесты в отдельных папках не зависят друг от друга, тесты в одной папке взаимосвязаны и сортируются между собой по имени файла.
В описаниях тестов доступны переменные, которые можно принимать из переменных окружения, из файла init.yml, либо создавать в процессе выполнения тестов.
Группы тестов
Отдельные тесты можно группировать помещая их в отдельную папку. Порядок запуска отдельных групп не регламентирован и может в будущем измениться.
Так же можно запускать выполнение только определенных групп по маске передавая параметр --pattern, в этом параметре можно указать регулярное выражение.
Например, может быть такая структура (тесты с проверкой логина и регистрации):
.
└── auth
├── login
│ ├── 1-login.yml
│ ├── 2-check-auth.yml
│ └── init.yml
└── register
├── 1-register.yml
├── 2-check-auth.yml
└── init.yml
Пример запуска теста из папки auth/login:
api-tests --pattern auth/login
Файл init
В папке с тестами можно создать файл init.yaml или init.yml. Этот файл обрабатывается перед запуском группы. В данный момент в файле можно только определить набор переменных для тестов - в секции store.
Пример файла init.yml с объявлением трех переменных:
store:
host: localhost
login: ivan
password: qwrty123
Структура описания теста в файле
В файле теста могут быть несколько корневых секций:
- name - имя теста. Обязательное поле.
- request - http запрос к серверу.
- response - валидация ответа http запроса.
- receive - принятие сообщения из websocket канала.
- message - валидация сообщения из websocket канала.
request
Секция описывает HTTP запрос к серверу.
Может содержать следующие параметры:
- method - тип запроса (GET, POST, PUT...). По-умолчанию GET.
- protocol - тип запроса: http или websocket. По-умолчанию http.
- url - адрес запроса, например:
https://www.google.com/search?q=testsили, в случае websocket соединения -wss://site.com/ws-open. - headers - список отправляемых заголовков.
- body - тело запроса.
- timeout - время ожидания ответа в секундах. По-умолчанию - 5.
- channel - имя соединения. Websocket соединение сохраняется с этим именем и в будущем его можно использовать.
Пример файла с request. Отправляется POST запрос на адрес https://example.com/api/reports, в заголовках отправляется Content-Type: application/json, в теле запроса {"begin":1663099200000,"end":1663271999999}, время ожидания ответа - 30 секунд.
name: Отправляем POST запрос
request:
method: POST
url: 'https://example.com/api/reports'
headers:
Content-Type: application/json
body: '{"begin":1663099200000,"end":1663271999999}'
timeout: 30response
Секция может состоять из нескольких элементов:
- headers - валидация полученных заголовков - набор правил.
- code - валидация кода ответа - набор правил. Всегда проверяется только числовой статус (200, 301, 404 и другие...).
- body - валидация тела ответа - набор валидаторов
Валидатор
Валидатор регламентирует способ обращение к данным и правила, описывается параметрами type и rules. Параметр type может принимать значения из списка:
- json - можно обращаться к элементам по ключу.
- string - ответ сверяется как единое целое.
Параметр rules - это набор правил.
receive
Секция позволяет получать сообщение из вебсокет канала по фильтру. Имеет параметры:
- channel - имя вебсокет соединения
- timeout - время в секундах, сколько ждать сообщения
- filter - набор валидаторов для фильтра. Сообщение считается подходящим, если ни один из фильтров не выдал ошибку.
message
Секция валидирует сообщение, которое было получено в receive. Содержит набор правил.
Правило
Правило описывается параметрами:
- type - тип значения, которое проверяется (string, boolean, float, integer, jwt, hex, object, array)
- key - ключ значения
- equal - проверка значения на равенство
- not-equal - проверка значения на не равенство
- less - проверка на то, что значение меньше, чем указано
- greater - проверка на то, что значение больше, чем указано
- prefix - проверка на то, что значение содержит префикс
- suffix - проверка на то, что значение содержит суффикс
- required - указание на то что значение обязательно должно быть. По-умолчанию - true
- store - сохранение значения с указанным именем
- fields - правила для проверки вложенных значений (только для типов array и object)
Пример файла с валидацией ответа. Проверяется http код - должен быть 200 OK. Тело ответа проверяется как JSON. В ответе должны быть поля success типа boolean, в котором должно быть true, и поле data с JWT токеном, значение сохраняем в хранилище с именем token.
name: Авторизация
request:
method: POST
url: 'https://example-api.com/api/auth/login'
headers:
Content-type: application/json
body: '{"username":"roman","password":"qwerty123"}'
response:
code:
- equal: 200
body:
- type: json
rules:
- key: success
type: boolean
equal: true
- key: data
type: JWT
store: tokenЕще пример с проверкой ответа на равенство.
name: Список пользователей
request:
method: GET
url: 'https://example-api.com/api/users'
response:
body:
- type: string
rules:
- equal: '["roman","ivan"]'Пример с валидатором ответа как строка и проверкой того, что результат меньше, чем 10
name: Список пользователей
request:
method: GET
url: 'https://example-api.com/api/status'
response:
body:
- type: string
rules:
- type: integer
less: 10Валидация вложенных полей
Вложенные поля подерживаются только через валидатор json и с типами array и object.
Скажем некий API отдает такой ответ:
{
"data": {
"accounts": [
{
"name": "Ivan",
"email": "ivan@mail.com"
},
{
"name": "Roman",
"email": "roman@mail.com"
}
]
}
}Нам надо получить второй аккаунт и проверить имя. Это делается так:
# Имя теста
name: Получить второй аккаунт и проверить имя
# Отправляемый запрос
request:
method: GET
url: 'https://{{.TESTS_HOST}}/api/accounts'
# Валидация ответа
response:
body:
- type: json
rules:
# Обращаемся к data и получаем его как объект
- key: data
type: object
fields:
# Внутри data получаем accounts как массив
- key: accounts
type: array
fields:
# Получаем элемент по индексу 1 (второй элемент)
- key: 1
type: object
fields:
# Получаем поле name как string, проверим что там текст Roman
- key: name
type: string
equal: RomanК элементам массива можно обращаться по индексу, можно индекс не указывать - тогда пройдет валидация всех элементов массива.
Переменные
Во всех параметрах можно использовать переменные. Чтобы вставить значение переменной, вначале пишется {{., после имя переменной, и потом }}. Например {{.token}}.
Переменные можно обратиться к переменным окружения, но только к тем, имена которых начинаются на TESTS_.
Переменные можно определить в init файле, можно создавать во время выполнения указанием store у правила.
Переменные привязаны к группе тестов, это значит что внутри группы можно передавать данные между отдельными тестами, но не получится передавать данные между отдельными группами.
Пример двух файлов - в одном получаем токен, в другом используем. В тестах используем переменную окружения TESTS_HOST. В первом тесте создаем переменную token, во втором тесте - используем её.
1-auth.yml:
name: Авторизация
request:
method: POST
url: 'https://{{.TESTS_HOST}}/api/auth/login'
body: '{"username":"roman","password":"qwerty123"}'
response:
body:
- type: json
rules:
- key: data
type: JWT
store: token2-check-token.yml:
name: Авторизация
request:
method: GET
url: 'https://{{.TESTS_HOST}}/api/client/user/settings'
headers:
Authorization: 'Bearer {{.token}}'
response:
body:
- type: json
rules:
- key: success
type: boolean
equal: true
