Привет! Меня зовут Анатолий Калмыков, и я отвечаю за качество создаваемых решений в компании Ростелеком ИТ.

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

WireMock – это одновременно и утилита и библиотека на java для создания HTTP заглушек над веб-сервисами. Он создает HTTP-сервер, к которому мы могли бы подключиться, как к реальному веб-сервису. Сегодня речь пойдет исключительно о WireMock в амплуа утилиты, standalone http сервер, который можно настроить как душе угодно, не зная языков программирования.

Содержание

• Кейсы, которые наталкивают на использование HTTP заглушек

• Разворачиваем WireMock

• Создание заглушки

• Сопоставление запросов к заглушкам

• Журналирование

Кейсы, которые наталкивают на использование HTTP заглушек

• Веб-сервисы могут быть не всегда доступны из-за технических обновлений, подвержены перегрузкам или ошибкам сетевых протоколов;

• Если поставщик сервиса находится далеко, сетевая среда нестабильная и при вызове сервиса происходит задержка, то время прохождения тестов может значительно увеличиваться;

• Тесты покрывают не все возможные варианты ответов сервиса. Не всегда есть возможность получить некоторые ответы от реального веб-сервиса и промоделировать все рабочие ситуации — следовательно, максимально полно протестировать взаимодействие;

• Не всегда можно воспроизвести нестандартные ситуации с реальным веб-сервисом, например эмуляция различных ошибок в HTTP протоколе, эмуляция задержки на уровне сетевого соединения;

• Доступ к рабочим веб-сервисам ограничен. Встречается ситуация, когда рабочие сервисы недоступны из тестового контура, в котором программисты ведут разработку. Это делает как по причине безопасности, так и для того, чтобы не подвергать лишней нагрузке рабочее окружение;

• Из-за ошибок разработки могут быть подвергнуты риску реальные данные. Например, есть веб-сервисы, которые позволяют добавлять или изменять данные в удаленной системе. Ошибка при вызове такого сервиса может привести к потере данных;

• Тестовые данные, которые используются в тест-кейсах не всегда имеют постоянность на том или ином сервисе, и если нету возможности достать данные из какой-нибудь базы данных, то приходится постоянно поддерживать данные тесты в актуальном состоянии;

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

Разворачиваем WireMock

Чтобы начать пользоваться всеми прелестями данного инструмента, его нужно для начала развернуть. Где разворачивать уже принципиально ваши предпочтения, я лишь могу дать рекомендации. Для начала рекомендую его поднять на локальной машине, не важно, что у вас за ось, linux, windows или maс, главное, чтобы у вас стояла java 8 версии и выше либо docker. Развернуть на локальной машине нужно исключительно для того, чтобы попрактиковаться с API WireMock. Попрактиковавшись, его необходимо будет развернуть на каком-нибудь сервере, который находится внутри вашей корпоративной сети. Зачем это нужно? Дело в том, что у многих проекты приватные, которые не имеют доступ из вне и скорее всего развернув WireMock на своем локальном ПК, у веб-сервиса, который будет повернут на ваш WireMock не будет сетевого доступа, следовательно у вас ничего не получится. Поэтому в перспективе WireMock необходимо развернуть на сервере, который находится внутри вашей корпоративной сети.

Для того, чтобы поднять WireMock необходимо сначала скачать standalone jar WireMock из официального репозитория, далее открываем консоль в репозитории, где находятся исполняемые файлы и выполняем следующую команду:

java -jar wiremock.jar

В данном случае WireMock поднимется на порту 8080, если хотите можно также поднять его в docker контейнере выполнив следующую команду:

docker run -it --rm -p 8080:8080 --name wiremock wiremock/wiremock:2.33.2

Аналогично в таком случае будет запущен контейнер с WireMock на борту, который доступен на порту 8080. Это минимальное что нужно сделать, но для того, чтобы активировать большую часть функций необходимо воспользоваться параметрами запуска, о них сейчас и поговорим.

У WireMock масса параметров запуска, мы затронем самые основные:

Параметры нужно передавать при старте WireMock дальше их изменить можно только при перезапуске.

Пример оптимального набора параметров для нагрузочного тестирования:

java -jar wiremock.jar \
	--global-response-templating \
	--container-threads 120 \
	--no-request-journal \
	--async-response-enabled true \
	--async-response-threads 80

У wiremock есть расширение Webhooks and Callbacks, настоятельно рекомендую его использовать, так как оно дает возможность создания заглушек для асинхронных инфопотоков. Более подробно данное расширение разберем в следующей части.

