Документация

Всё о создании и управлении интеграционными заглушками в Badgermock.

Быстрый старт

1. Разверните Badgermock — через Helm-чарт в Kubernetes, Docker-образ или JAR на сервере (детали — в инструкции по развёртыванию от вашей команды)
2. Откройте http://<APP_HOST>:8080/ui/stubs (учётные данные — уточните у администратора вашей инсталляции)
3. Нажмите + Новый стаб, выберите протокол HTTP
4. Заполните: имя, метод GET, путь /api/hello, тело ответа {"message": "Hello!"}
5. Проверьте: curl http://<WIREMOCK_HOST>:18080/api/hello

HTTP-заглушки

HTTP-заглушки работают на базе WireMock. При создании заглушки приложение регистрирует маппинг в встроенном WireMock-сервере, который слушает на отдельном порту (по умолчанию 18080).

Request Matching

Запрос сопоставляется с заглушкой по нескольким критериям. Все заданные критерии должны совпасть одновременно (логическое AND).

HTTP-метод

Обязательное поле. Поддерживаются: GET, POST, PUT, DELETE, PATCH.

Точный путь (path)

Запрос должен совпасть с путём полностью. Лидирующий / добавляется автоматически.

Паттерн пути (pathPattern) — регулярные выражения

Если заполнено поле pathPattern, оно имеет приоритет над path. Используется Java-regex для гибкого матчинга.

Query-параметры

JSON-объект с параметрами запроса. Каждый параметр проверяется на точное совпадение.

{
  "status": "active",
  "page": "1"
}

Запрос GET /api/users?status=active&page=1 — совпадение. Запрос GET /api/users?status=inactive&page=1 — нет.

Заголовки запроса (Header Matchers)

JSON-объект с заголовками. Каждый заголовок проверяется на точное совпадение значения.

{
  "X-Api-Key": "my-secret-key",
  "X-Tenant": "acme"
}

Тело запроса (Body Contains)

Строка, которая должна содержаться в теле запроса. Это поиск подстроки, не регулярное выражение.

Как матчить конкретное значение поля в JSON

Body Contains — это поиск подстроки по всему телу запроса. Чтобы сматчить конкретное значение поля, укажите фрагмент JSON как он выглядит в теле:

Пример: комбинация всех критериев

Заглушка сработает только если все заданные критерии совпали:

Метод:          POST
Path Pattern:   /api/orders/[^/]+/pay
Query Params:   {"currency": "RUB"}
Header Matchers: {"X-Api-Key": "secret"}
Body Contains:  "amount"

Запрос, который сматчится:

curl -X POST "http://<WIREMOCK_HOST>:18080/api/orders/ord-42/pay?currency=RUB" \
  -H "X-Api-Key: secret" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500}'

Настройка ответа

Статус-код

HTTP-статус ответа. По умолчанию: 200. Примеры: 201 (Created), 404 (Not Found), 500 (Server Error).

Тело ответа

Текст, который WireMock вернёт в теле ответа. Может быть JSON, XML, HTML или обычный текст.

Заголовки ответа

JSON-объект с заголовками, которые добавятся к ответу:

{
  "Content-Type": "application/json",
  "X-Request-Id": "abc-123"
}

Задержка ответа (Response Delay)

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

CORS

Если включено, к ответу автоматически добавляются CORS-заголовки и регистрируется OPTIONS preflight-маппинг:

• Access-Control-Allow-Origin: *
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
• Access-Control-Allow-Headers: *
• Access-Control-Max-Age: 86400

Response Templating

При включённом шаблонизировании тело ответа обрабатывается движком Handlebars. Это позволяет создавать динамические ответы, которые зависят от данных запроса.

Доступные переменные

Встроенные хелперы

Пример: эхо-сервер с метаданными

{
  "id": "{{randomValue type='UUID'}}",
  "received_at": "{{now format='yyyy-MM-dd\'T\'HH:mm:ss\'Z\''}}",
  "your_name": "{{jsonPath request.body '$.name'}}",
  "request_id": "{{request.headers.X-Request-Id}}",
  "method": "{{request.method}}"
}

Fault Injection

Симулирование сетевых ошибок для тестирования устойчивости вашего приложения. При включённом fault injection обычный ответ не отправляется — вместо него генерируется ошибка.

SOAP-заглушки

SOAP-заглушки позволяют мокировать веб-сервисы, работающие по SOAP 1.1 и 1.2. Они также работают через WireMock, но с дополнительными возможностями для XML и XPath.

Основные поля

