Self-hosted mock API і тестування на VPS
Розгорніть WireMock і Hurl на власному VPS: stubs зберігайте в git, тести запускайте в CI, а звіти не втрачайте після перебудови сервера.
Два завдання, які використовують один репозиторій
Self-hosted mocking і тестування API — це два різні завдання, і спроба об’єднати їх призводить до втрати тижня. Mock server замінює залежність, до якої не можна звернутися з CI: платіжного провайдера, партнерського API, upstream із rate limiting або сервісу, який інша команда ще не випустила. API test runner викликає власні endpoints у фіксованому порядку та перевіряє відповіді, передаючи значення з однієї відповіді в наступний запит.
Деякі інструменти виконують обидва завдання. Основне завдання mock server — відповідати на запити. Test runner не визначає, що має повертати платіжний провайдер, якщо картку відхилено. Більшість команд, які вже орендують сервер, зрештою запускають по одному інструменту кожного типу з одного Docker Compose file і перевіряють зміни в тому самому pull request.
Чому варто самостійно розгортати mock API та тестування?
Ваші fixtures містять дані, структуровані як production-дані. Тіло запиту в API-тесті може бути реальним записом клієнта зі зміненим ім’ям або навіть із незміненим ім’ям, якщо ніхто цього не перевірив. Записані stubs ще небезпечніші: proxy recording зберігає фактичну відповідь upstream, тому каталог stubs, створений під час запису, містить діючі токени й адреси електронної пошти клієнтів, доки хтось не перегляне кожен файл. У hosted service такі дані стають чужим інцидентом і вашим розкриттям інформації.
Друга причина — доступність. Сервіс, прив’язаний до приватної адреси, потребує підключення до приватної мережі, перш ніж hosted runner зможе до нього звернутися. Кожен обхідний шлях має свою ціну. Публікація API в інтернеті для його тестування усуває причину, через яку він був приватним. Tunnel або публічна staging-копія — це ще одна система, яку потрібно обслуговувати, а staging-копія розходиться з production між релізами. GitHub-hosted runners також підтримують приватний доступ через WireGuard overlay або Azure Virtual Network. Runner у тій самій приватній мережі звертається до сервісу безпосередньо й не потребує нічого з цього. У цьому полягає практична перевага власного GitHub Actions runner.
Який 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 та commit результату залишаються сумісними. - 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 і запускає contract tests. Для повного встановлення потрібні MongoDB і Keycloak, а для асинхронних функцій — також Kafka. Образ «усе в одному»
microcks-uberмістить MongoDB у пам’яті. У документації проєкту зазначено, що такий варіант призначений для ephemeral use, тому вважайте все створене в цьому UI тимчасовим і зберігайте вихідні артефакти в git.
Який self-hosted runner для тестування API варто використовувати?
Тут потрібна послідовність дій: автентифікуватися, створити замовлення, прочитати його та перевірити, що стан змінився. Для цього потрібно отримати значення з однієї відповіді та використати його в наступному запиті. Інструмент, який не може передавати стан між викликами, є health check, а не засобом тестування API.
- Hurl запускає plain text-файли з HTTP-запитами з одного бінарного файла. Секція
[Captures]отримує значення з відповіді, секція[Asserts]перевіряє їх, а--testперетворює цей процес на test runner зі зведенням і exit code. Станом на August 2026 актуальною є Version 8.0.1. - Bruno CLI запускає каталог файлів
.bru. Встановіть його за допомогоюnpm install -g @usebruno/cli, потім виконайтеbru run folder --env Local --reporter-junit results.xml. Формат колекції за задумом складається з текстових файлів у каталозі, тому зміни зручно переглядати під час code review. - Newman запускає Postman collections поза Postman:
npm install -g newman, потімnewman run collection.json -r cli,junit --reporter-junit-export results.xml. Проблема — у форматі. Newman запускає експортовані collections у форматі v2.1 JSON. Postman тепер також підтримує формат v3 collection і Native Git workflows через Postman CLI. У документації Postman зазначено, що Newman більше не отримуватиме оновлень або виправлень, і рекомендовано перенести scripts та CI pipelines до Postman CLI. - Schemathesis призначений для іншого типу перевірок. Він читає OpenAPI schema та генерує випадки, які намагаються отримати відповіді, неможливі згідно зі schema:
uvx schemathesis run https://your.api/openapi.json. Він знаходить збої та порушення контракту, але не знає нічого про бізнес-правила, тому використовується разом зі scripted suite, а не замінює її. - Self-hosted Hoppscotch — це варіант із web UI, для якого потрібен екземпляр Postgres. Усвідомте цей компроміс до встановлення: collections зберігаються в базі даних, а не у вашому репозиторії.
Є інструмент, якого варто уникати. Step CI досі з’являється в оглядах інструментів, а його формат YAML workflow зручно читати, але останній commit до repository було зроблено в August 2024. Програма, яка працює між вашим CI та API, — невдале місце для коду без супроводу.
Розмістіть mock server за firewall
Наведена нижче конфігурація запускає 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 network Docker у Engine 28.0.0 або новішій версії опублікований порт був доступний лише з хоста. Старіші релізи дають змогу хостам у тій самій мережі layer 2 звертатися до портів, опублікованих на localhost. Прив’язка до адреси приватного інтерфейсу все одно дає доступ із мереж, які можуть маршрутизувати трафік до цієї адреси.
Після цього ваш сервіс має звертатися до mock. Якщо сервіс працює в тому самому compose-проєкті, базовий URL mock — http://mock-payments:8080, оскільки compose розпізнає імена сервісів у власній мережі. Якщо сервіс працює на хості, використовуйте http://127.0.0.1:8080. Передайте це значення через змінну середовища, а не задавайте в коді, інакше тестовий URL потрапить у production.
Stub-файли зберігайте в ./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 очікує, доки контейнер не повідомить про готовність. Це працює, оскільки image WireMock містить HEALTHCHECK для його endpoint /__admin/health. Виклик mappings виводить усі stub-файли, які прочитав сервер. Якщо створений вами stub відсутній у цьому списку, його не було завантажено. Перевірте, що файл розташований у mappings/, а не в корені змонтованого каталогу, і що JSON має коректний синтаксис.
Коли надходить запит, для якого немає відповідного stub, WireMock повертає 404. Якщо він знаходить близький збіг, тіло відповіді починається з Request was not matched, після чого містить diff із найближчим stub. Якщо stub mappings відсутні, тіло відповіді — No response could be served as there are no stub mappings in this WireMock instance.. Якщо diff наявний, прочитайте його перед внесенням змін: у ньому вказано точне поле, яке відрізняється. Зазвичай це шлях із /v1/charge, тоді як у stub зазначено /v1/charges.
Напишіть тест як послідовність викликів зі збереженням стану між ними
Файли Hurl — це звичайний текст. Встановіть deb-пакет із releases проєкту.
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, ваш сервіс не обробив відповідь mock. Далі перевірте журнал запитів WireMock у /__admin/requests. Він показує, чи досяг виклик mock взагалі.
Запуск набору тестів із власного CI runner
Якщо runner зареєстрований на тому самому сервері, workflow залишається коротким. Runner — це звичайний процес на хості, тому на цьому хості мають бути встановлені docker і hurl. Нічого не успадковується від 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 на кожен commit відповідає лише на одне запитання: чи пройшов запуск. Він не показує, коли endpoint почав працювати повільніше, оскільки після припинення ручного відкривання цих файлів їх ніхто не читає. Для відстеження тенденції додавайте після кожного запуску один рядок до невеликої бази даних на тому самому сервері. Достатньо однієї таблиці з SHA commit, іменем файлу, кількістю успішних і невдалих перевірок та тривалістю. SQLite у production на VPS — доцільне місце для зберігання цих даних: один файл, окремий серверний процес не потрібен, а вся історія потрапляє до резервної копії, яку ви вже створюєте. Для отримання детальних даних про запуск розбирайте вивід Hurl --report-json; і JSON, і JUnit XML придатні для машинного читання.
Що має зберегтися після перебудови контейнера
Mock definitions і test suites — це source code. Вони мають зберігатися в repository поруч із сервісом, який вони описують, і змінюватися в тому самому pull request, що й endpoint. Stub, відредагований у web UI, або expectation, переданий до MockServer через його REST API під час роботи, потребує налаштування export або persistence, щоб пережити перебудову. Після запуску docker compose down пам’ять контейнера та writable layers втрачаються; дані в bind mounts або named volumes зберігаються. Якщо ваші repositories також працюють на власному обладнанні, self-hosted git server дає змогу зберігати fixtures і сервіс в межах однієї trust boundary.
Далі — практичні правила. Фіксуйте image tags, оскільки latest може змінити спосіб, у який ваш mock зіставляє запити, без будь-яких змін у repository, а таку помилку дуже важко пов’язати з її причиною. Монтуйте каталоги зі stubs у режимі read-only, якщо інструменту не потрібно вносити до них зміни. Ніколи не зберігайте stubs mock у named Docker volume, оскільки тоді volume стає джерелом істини, а копія в git непомітно застаріває.
І ще одне правило, про яке часто забувають. Якщо ви створюєте stubs, записуючи реальний traffic через proxy, перевірте кожен згенерований файл перед commit. Запис містить саме те, що повернув upstream, зокрема bearer tokens і customer email addresses. Commit такого файла назавжди додає ці дані до repository, оскільки git зберігає видалений вміст в history.
FAQ
У чому різниця між mock-сервером API та засобом запуску API-тестів?
Mock-сервер відповідає на запити. Він замінює залежність, до якої ви не можете звернутися з CI; деякі інструменти також запускають контрактні тести й повідомляють про їхні результати. Засіб запуску API-тестів надсилає запити до вашого сервісу, перевіряє відповіді за допомогою assertions, передає значення з одного виклику до наступного та завершує роботу з ненульовим кодом, якщо assertion не пройшов. Вони вирішують різні завдання, тому типове налаштування запускає обидва компоненти одночасно: засіб запуску тестів викликає ваш сервіс, а ваш сервіс викликає mock.
Чи можна тестувати внутрішній API з hosted CI runner?
Так, за допомогою приватної мережі. GitHub-hosted runners підтримують overlay на основі WireGuard або Azure Virtual Network для доступу до приватних ресурсів без публікації API. Публікація API, запуск тунелю або підтримка публічної staging-копії — інші варіанти, і кожен із них додає систему, яка може відмовити або спричинити витік даних. Runner у тій самій приватній мережі звертається до сервісу безпосередньо. Це основна практична причина, чому команди розміщують такі ресурси у власній інфраструктурі.
Де мають зберігатися mock stubs і набори API-тестів?
У git, поруч із сервісом, який вони описують. Інструменти, що зберігають визначення у файлах, як-от каталог WireMock mappings/, файл даних Mockoon, файли Hurl і каталог Bruno .bru, забезпечують code review, а перебудова контейнера не потребує додаткових витрат. Інструменти, що зберігають визначення в базі даних або web UI, потребують плану резервного копіювання та кроку експорту, а саме крок експорту часто забувають, доки контейнер уже не буде видалено.
Чому мій mock повертає 404, коли stub виглядає правильно?
WireMock обслуговує stub лише тоді, коли запит відповідає налаштованим matchers. Для запиту без відповідного збігу повертається 404; якщо існує близький збіг, тіло відповіді починається з Request was not matched, після чого містить diff із найближчим stub, а цей diff називає поле, що відрізняється. Якщо stub mappings відсутні, тіло відповіді натомість пояснює, що в інстансі їх немає. Поширені причини: кінцевий slash у path; заголовок Content-Type, якого вимагає stub, але клієнт його не надіслав; використання urlPath там, де stub потребує urlPathPattern для змінного сегмента; а також matcher тіла, який не відповідає payload. Спочатку перевірте /__admin/requests, щоб підтвердити, що запит узагалі досяг mock.
Чи потрібні мені mocks, якщо я маю staging-середовище?
Так, з двох причин. Staging-копія upstream, яким ви не керуєте, також може стати недоступною або застосувати rate limit, через що ваш набір тестів завершиться помилкою з причин, не пов’язаних із вашим кодом. Крім того, вона не може повертати відповіді, які вам найпотрібніше тестувати, наприклад відхилену оплату карткою або gateway timeout. Mock повертає такі відповіді на вимогу зі швидкістю локальної мережі. Завдяки цьому набір тестів, який у sandbox виконується кілька хвилин, виконується кілька секунд. Залиште staging для фінальної перевірки перед релізом, а в CI використовуйте mocks.