Для работы расширения требуется уже java 11 версии и выше, а также требуется скачать само расширение с официального репозитория. Данное расширение нужно положить в папку, где лежит основной jar файл WireMock, далее открываем консоль в репозитории, где находятся исполняемые файлы и выполняем следующую команду:

java -cp wiremock.jar:wiremock-webhooks.jar \
	com.github.tomakehurst.wiremock.standalone.WireMockServerRunner \
	--extensions org.wiremock.webhooks.Webhooks \
	--global-response-templating \
	--max-request-journal-entries 1000

Для запуска в docker, необходимо файл с расширением положить в папку extensions, и при запуске указать путь до нее:

docker run -it --rm -p 8080:8080 --name wiremock \
	-v $PWD/extensions:/var/wiremock/extensions wiremock/wiremock:2.33.1 \
	--extensions org.wiremock.webhooks.Webhooks \
	--global-response-templating \
	--max-request-journal-entries 1000

Создание заглушки

После того как вы подняли WireMock, по пути http://{{host}}:{{port}}/__admin будет доступно API для настройки WireMock, можно сделать первую заглушку, отправим запрос на WireMock:

POST http://{{host}}:{{port}}/__admin/mappings
{
    "name": "Простая заглушка - Привет мир!",
    "request": {
        "method": "GET",
        "url": "/some/thing"
    },
    "response": {
        "status": 200,
        "body": "Hello world!",
        "headers": {
            "Content-Type": "text/plain"
        }
    }
}

В ответ придут параметры сконфигурированной заглушки и её идентификатор, с помощью которого в дальнейшем можно применять CRUD операции над созданной заглушкой. Данный запрос сделает заглушку, которая вернет в ответе текст Hello world если отправим GET запрос по пути http://{{host}}:{{port}}/some/thing.

Тело запроса состоит из трех корневых параметров:

• name – название заглушки, советую использовать его всегда и называть заглушки такими именами, что бы вы потом не запутались в массе созданных заглушек;

• request – объект сопоставления запросов к заглушкам, подробнее его разберем далее;

• response – объект, в котором настраиваются параметры ответа, подробнее его разберем далее.

После создания заглушки, можно получить её параметры следующим запросом:

GET http://{{host}}:{{port}}/__admin/mappings/{{mockId}}

Изменить заглушку можно следующим запросом:

PUT http://{{host}}:{{port}}/__admin/mappings/{{mockId}}
{
    "name": "Простая заглушка - Привет мир!",
    "request": {
        "method": "GET",
        "url": "/some/thing"
    },
    "response": {
        "status": 200,
        "body": "Hello!",
        "headers": {
            "Content-Type": "text/plain"
        }
    }
}

Удалить заглушку можно следующим запросом:

DELETE http://{{host}}:{{port}}/__admin/mappings/{{mockId}}

Сопоставление запросов к заглушкам

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

• Метод

• URL

  • Протокол

  • Хост

  • Порт

  • Параметры пути

  • Параметры запроса

• Заголовки

  • Авторизация

  • Cookies

  • Прочие заголовки

• Тело запроса

В WireMock можно сделать сопоставление по всем частям HTTP запроса, причем можно комбинировать между сопоставлениями по различным частям, а также использовать условия OR и AND ко всем сопоставлениям.

Мы уже сталкивались с объектом request, который содержит сопоставления, теперь настало время рассмотреть все его параметры более детально в данном разделе.

Сопоставление по url

url – строгое сопоставление по параметрам пути и параметрам запроса, нужно понимать что если вы сделали сопоставление на определенные параметры запроса и к примеру добавится какой то новый параметр или вовсе изменится порядок определения параметров запроса, то строгое сопоставление не сработает.

{
    "request": {
        "url": "/match/url"
        ...
    },
    ...
}

Таблица сопоставления:

Сопоставление по urlPath

urlPath – строгое сопоставление по параметрам пути игнорируя параметры запроса.

{
    "request": {
        "urlPath": "/match/url"
        ...
    },
    ...
}

Таблица сопоставления:

Сопоставление по urlPattern

urlPattern – сопоставление по параметрам пути и параметрам запроса, на вход принимает регулярное выражение, которое можно гибко настроить под различные конфигурации параметров пути и параметров запроса.

{
    "request": {
        "urlPattern": "/match/url.*?id=[0-9]{4}"
        ...
    },
    ...
}