XPath Body Matchers

Мощный способ фильтрации SOAP-запросов по содержимому XML-тела. Задаётся как JSON-массив:

[
  {
    "xpath": "//*[local-name()='SendRequestRequest']",
    "equals": ""
  },
  {
    "xpath": "//*[local-name()='MessageType']",
    "equals": "CREATE"
  }
]

Два режима матчинга

• Проверка наличия — только xpath, без equals: элемент должен существовать
• Проверка значения — xpath + equals: элемент должен существовать и иметь указанное значение

Если несколько матчеров

Все матчеры в массиве должны совпасть (логика AND). Это позволяет точно выбрать нужный SOAP-метод.

Response Templating в SOAP

Работает так же, как для HTTP. Дополнительно доступен хелпер soapXPath:

<Response>
  <MessageId>{{soapXPath request.body '//MessageId/text()'}}</MessageId>
  <Timestamp>{{now format='yyyy-MM-dd HH:mm:ss'}}</Timestamp>
  <Status>SUCCESS</Status>
</Response>

Kafka-заглушки

Kafka-заглушки реализуют паттерн Request / Reply: приложение слушает входящий топик и автоматически отправляет ответ в указанный выходной топик.

Конфигурация

Как работает

1. При создании заглушки поднимается отдельный Kafka consumer с уникальным group ID
2. Consumer слушает указанный Request Topic
3. При получении сообщения — отправляет тело ответа заглушки в Reply Topic
4. Заголовки из поля Response Headers добавляются к ответному сообщению

Artemis-заглушки (JMS)

Заглушки для ActiveMQ Artemis. Слушают JMS-очередь и отправляют ответ в указанную очередь.

Конфигурация

JMS Selector

Позволяет фильтровать входящие сообщения по свойствам JMS. Синтаксис аналогичен SQL WHERE:

JMSType = 'PaymentRequest'
priority > 5
country = 'RU' AND amount > 1000

RabbitMQ-заглушки

Заглушки для RabbitMQ. Слушают AMQP-очередь и отправляют ответ в указанную очередь.

Конфигурация

Очереди создаются автоматически (durable) при регистрации заглушки.

HTTP Schedule

Отложенные исходящие HTTP-вызовы. Заглушка отправляет HTTP-запрос по расписанию — в указанное время или по cron-выражению. Это не мок, а генератор исходящих запросов.

Типы расписания

Cron — повторяющееся

5-полевой cron: минута час день_месяца месяц день_недели

*/5 * * * *     — каждые 5 минут
0 9 * * 1-5     — в 09:00 по будням
0 0 1 * *       — первого числа каждого месяца в полночь
30 14 * * *     — каждый день в 14:30

Once — однократно

Выполняется один раз в указанное время. Формат: 2026-04-16T14:30:00 или ISO-8601 с timezone.

Delay — с задержкой

Выполняется один раз через указанное количество минут от момента создания.

Конфигурация запроса

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

Через UI

1. Перейдите в /ui/stubs и нажмите Создать
2. Выберите протокол — форма автоматически покажет нужные поля
3. Заполните обязательные поля (отмечены *)
4. Заполните тело ответа — редактор автоматически определит формат (JSON/XML/Text)
5. Нажмите Сохранить

Валидация

• Имя — обязательно, до 255 символов
• Тело ответа — обязательно для HTTP, SOAP, Kafka, Artemis, RabbitMQ; необязательно для HTTP Schedule GET
• JSON — если выбран формат JSON, тело проверяется на валидность синтаксиса
• XML — если выбран формат XML, тело проверяется на валидность
• Cron — проверяется формат: 5 полей, допустимые символы 0-9 a-z A-Z * , - /

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

Kafka

SOAP

Клонирование

Кнопка Клонировать в деталях заглушки создаёт копию с префиксом «Copy of». Копия создаётся выключенной. Удобно для создания вариаций одного сценария.

Включение / Выключение

Переключатель Enabled позволяет временно отключить заглушку, не удаляя её. Выключенная заглушка снимается с регистрации в WireMock / Kafka / Artemis и перестаёт отвечать на запросы.

Проекты и папки

Проекты

Заглушки можно объединять в проекты. Проект имеет код (уникальный) и имя. Фильтрация по проекту доступна в sidebar списка заглушек.

Папки

Иерархическая организация заглушек через путь-папку. Поддерживается вложенность через /:

payments
payments/auth
payments/auth/login
payments/refunds
orders
orders/v2

