Self-hosted API mocking и тестирование на VPS
Узнайте, как настроить WireMock для стабов и Hurl для тестирования на собственном сервере. Разделяйте задачи mock-сервера и test runner для стабильной работы в CI.
Два сервиса в одном репозитории
Self-hosted mock-сервер и средство тестирования API решают разные задачи. Если объединить их, можно потерять неделю. Mock-сервер заменяет зависимость, к которой нельзя обратиться из CI: платёжного провайдера, API партнёра, upstream с ограничением частоты запросов или сервис, который другая команда ещё не выпустила. Средство запуска тестов API обращается к вашим endpoint в заданном порядке и проверяет ответы. Значения из одного ответа оно передаёт в следующий запрос.
Некоторые инструменты выполняют обе задачи. Основная задача mock-сервера — отвечать на запросы. Средство запуска тестов не определяет, какой ответ должен вернуть платёжный провайдер при отклонении карты. Большинство команд, у которых уже есть сервер, в итоге запускают по одному инструменту каждого типа. Оба сервиса запускаются одним файлом Docker Compose, а изменения в них проверяются в одном pull request.
Почему стоит самостоятельно размещать mock API и тестовую инфраструктуру?
Ваши fixtures содержат данные, похожие на production. Тело запроса в API-тесте может быть реальной записью клиента с изменённым именем или с исходным именем, если никто это не проверил. С записанными stubs ситуация ещё хуже: при записи через proxy сохраняется всё, что фактически вернул upstream. Поэтому в каталоге stubs, созданном таким способом, остаются действующие tokens и адреса электронной почты клиентов, пока кто-нибудь не проверит каждый файл. В hosted-сервисе эти данные становятся чужим инцидентом и вашим раскрытием информации.
Вторая причина — доступность по сети. Сервис, привязанный к private address, требует подключения к private network, прежде чем hosted runner сможет обратиться к нему. Каждый обходной путь имеет свою цену. Публикация API в Интернете для его тестирования устраняет причину, по которой он был private. Tunnel или публичная staging-копия — это ещё одна система, которую нужно сопровождать, а staging-копия расходится с production между релизами. GitHub-hosted runners также поддерживают private-доступ через WireGuard overlay или Azure Virtual Network. Runner в той же private network обращается к сервису напрямую и не требует ничего из этого. В этом состоит практическое обоснование использования self-hosted runner GitHub Actions.
Какие self-hosted mock server следует запускать?
Каждый из них работает как контейнер на принадлежащем вам сервере. Важно понять, что именно каждый из них считает источником истины. От этого зависит, обойдётся ли пересоздание контейнера бесплатно или потребует целого дня работы.
- WireMock хранит каждый stub в виде JSON-файла в каталоге
mappings/, а большие тела ответов — в__files/. Образ находится вwiremock/wiremock, его корневой каталог внутри контейнера —/home/wiremock. Кроме того, WireMock работает как proxy для записи трафика. Файлы на диске позволяют хранить mock в git, как любой другой код. - Mockoon CLI хранит весь mock API в одном JSON-файле данных. Установите его с помощью
npm install -g @mockoon/cliи запустите с помощьюmockoon-cli start --data ./data-file.jsonлибо запустите образmockoon/cli, подключив этот файл через bind mount. Desktop-приложение редактирует тот же файл, поэтому проектирование в UI и фиксация результата в git совместимы. - MockServer запускается из образа
mockserver/mockserverи принимает подключения на порту 1080. Expectations передаются через собственный REST API. Это удобно из тестового кода, но создаёт риск при развёртывании: по умолчанию expectation, созданный HTTP-запросом, исчезает после перезапуска контейнера. Для постоянных stub используйте JSON-файл инициализации. Чтобы сохранять изменения, внесённые во время работы, включитеpersistExpectations, сохраняйте выходной файл за пределами контейнера и загружайте его при запуске черезinitializationJsonPath. - Prism создаёт mock на основе документа OpenAPI, а не отдельных файлов stub. Установите его с помощью
npm install -g @stoplight/prism-cli, затем запустите черезprism mock openapi.yaml. В контейнере добавьте-h 0.0.0.0, поскольку по умолчанию Prism привязывается к localhost и иначе недоступен извне контейнера. - Microcks — наиболее крупный вариант: web UI импортирует документы OpenAPI и коллекции Postman, затем предоставляет их как mock и запускает контрактные тесты. Для полной установки нужны MongoDB и Keycloak, а для асинхронных функций — также Kafka. Универсальный образ
microcks-uberсодержит MongoDB в памяти. В документации проекта указано, что такой режим подходит для временного использования. Поэтому считайте всё созданное в этом UI временными данными и храните исходные артефакты в git.
Какой self-hosted runner для тестирования API следует использовать?
Здесь нужен последовательный сценарий: аутентифицироваться, создать заказ, получить его данные и проверить, что состояние изменилось. Для этого нужно извлечь значение из одного ответа и использовать его в следующем запросе. Инструмент, который не умеет передавать состояние между вызовами, выполняет health check, а не тестирование API.
- Hurl запускает из одного бинарного файла обычные текстовые файлы с HTTP-запросами. Секция
[Captures]извлекает значения из ответа, секция[Asserts]проверяет их, а--testпревращает сценарий в test runner со сводкой и exit code. По состоянию на August 2026 актуальна версия 8.0.1. - Bruno CLI запускает набор файлов
.bruиз каталога. Установите его с помощьюnpm install -g @usebruno/cli, затем выполнитеbru run folder --env Local --reporter-junit results.xml. Формат коллекции специально рассчитан на текстовые файлы в каталоге, поэтому изменения удобно просматривать при code review. - Newman запускает коллекции Postman за пределами Postman:
npm install -g newman, затемnewman run collection.json -r cli,junit --reporter-junit-export results.xml. Ограничение связано с форматом. Newman запускает экспортированные коллекции в формате JSON v2.1. Сейчас Postman также поддерживает формат коллекций v3 и Native Git workflows через Postman CLI. В документации Postman указано, что Newman больше не будет получать обновления и исправления. Также рекомендуется перенести скрипты и CI pipelines в Postman CLI. - Schemathesis выполняет проверку другого типа. Он читает схему OpenAPI и генерирует случаи, которые пытаются получить ответы, объявленные схемой невозможными:
uvx schemathesis run https://your.api/openapi.json. Он обнаруживает сбои и нарушения контракта, но ничего не знает о бизнес-правилах. Поэтому его следует использовать вместе со скриптовым набором, а не вместо него. - Self-hosted Hoppscotch — вариант с web UI, которому требуется экземпляр Postgres. Учтите это ограничение до установки: коллекции хранятся в базе данных, а не в репозитории.
Есть инструмент, которого следует избегать. Step CI по-прежнему встречается в обзорах инструментов, а его формат YAML workflows хорошо читается. Однако последний commit в репозитории был выполнен в August 2024. Программа, расположенная между CI и API, не должна содержать неподдерживаемый код.
Поместите mock-сервер за межсетевой экран
Приведённая ниже конфигурация запускает WireMock как замену платёжному провайдеру. Если формат файла Compose вам незнаком, в разделе Docker Compose на VPS описаны команды управления жизненным циклом, которые используются в этом разделе.
services:
mock-payments:
image: wiremock/wiremock:3.13.2
command: ["--verbose"]
volumes:
- ./mocks/payments:/home/wiremock
ports:
- "127.0.0.1:8080:8080"
restart: unless-stoppedПрефикс 127.0.0.1: в объявлении порта имеет решающее значение. Если указать только 8080:8080, mock-сервер будет доступен на всех интерфейсах, включая публичный IP-адрес. Он останется доступным даже при запрете этого порта в ufw, потому что Docker направляет опубликованный трафик через таблицу nat до того, как он доходит до правил INPUT в ufw. Привяжите порт к loopback-адресу, чтобы при стандартной bridge-сети Docker на Engine 28.0.0 или более поздней версии опубликованный порт был доступен только с самого хоста. В старых версиях хосты в той же сети уровня 2 могут обращаться к портам, опубликованным на localhost. Привязка к адресу приватного интерфейса по-прежнему позволяет подключаться из сетей, у которых есть маршрут к этому адресу.
После этого сервис, который вы тестируете, должен обращаться к mock-серверу. Если сервис работает в том же Compose-проекте, его базовый URL — http://mock-payments:8080, потому что Compose разрешает имена сервисов в собственной сети. Если сервис работает на хосте, используйте http://127.0.0.1:8080. Передайте это значение через переменную окружения, а не задавайте в коде. Иначе URL для тестирования попадёт в production.
Stubs размещаются в ./mocks/payments/mappings/, по одному JSON-файлу на каждый stub.
{
"request": {
"method": "POST",
"urlPath": "/v1/charges",
"bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
},
"response": {
"status": 201,
"headers": { "Content-Type": "application/json" },
"jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
}
}Запустите сервер и проверьте, какие данные были загружены.
docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappingsКоманда --wait ожидает, пока контейнер сообщит о готовности. Это работает, потому что в образ WireMock входит HEALTHCHECK для его endpoint /__admin/health. Вызов mappings выводит список всех stubs, прочитанных сервером. Если написанный вами stub отсутствует в этом списке, он не был загружен. Проверьте, что файл находится в mappings/, а не в корне подключённого тома, и что JSON корректно разбирается.
Если поступает запрос, которому не соответствует ни один stub, WireMock возвращает 404. Если найдено близкое соответствие, тело ответа начинается с Request was not matched, за которым следует diff с наиболее близким stub. Если mappings stubs отсутствуют, тело ответа равно No response could be served as there are no stub mappings in this WireMock instance.. Если diff присутствует, сначала изучите его, а уже потом что-либо изменяйте: в нём указано точное поле, которое отличается. Обычно это путь с /v1/charge, тогда как в stub указано /v1/charges.
Написание теста в виде последовательности с сохранением состояния между вызовами
Файлы Hurl представляют собой обычный текст. Установите deb-пакет из релизов проекта.
VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.debНабор тестов, проверяющий ваш API с использованием заглушки (mock), находится в tests/checkout.hurl.
POST {{base_url}}/orders
Content-Type: application/json
{
"sku": "ssd-1tb",
"amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"
GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"Блок [Captures] превращает это в полноценный API-тест, а не в два независимых запроса. Значение order_id считывается из первого ответа и подставляется в URL второго запроса. Проверка в charge_id — это ключевой момент всей процедуры: она подтверждает, что ваш сервис обратился к платёжному провайдеру и сохранил полученные данные, а сравниваемое значение совпадает с тем, которое вы указали в WireMock stub. Теперь один файл охватывает обе части процесса.
hurl --test --variable base_url=http://127.0.0.1:3000 \
--report-junit reports/junit.xml \
--report-json reports/json \
tests/При успешном выполнении выводится по одной строке на каждый файл и итоговая сводка.
tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files: 1
Executed requests: 2 (30.1/s)
Succeeded files: 1 (100.0%)
Failed files: 0 (0.0%)
Duration: 64 msВ случае ошибки выводится error: Assert failure с указанием файла и номера строки, затем полученное значение в сравнении с ожидаемым, после чего hurl завершается с ненулевым кодом, чтобы остановить CI. Если status считывает pending там, где вы ожидали paid, значит, ваш сервис не обработал ответ от заглушки. Следующим шагом следует изучить журнал запросов WireMock по адресу /__admin/requests, который покажет, дошёл ли вызов до заглушки в принципе.
Запускайте набор тестов из собственного CI runner
Если runner зарегистрирован на том же сервере, workflow будет коротким. Runner — это обычный процесс на host, поэтому docker и hurl должны быть установлены на этом host. Hosted image не используется и ничего из него не наследуется.
name: api-tests
on: [push]
jobs:
hurl:
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
- name: Start the mock
run: docker compose up -d --wait mock-payments
- name: Run the suite
run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
- name: Archive the reports
if: always()
run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
- name: Stop the mock
if: always()
run: docker compose downПараметр if: always() на шаге архивации имеет значение. Без него при сбое тестов копирование пропускается, и вы теряете именно тот отчёт, который хотели прочитать. Копия также должна сохраняться за пределами workspace, потому что actions/checkout@v4 по умолчанию выполняет git clean -ffdx перед получением файлов. При следующем checkout это удаляет неотслеживаемые отчёты из каталога репозитория.
Сохраняйте результаты, а не только данные последнего запуска
Один JUnit XML-файл на каждый коммит отвечает только на один вопрос: пройден ли тест. Он не показывает, когда endpoint начал работать медленнее, поскольку после прекращения просмотра эти файлы никто не обрабатывает. Для построения динамики добавляйте после каждого запуска одну строку в небольшую базу данных на том же сервере. Достаточно одной таблицы с SHA коммита, именем файла, числом успешных и неуспешных проверок, а также длительностью. SQLite в production на VPS — подходящее место для хранения: один файл, отдельный серверный процесс не требуется, а вся история попадёт в резервную копию, которую вы уже создаёте. Для получения подробных данных о запуске разбирайте вывод Hurl в формате --report-json; и JSON, и JUnit XML пригодны для автоматической обработки.
Что должно сохраняться после пересборки контейнера
Определения mock-объектов и наборы тестов являются исходным кодом. Они должны храниться в репозитории рядом с сервисом, который они описывают, и изменяться в том же pull request, что и соответствующий endpoint. Если stub отредактирован в web UI или expectation передан в MockServer через REST API во время работы, для сохранения после пересборки потребуется настроить экспорт или persistence. Запуск docker compose down удаляет память контейнера и доступные для записи слои; данные в bind mount или именованных томах сохраняются. Если ваши репозитории также работают на собственном оборудовании, self-hosted git-сервер хранит fixtures и сервис в одной доверенной зоне.
Далее приведены практические правила. Фиксируйте теги образов, потому что latest может изменить способ сопоставления запросов вашим mock-объектом без изменений в репозитории, а такую ошибку очень сложно связать с причиной. Подключайте каталоги со stub только для чтения, если инструменту не требуется в них записывать. Никогда не храните stub mock-объекта в именованном Docker volume: в этом случае volume становится источником истины, а копия в git незаметно устаревает.
Есть ещё одно правило, о котором часто забывают. Если вы создаёте stub, записывая реальный трафик через proxy, прочитайте каждый сгенерированный файл перед коммитом. Запись содержит ровно то, что вернул upstream, включая bearer-токены и адреса электронной почты клиентов. После коммита эти данные навсегда попадут в репозиторий, поскольку git сохраняет удалённое содержимое в истории.
FAQ
В чём разница между API mock server и API test runner?
Mock server отвечает на запросы. Он заменяет зависимость, к которой нельзя обратиться из CI. Некоторые инструменты также выполняют contract tests и сообщают об их результатах. API test runner отправляет запросы в собственный сервис, проверяет ответы, передаёт значения из одного вызова в следующий и завершает работу с ненулевым кодом, если проверка завершается ошибкой. Эти инструменты решают разные задачи. Обычно их запускают одновременно: runner обращается к вашему сервису, а сервис — к mock.
Можно ли тестировать внутренний API из hosted CI runner?
Да, с помощью private networking. Hosted runner от GitHub поддерживает overlay на WireGuard или Azure Virtual Network для доступа к private resources без публикации API. Другие варианты — опубликовать API, запустить tunnel или поддерживать общедоступную staging-копию. Каждый из них добавляет систему, которая может отказать или раскрыть данные. Runner в той же private network обращается к сервису напрямую. Именно поэтому команды часто размещают такую инфраструктуру самостоятельно.
Где должны храниться mock stubs и API test suites?
В git рядом с сервисом, который они описывают. Инструменты, хранящие определения в виде файлов, например каталог mappings/ в WireMock, data file в Mockoon, файлы Hurl и каталог .bru в Bruno, обеспечивают code review и позволяют бесплатно пересобрать контейнер. Инструментам, которые хранят определения в database или web UI, нужны план резервного копирования и шаг экспорта. Именно об экспорте часто забывают, пока контейнер уже не удалён.
Почему мой mock возвращает 404, хотя stub выглядит правильно?
WireMock обслуживает stub только тогда, когда запрос соответствует настроенным matchers. Для запроса без совпадения возвращается 404. Если найдено близкое совпадение, body начинается с Request was not matched, затем приводится diff с ближайшим stub. В этом diff указано поле, которое отличается. Если mappings для stub отсутствуют, body сообщает, что в экземпляре нет mappings. Частые причины — завершающий слеш в path, заголовок Content-Type, который требуется stub, но не отправляет client, использование urlPath там, где stub ожидает urlPathPattern для variable segment, а также body matcher, не соответствующий payload. Сначала проверьте /__admin/requests, чтобы убедиться, что запрос вообще достиг mock.
Нужны ли мне mocks, если у меня есть staging environment?
Да, по двум причинам. Staging-копия upstream-сервиса, которым вы не управляете, всё равно может стать недоступной или начать ограничивать частоту запросов. В результате suite завершается ошибкой по причинам, не связанным с вашим кодом. Кроме того, такая копия не может возвращать ответы, которые особенно важно тестировать, например отказ по карте или gateway timeout. Mock возвращает эти ответы по требованию со скоростью локальной сети. Поэтому suite, которая занимает несколько минут при обращении к sandbox, выполняется за несколько секунд. Используйте staging для финальной проверки перед release, а mocks — в CI.