Таблица сопоставления:

Сопоставление по urlPatternPath

urlPatternPath – сопоставление по параметрам пути, на вход принимает регулярное выражение, которое можно гибко настроить под различные конфигурации параметров пути.

{
    "request": {
        "urlPathPattern": "/match/url/[0-9]{4}"
        ...
    },
    ...
}

Таблица сопоставления:

Сопоставление по method

method – параметр для сопоставления по методу запроса, в качестве значения принимает название методов HTTP запроса, так-же может принимать на вход параметр ANY, который будет делать сопоставление к любому методу HTTP запроса.

Пример сопоставления по определенному методу:

{
    "request": {
        "method": "POST",
        ...

    },
    ...
}

Таблица сопоставления:

Пример сопоставления к любому методу:

{
    "request": {
        "method": "ANY",
        ...
    },
    ...
}

Таблица сопоставления:

Сопоставление по basicAuth

basicAuth – параметр который позволяет сопоставить заглушку к запросу, который идет с базовой авторизацией.

{
    "request": {
        ...
        "basicAuth": {
            "username": "user",
            "password": "pass"
        },
        ...
    },
    ...
}

Таблица сопоставления:

Сопоставление по headers

headers – объект сопоставления по заголовкам HTTP запроса, в качестве ключей данного объекта выступает название заголовков, в свою очередь данные ключи в качестве значений имеют также объект, содержимое которого один из условных операторов с параметрами условного оператора, у WireMock есть масса условных операторов, примеры с разными условными операторами разберем ниже.

Пример сопоставления по заголовку и условию equalTo:

{
    "request": {
        ...
        "headers": {
            "testHeader": {
                "equalTo": "xml",
                "caseInsensitive": true
            }
        }
    },
    ...
}

Условие equalTo выполняется только в том случае если полученное значение строго равно значению, указанному в условии. У данного условия есть параметр caseInsensitive, который делает условие менее строгое позволяя игнорировать регистр букв, данный параметр опционален.

Таблица сопоставления:

Пример сопоставления по заголовку и условию contains:

{
    "request": {
        ...
        "headers": {
            "testHeader": {
                "contains": "xml"
            }
        }
    },
    ...
}

Условие contains выполняется только в том случае если значение условия входит в полученное значение.

Таблица сопоставления:

Пример сопоставления по заголовку и условию matches:

{
    "request": {
        ...
        "headers": {
            "testHeader": {
                "matches": "xml.*"
            }
        }
    },
    ...
}

Условие matches выполняется только в том случае если значение условия, которое является регулярным выражением сопоставится с входным значением.

Таблица сопоставления:

Пример сопоставления по заголовку и условию absent:

{
    "name": "Match headers absent",
    "request": {
        ...
        "headers": {
            "testHeader": {
                "absent": true
            }
        }
    },
    ...
}

Условие absent выполняется только в том случае если заголовок (или другой параметр, к которому применяется условие) будет отсутствовать в запросе. Отмечу что значением условия, может быть либо true либо false, причем поведение условия никак неизменно при разных параметрах.

Таблица сопоставления:

Пример сопоставления по заголовку и условию after:

{
    "request": {
        ...
        "headers": {
            "testHeader": {
                "after": "2022-04-22T00:00:00Z",
                "actualFormat": "dd/MM/yyyy"
            }
        }
    },
    ...
}

Условие after работает с датой и временем, выполняется только в том случае если полученная временная метка больше временной метки, указанной в условии. Значением условия является временная метка согласно стандарту ISO-8601. В качестве значения также можно указать следующие комбинации:

• now +15 days – будет выбрана текущая дата по Гринвичу плюс 15 дней;

• now -15 days – будет выбрана текущая дата по Гринвичу минус 15 дней;

• now +2 months – будет выбрана текущая дата по Гринвичу плюс 2 месяца.

Условие имеет три опциональных параметра actualFormat, expectedOffset и expectedOffsetUnit. Параметр actualFormat указывает формат временной метки, если данный параметр отсутствует, то WireMock ожидает значение согласно стандарту ISO-8601. Параметры expectedOffsetUnit и expectedOffset работают совместно, первый является единицей сдвига (days, months, years), второй числом, на которое нужно сдвигать указанную дату.

Аналогично условию after есть условия before и equalToDateTime. Первое выполняется только в том случае если полученная временная метка меньше временной метки, указанной в условии. Второе выполняется только в том случае если полученная временная метка строго равна временной метки, указанной в условии.