В sidebar отображается дерево папок с количеством заглушек в каждой. При клике на папку отображаются все заглушки в ней и её подпапках.

Импорт и экспорт

Экспорт

• Один стаб: в деталях заглушки — кнопка «Экспорт». Скачивает JSON-файл
• Все стабы: GET /api/stubs/export — скачивает stubs-export.json
• По протоколу: GET /api/stubs/export?protocol=http — только HTTP-заглушки

Импорт

Отправьте массив заглушек через POST /api/stubs/import:

curl -X POST http://<APP_HOST>:8080/api/stubs/import \
  -u <USER>:<PASSWORD> \
  -H "Content-Type: application/json" \
  -d @stubs-export.json

Формат файла

[
  {
    "name": "Get User",
    "integrationType": "sync",
    "protocol": "http",
    "config": {
      "method": "GET",
      "path": "/api/users/1",
      "status_code": 200
    },
    "responseBody": "{\"id\": 1, \"name\": \"John\"}",
    "responseHeaders": "{\"Content-Type\": \"application/json\"}",
    "enabled": true,
    "folder": "users"
  }
]

Сценарий: перенос между окружениями

1. Экспортируйте заглушки из dev: GET /api/stubs/export
2. Импортируйте в staging: POST /api/stubs/import
3. Включите нужные заглушки

OpenAPI импорт

Автоматическое создание HTTP-заглушек из OpenAPI 3.x / Swagger 2.0 спецификации.

Как это работает

1. Перейдите в /ui/stubs/import-openapi
2. Вставьте OpenAPI-спецификацию (JSON или YAML)
3. Система распарсит все эндпоинты и покажет превью
4. Выберите нужные эндпоинты и нажмите «Создать»

Что извлекается автоматически

• Путь — параметры пути конвертируются в regex [^/]+
• Метод — GET, POST, PUT, DELETE, PATCH
• Query-параметры — из блока parameters с in: query
• Заголовки — из parameters с in: header (кроме Accept, Content-Type)
• Тело ответа — из example, examples или генерация из схемы
• Статус-код — выбирается лучший (200 > 201 > первый 2xx)
• Имя заглушки — из summary операции

Метрики и журнал вызовов

Каждая заглушка отслеживает вызовы и показывает метрики в разделе деталей.

Hit Counter

Счётчик количества срабатываний заглушки. Отображается в списке и в деталях. Сбрасывается при перезапуске приложения.

Журнал вызовов (Call Journal)

Детальный лог каждого обращения к заглушке:

• Timestamp — время вызова
• URL / Destination — путь запроса (HTTP/SOAP) или топик/очередь (Kafka/Artemis/Rabbit)
• Заголовки — заголовки входящего запроса
• Тело — тело входящего запроса/сообщения
• HTTP-статус — код ответа (только для HTTP и SOAP)
• Время ответа — задержка в миллисекундах

Графики

В деталях заглушки доступны:

• Traffic Chart — гистограмма запросов за период с наложением средней задержки
• Status Distribution — распределение HTTP-статусов (для HTTP/SOAP)
• Average Response Time — средняя задержка за период

Периоды: 5 мин, 15 мин, 30 мин, 1 час, 6 часов, 24 часа, 7 дней.

Поддержка по протоколам

REST API

Все операции доступны через REST API на порту :8080. Авторизация: HTTP Basic Auth.

Endpoints

Пагинация и фильтрация

GET /api/stubs?page=0&size=20&protocol=http

Параметры: page (с 0), size (по умолчанию 20), protocol (опционально).

Примеры curl

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

curl -X POST http://<APP_HOST>:8080/api/stubs \
  -u <USER>:<PASSWORD> \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Get Users",
    "integrationType": "sync",
    "protocol": "http",
    "config": {
      "method": "GET",
      "path": "/api/users",
      "status_code": 200,
      "response_templating": false
    },
    "responseBody": "[{\"id\": 1, \"name\": \"John\"}]",
    "responseHeaders": "{\"Content-Type\": \"application/json\"}",
    "enabled": true
  }'

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

curl -X POST http://<APP_HOST>:8080/api/stubs \
  -u <USER>:<PASSWORD> \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Reply",
    "integrationType": "sync",
    "protocol": "kafka",
    "config": {
      "request_topic": "payment.requests",
      "reply_topic": "payment.replies"
    },
    "responseBody": "{\"status\": \"SUCCESS\", \"txId\": \"TX-001\"}",
    "enabled": true
  }'

Список с фильтром

curl http://<APP_HOST>:8080/api/stubs?protocol=kafka&page=0&size=10 \
  -u <USER>:<PASSWORD>