Таблица сопоставления:

Пример сопоставления по заголовку и условию and:

{
    "request": {
        ...
        "headers": {
            "testHeader": {
                "and": [
                    {
                        "after": "2022-04-22T00:00:00Z",
                        "actualFormat": "dd/MM/yyyy"
                    },
                    {
                        "before": "2022-04-30T00:00:00Z",
                        "actualFormat": "dd/MM/yyyy"
                    }
                ]
            }
        }
    },
    ...
}

Условие and является массивом объектов, в качестве объектов выступают другие условия, все перечисленные условия в массиве трактуются как И. В данному случае используется два условия after и before для того, чтобы можно было сопоставить входящее значение к временному диапазону. Аналогично условию and есть условие or, которое также является массивом объектов, только все условия, которые находятся в данном массиве трактуются как ИЛИ. Условиями and и or можно комбинировать в более сложные условия.

Таблица сопоставления:

Сопоставление по queryParameters

queryParameters – объект сопоставления по параметрам запроса, в качестве ключей данного объекта выступает название параметра, в свою очередь данные ключи в качестве значений имеют также объект, содержимое которого один из условных операторов с параметрами условного оператора. Основную часть условных параметров рассмотрели при сопоставлении с заголовками, данные условия также распространятся и на queryParameters.

Пример сопоставления по параметрам запроса и условию after:

{
    "request": {
        ...
        "queryParameters": {
            "operationDate": {
                "after": "2022-04-22T00:00:00Z",
                "actualFormat": "dd/MM/yyyy"
            }
        }
    },
    ...
}

Таблица сопоставления:

Сопоставление по cookies

cookies – объект сопоставления по cookies запроса, в качестве ключей данного объекта выступает атрибут cookies, в свою очередь данные ключи в качестве значений имеют также объект, содержимое которого один из условных операторов с параметрами условного оператора. Основную часть условных параметров рассмотрели при сопоставлении с заголовками, данные условия также распространятся и на cookies.

Пример сопоставления по cookies запроса и условию contains:

{
    "request": {
        ...
        "cookies": {
            "session": {
                "contains": "12345"
            }
        }
    },
    ...
}

Таблица сопоставления:

Сопоставление по bodyPatterns

bodyPatterns – массив объектов сопоставления по телу запроса, в качестве индексов массива выступают объекты, содержимое которых один из условных операторов с параметрами условного оператора. Основную часть условных параметров рассмотрели при сопоставлении с заголовками, данные условия также распространятся и на bodyPatterns, в этом разделе также будут рассмотрены другие более сложные условия.

Пример сопоставления по телу запроса и условию equalToJson:

{
    "request": {
        ...
        "bodyPatterns": [
            {
                "equalToJson": [
                    {
                        "results": 4,
                        "status": "ACTIVE"
                    },{
                        "results": 5,
                        "status": "PASSIVE"
                    }
                ],
                "ignoreArrayOrder": true,
                "ignoreExtraElements": true
            }
        ]
    },
    ...
}

Условие equalToJson выполняется только в том случае если значение условия равно входящему JSON. Отмечу что сравнение происходит не на строковом уровне, а на объектном. Без дополнительных параметров условия игнорируется только порядок ключей в объектах. Также у данного условия есть два параметра ignoreArrayOrder и ignoreExtraElements. Первый указывает условию игнорировать порядок элементов в массивах, второй указывает условию игнорировать ключи объектов, которые не описаны в условии. Аналогичное условие есть и для xml, называется equalToXml, с функциональной точки зрения оно ничем не отличается от условия equalToJson.

Примеры тела запроса, которые будут сопоставлены с заглушкой выше:

[
    {
        "status": "PASSIVE",
        "results": 5,
        "id": 111
    },
    {
        "status": "ACTIVE",
        "results": 4,
        "id": 222
    }
]

[
    {
        "status": "PASSIVE",
        "results": 5
    },
    {
        "status": "ACTIVE",
        "results": 4
    }
]

Примеры тела запроса, которые не будут сопоставлены с заглушкой выше:

[
    {
        "status": "PASSIVE",
        "results": 4
    },
    {
        "status": "ACTIVE",
        "results": 5
    }
]

[
    {
        "status": "PASSIVE",
        "results": 5
    }
]

Пример сопоставления по телу запроса и условию matchesJsonPath:

{
    "request": {
        ...
        "bodyPatterns": [
            {
                "matchesJsonPath": "$.result"
            }
        ]
    },
    ...
}