Конфигуратор развёртывания

Конфигуратор генерирует готовый набор файлов для развёртывания Badgermock под ваш проект. Вы выбираете нужные протоколы и параметры — получаете ZIP-архив со всем необходимым.

Что входит в архив

Состав архива зависит от выбранной среды развёртывания:

Как пользоваться

1. Выберите протоколы — отметьте только те, которые реально используются на проекте. HTTP включён всегда. Отключённые протоколы не будут приниматься приложением, а в Docker Compose не будут подниматься лишние брокеры.
2. Настройте параметры — порт приложения (8080) и порт WireMock (18080). Эти порты влияют на Dockerfile, docker-compose.yml, Ingress и переменную APPLICATION_STUBS_BASE_URL (от неё зависят curl-примеры в UI).
3. Заполните настройки протоколов — при включении Kafka, Artemis или RabbitMQ появятся дополнительные поля: bootstrap servers, broker URL, security protocol и т.д.
4. Выберите среду — Docker Compose, Kubernetes или Standalone (VM).
5. Скачайте архив — опционально можно включить badgermock.jar (~106 MB).

Docker Compose

Генерируется docker-compose.yml с сервисами:

• badgermock — контейнер приложения с env_file: .env
• postgres — PostgreSQL 16 с healthcheck
• kafka + zookeeper — только если выбран Kafka
• artemis — только если выбран Artemis
• rabbitmq — только если выбран RabbitMQ

Запуск: положите badgermock.jar рядом с Dockerfile, соберите образ и запустите:

docker build -t badgermock .
BADGERMOCK_IMAGE=badgermock docker compose up -d

Kubernetes (Helm)

Генерируется полноценный Helm-чарт:

• Chart.yaml — метаданные
• values.yaml — все env-переменные, ресурсы (CPU/RAM), probes, ingress
• templates/deployment.yaml — Deployment с env из values и secrets
• templates/service.yaml — Service с двумя портами (приложение + WireMock)
• templates/ingress.yaml — Ingress с двумя хостами

Ingress: два хоста

Ingress настраивается на два домена:

APPLICATION_STUBS_BASE_URL автоматически формируется из ingress.wiremock.host — curl-примеры в UI будут корректными.

Деплой:

# Сборка образа
docker build -t registry.example.com/badgermock:latest .
docker push registry.example.com/badgermock:latest

# Секрет для БД
kubectl create secret generic badgermock-db-secret \
  --from-literal=SPRING_DATASOURCE_PASSWORD=<PASSWORD>

# Установка
helm upgrade --install badgermock ./helm/ -f helm/values.yaml

Standalone (VM)

Генерируется пара файлов для запуска через systemd:

• badgermock.env — переменные окружения (JDBC URL с localhost)
• badgermock.service — systemd unit с EnvironmentFile

Установка:

cp badgermock.jar /opt/badgermock/
cp badgermock.env /etc/badgermock/
cp badgermock.service /etc/systemd/system/
systemctl daemon-reload
systemctl start badgermock

Переопределение конфигурации

JAR всегда один и тот же — все протоколы включены внутри. Конфигуратор генерирует только внешнюю обвязку (env-файлы, docker-compose, Helm values). Spring Boot применяет приоритеты:

1. Переменные окружения — наивысший приоритет (перекрывают всё)
2. application.yml рядом с JAR — средний приоритет
3. application.yml внутри JAR — дефолты

Это значит: вы можете изменить любой параметр после генерации, просто отредактировав .env / values.yaml — без пересборки JAR.

Конфигурация

Feature Flags

Каждый протокол можно включить или выключить. Выключенный протокол не отображается в UI и не принимает запросы на создание заглушек.

Таймауты

Брендинг

Кастомизация внешнего вида UI:

Подключения

Безопасность

Аутентификация

• API (/api/**) — HTTP Basic Auth
• UI (/ui/**) — форма логина с сессией
• Actuator (/actuator/**) — доступен без авторизации

Пользователи

Учётные данные задаются при развёртывании. Для настройки через переменные окружения:

APPLICATION_SECURITY_USER=myuser
APPLICATION_SECURITY_PASSWORD=mypassword

Отключение авторизации

APPLICATION_SECURITY_ENABLED=false

Все эндпоинты становятся доступны без авторизации. Подходит для dev-окружений.

Health Check

curl http://<APP_HOST>:8080/actuator/health

Доступен без авторизации. Используется для liveness/readiness probes в Kubernetes.