Значением условия matchesJsonPath является путь JSONPath, это своего рода XPath только для JSON, подробнее о JSONPath можно ознакомиться в данном руководстве. Условие выполняется в том случае если путь JSONPath указанный в значении условия, во входящем JSON найдет значение, которое будет не равно null. Аналогичное условие есть и для xml, называется matchesXPath, с функциональной точки зрения оно ничем не отличается от условия matchesJsonPath.

Примеры тела запроса, которые будут сопоставлены с заглушкой выше:

{
    "result": [
        {
            "status": "PASSIVE",
            "results": 5,
            "id": 111
        },
        {
            "status": "ACTIVE",
            "results": 4,
            "id": 222
        }
    ]
}

{
    "result": "PASSIVE"
}

Примеры тела запроса, которые не будут сопоставлены с заглушкой выше:

{
    "result1": [
        {
            "status": "PASSIVE",
            "results": 5
        },
        {
            "status": "ACTIVE",
            "results": 4
        }
    ]
}

{
    "result": null
}

Пример сопоставления по телу запроса и условиям matchesJsonPath, equalToJson:

{
    "request": {
        ...
        "bodyPatterns": [
            {
                "matchesJsonPath": {
                    "expression": "$.result",
                    "equalToJson": [
                        {
                            "results": 4,
                            "status": "ACTIVE"
                        },
                        {
                            "results": 5,
                            "status": "PASSIVE"
                        }
                    ],
                    "ignoreArrayOrder": true,
                    "ignoreExtraElements": true
                }
            }
        ]
    },
    ...
}

В данном примере используются два условия matchesJsonPath и equalToJson, которые мы рассмотрели выше. В комбинации двух таких условий, условие matchesJsonPath на вход уже принимает не строку, а объект с дополнительным условием equalToJson. Также появился параметр expression, который принимает на вход JSONPath для условия matchesJsonPath. Смысл такой конструкции прост, сначала условие matchesJsonPath во входящем JSON ищет значение на основе пути переданном в параметре expression, далее найденное значение передается в условие equalToJson. Сопоставление произойдет в том случае если выполнятся оба условия.

Примеры тела запроса, которые будут сопоставлены с заглушкой выше:

{
    "result": [
        {
            "status": "PASSIVE",
            "results": 5,
            "id": 111
        },
        {
            "status": "ACTIVE",
            "results": 4,
            "id": 222
        }
    ]
}

{
    "result": [
        {
            "status": "PASSIVE",
            "results": 5
        },
        {
            "status": "ACTIVE",
            "results": 4
        }
    ]
}

Примеры тела запроса, которые не будут сопоставлены с заглушкой выше:

{
    "result1": [
        {
            "status": "PASSIVE",
            "results": 5
        },
        {
            "status": "ACTIVE",
            "results": 4
        }
    ]
}

{
    "result": [
        {
            "status": "PASSIVE",
            "results": 5
        }
    ]
}

Журналирование

Журналирование в WireMock устроено очень просто, доступно API которое предоставляет информацию о связках запрос-ответ. Отмечу что журналирование работает только в том случае если при запуске WireMock не указан параметр --no-request-journal. Объем журналирования зависит от параметра --max-request-journal-entries, он описан выше.

Для того чтобы получить весь журнал, нужно отправить запрос:

GET http://{{host}}:{{port}}/__admin/requests

Для того чтобы очистить весь журнал, нужно отправить запрос:

DELETE http://{{host}}:{{port}}/__admin/requests

Для того что бы получить количество определенных вызовов, нужно отправить запрос:

POST http://{{host}}:{{port}}/__admin/requests/count
{
  "method": "GET",
  "url": "/some/thing"
}

В теле запроса можно передавать любые сопоставления, по которым можно найти HTTP запрос, выше в разделе сопоставления мы рассмотрели все параметры.

Для того что бы получить журнал по определенным вызовам, нужно отправить запрос:

POST http://{{host}}:{{port}}/__admin/requests/find
{
  "method": "GET",
  "url": "/some/thing"
}

В теле запроса можно передавать любые сопоставления, по которым можно найти HTTP запрос, выше в разделе сопоставления мы рассмотрели все параметры.

Для того что бы получить все вызовы, к которым не было найдено сопоставление, нужно отправить запрос:

GET http://{{host}}:{{port}}/__admin/requests/unmatched

В следующей части я расскажу все что связано с HTTP ответом, который возвращает заглушка, а также затронем сценарии.