Создаём мок в Конструкторе

Здесь описаны поля Конструктора. Для первого практического мока начните с обучения в интерфейсе или «Быстрого старта».

Поля и протоколы

Путь: /ui/constructor

Конструктор — это место, где вы создаёте и редактируете моки. Вместо того чтобы писать JSON вручную, вы заполняете пошаговую форму: выбираете протокол, задаёте маршрут, определяете условия и создаёте ответ. Это основной инструмент, который вы будете использовать в повседневной работе с Mockarty.

Первый HTTP-мок за пять шагов

1. Выберите HTTP REST.
2. Укажите метод и путь, например GET /hello.
3. Впишите ответ в формате JSON. Для первого примера оставьте статус 200.
4. Нажмите «Проверить» и посмотрите, что получит приложение.
5. Нажмите «Создать». После успешного сохранения вызовите мок из API-тестера или своего приложения.

Ниже разобраны остальные поля и протоколы — возвращайтесь к ним по мере необходимости.

Если удобнее описать мок словами, попробуйте Generate Mock. Кнопка Improve Mock предложит изменения для заполненной формы. Проверьте результат перед сохранением; подробнее — в разделе об AI-функциях.

Выбор протокола

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

Прямые протоколы — обслуживаются нодой Mockarty по адресу /stubs/{namespace}/...:

• HTTP: RESTful HTTP-эндпоинты с параметрами маршрута, строками запроса и заголовками.
• GraphQL: Запросы и мутации, сопоставляемые по типу и имени операции.
• SOAP: SOAP/XML-сервисы, сопоставляемые по действию и пути.
• SSE: Server-Sent Events с сопоставлением по имени события.
• MCP: Инструменты, ресурсы и промпты Model Context Protocol.

Протоколы, которым нужен отдельный сервер — создайте мок здесь, затем сгенерируйте и запустите сервер, прежде чем отправлять запросы. См. «Руководство по генератору серверов».

• gRPC: Унарные и потоковые gRPC-методы с protobuf-данными.
• Kafka: Сообщения топиков. Нужен запущенный Kafka-кластер.
• RabbitMQ: Сообщения очередей и обменников. Нужен запущенный RabbitMQ.
• Socket: WebSocket, TCP и UDP коммуникация с сопоставлением по событиям.
• SMTP: Имитация SMTP-сервера электронной почты с сопоставлением по отправителю, получателю и содержимому сообщения.

После выбора протокола конструктор показывает поля конфигурации, специфичные для данного протокола.

Конфигурация HTTP-мока

Для HTTP-моков настройте следующие поля:

• Маршрут: Шаблон URL-пути для сопоставления. Поддерживает подстановочные сегменты (например, /api/users/*) и точные пути.
• HTTP-метод: HTTP-метод для сопоставления (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS или ANY для сопоставления всех методов).
• Код состояния: Код HTTP-состояния для возврата (например, 200, 201, 400, 404, 500).
• Заголовки ответа: Пары ключ-значение для заголовков ответа (Content-Type, Cache-Control и др.).
• Тело ответа: Тело ответа в формате JSON, XML, простого текста или бинарных данных. Поддерживает переменные Faker и интерполяцию JsonPath.

Конфигурация gRPC-мока

Для gRPC-моков:

• Имя сервиса: Полное имя gRPC-сервиса (например, mypackage.MyService).
• Имя метода: Имя RPC-метода (например, GetUser).
• Тело ответа: JSON-представление protobuf-сообщения ответа. Имена полей должны соответствовать proto-определению.
• Код ошибки: Опциональный код состояния gRPC для возврата (OK, CANCELLED, UNKNOWN, INVALID_ARGUMENT и др.).
• Сообщение об ошибке: Опциональное сообщение об ошибке при возврате gRPC-ошибки.

Конфигурация MCP-мока

Для MCP (Model Context Protocol) моков:

• Имя сервера: Имя MCP-сервера для маршрутизации.
• Имя инструмента: Имя MCP-инструмента для имитации.
• Схема входных данных: JSON Schema, описывающая входные параметры инструмента.
• Тело ответа: Содержимое ответа инструмента, поддерживающее переменные Faker и ссылки на хранилища.
• URI ресурса: Для моков типа ресурса — шаблон URI для сопоставления.
• Имя промпта: Для моков типа промпта — идентификатор промпта.

Конфигурация GraphQL-мока

Для GraphQL-моков:

• Тип операции: Query, Mutation или Subscription.
• Имя операции: Именованная операция для сопоставления (необязательно; если не указано, сопоставляется с любой операцией указанного типа).
• Тело ответа: Тело ответа GraphQL в стандартном формате { "data": { ... } }.
• Ответы с ошибками: Настройка ответов с ошибками, специфичными для GraphQL, в формате { "errors": [ ... ] }.

Конфигурация SOAP-мока

Для SOAP-моков:

• SOAP Action: Значение заголовка SOAPAction для сопоставления.
• Путь: Путь эндпоинта для сопоставления.
• Тело ответа: XML-конверт ответа. Поддерживает переменные Faker внутри XML-элементов.
• WSDL: Опциональное содержимое WSDL для валидации и автодополнения.

Конфигурация Kafka-мока

Для Kafka-моков:

• Топик: Имя Kafka-топика для сопоставления.
• Имя сервера: Логическое имя сервера для маршрутизации (привязывает мок к конкретному экземпляру Kafka-сервера).
• Тело ответа: Значение сообщения для возврата, поддерживающее JSON или простой текст с Faker-интерполяцией.
• Ключ: Опциональный ключ сообщения.
• Заголовки: Опциональные заголовки Kafka-сообщения.

Конфигурация RabbitMQ-мока

Для RabbitMQ-моков:

• Очередь / Обменник: Имя очереди или обменника для сопоставления.
• Ключ маршрутизации: Шаблон ключа маршрутизации.
• Имя сервера: Логическое имя сервера для маршрутизации.
• Тело ответа: Тело сообщения для возврата.
• Заголовки: Опциональные заголовки AMQP-сообщения.

Конфигурация SSE-мока

Для SSE (Server-Sent Events) моков:

• Имя события: Тип SSE-события для сопоставления.
• Имя сервера: Логическое имя сервера для маршрутизации.
• Тело ответа: Данные события для отправки.
• Повторное подключение: Опциональный интервал переподключения в миллисекундах.
• Идентификатор: Опциональный идентификатор события для отслеживания на стороне клиента.

Конфигурация Socket-мока

Для WebSocket и сырых сокет-моков:

• Имя сервера: Логическое имя сервера для маршрутизации (определяет, какой сгенерированный Socket-сервер обрабатывает этот мок).
• Имя события: Имя события для сопоставления (для маршрутизации сообщений WebSocket/TCP/UDP).
• Тело ответа: Сообщение для отправки обратно, поддерживающее JSON или текст.

Конфигурация SMTP-мока

Для SMTP-моков:

• Имя сервера: Логическое имя SMTP-сервера для маршрутизации.
• Отправитель (From): Шаблон адреса электронной почты отправителя для сопоставления.
• Получатель (To): Шаблон адреса электронной почты получателя для сопоставления.
• Тема: Тема письма для сопоставления.
• Тело ответа: SMTP-ответ для возврата, поддерживающий переменные Faker и ссылки на хранилища.

Вкладка условий

Условия определяют, когда мок должен быть выбран для данного запроса. Несколько условий можно комбинировать (все условия должны совпасть, чтобы мок был выбран — логика И).

Условия по телу (JsonPath)

Сопоставление по определённым полям в теле запроса с помощью выражений JsonPath:

• JsonPath: Выражение пути для проверки тела запроса (например, $.user.name, $.items[0].id).

• Действие проверки: Операция сравнения. Mockarty поддерживает 13 действий проверки:

  Действие	Значение в JSON	Описание	Пример
  Equals	equals	Точное совпадение. Для строк сравнивает буквально. Для объектов и массивов выполняет глубокое сравнение.	$.user.role equals "admin"
  Contains	contains	Для строк – поиск подстроки. Для объектов – проверяет, что ожидаемые поля являются подмножеством. Для массивов – проверяет наличие элемента. У чисел и логических значений подстроки нет, поэтому проверяется точное совпадение: 100 не содержит 10.	$.user.name contains "john"
  Not Equals	not_equals	Отрицание equals. Совпадает, когда значение НЕ равно ожидаемому.	$.status not_equals "deleted"
  Not Contains	not_contains	Отрицание contains. Совпадает, когда значение НЕ содержит ожидаемую подстроку или подмножество, а для числа или логического значения – когда оно не равно этому значению.	$.tags not_contains "deprecated"
  Any	any	Всегда совпадает, независимо от значения. Действует как подстановочный знак – ожидаемое значение игнорируется.	$.request_id any
  Not Empty	notEmpty	Совпадает, когда значение непустое: не null, непустая строка, непустой массив или непустой объект.	$.user.email notEmpty
  Empty	empty	Совпадает, когда значение пустое: null, пустая строка "", пустой массив [] или пустой объект {}.	$.error empty
  Matches	matches	Сопоставление с регулярным выражением. Ожидаемое значение – шаблон регулярного выражения.	$.email matches "^[a-z]+@example\\.com$"
  Not Matches	not_matches	Негация Matches – совпадает, когда значение НЕ соответствует regex (отсутствующее поле совпадает).	$.email not_matches "@blocked\\.com$"
  Is Number	is_number	Совпадает, когда значение числовое.	$.amount is_number
  Greater Than	gt	Совпадает, когда значение численно больше ожидаемого числа. Обе стороны разбираются как числа.	$.amount gt 100
  Less Than	lt	Совпадает, когда значение численно меньше ожидаемого числа. Обе стороны разбираются как числа.	$.qty lt 10
  Больше или равно	gte	Совпадает, когда значение численно больше ИЛИ равно ожидаемому числу (включительно).	$.amount gte 100
  Меньше или равно	lte	Совпадает, когда значение численно меньше ИЛИ равно ожидаемому числу (включительно).	$.qty lte 10
  Num Digits	num_digits	Совпадает, когда строка содержит ожидаемое число цифр.	$.code num_digits 6
  Starts With	starts_with	Совпадает, когда строка начинается с ожидаемого префикса.	$.sku starts_with "PRD-"
  Ends With	ends_with	Совпадает, когда строка заканчивается ожидаемым суффиксом.	$.file ends_with ".pdf"
  One Of	one_of	Совпадает, когда значение входит в ожидаемый список.	$.status one_of ["active","trial"]

  Примечание: Устаревший псевдоним match также принимается и работает идентично matches.

• Ожидаемое значение: Значение для сравнения.

Условия по заголовкам

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

• Имя заголовка: Имя HTTP-заголовка (регистронезависимое для HTTP, регистрозависимое для gRPC-метаданных).
• Действие проверки: Те же варианты, что и для условий по телу.
• Ожидаемое значение: Значение заголовка для сравнения.

Условия по параметрам запроса

Сопоставление по параметрам URL-запроса (только HTTP):

• Имя параметра: Ключ параметра запроса.
• Действие проверки: Те же варианты, что и для условий по телу.
• Ожидаемое значение: Значение параметра для сравнения.

Можно добавить несколько условий каждого типа. Все условия должны быть выполнены для совпадения мока.

Расширенные поля условий (только API)

При создании условий через REST API (не в веб-интерфейсе) каждый объект условия поддерживает дополнительные поля:

Пример через API:

{
  "path": "$.data",
  "assertAction": "equals",
  "value": "expected",
  "decode": "base64",
  "sortArray": true,
  "valueFromFile": "/templates/expected-response.json"
}

Примечание: decode, sortArray и valueFromFile не доступны в визуальном конструкторе Web UI. Используйте REST API (POST /api/v1/mocks) для установки этих полей.

Вкладка ответа

Вкладка ответа предоставляет полноценный редактор для создания ответа мока:

Редактор тела ответа

Редактор кода (с подсветкой синтаксиса для JSON и XML) для написания тела ответа. Редактор поддерживает:

• Переменные Faker: Вставка динамических данных с помощью выражений $.fake.*. Например:

  • $.fake.UUID – генерирует случайный UUID.
  • $.fake.FirstName – генерирует случайное имя.
  • $.fake.Email – генерирует случайный адрес электронной почты.
  • $.fake.Number – генерирует случайное целое число.
  • Полный список см. в Справочнике Faker-функций.

• Интерполяция JsonPath: Ссылка на данные из входящего запроса (полный синтаксис см. в Руководстве по JsonPath):

  • $.req.fieldName – извлечение поля из тела запроса.
  • $.queryParams.page – извлечение параметра запроса.
  • $.reqHeader.Authorization[0] – извлечение заголовка запроса.

• Ссылки на хранилища: Доступ к значениям из любого из трёх типов хранилищ (подробнее см. Системы хранилищ):

  • $.gS.keyName – чтение из Global Store.
  • $.cS.keyName – чтение из Chain Store.
  • $.mS.keyName – чтение из Mock Store.

• Математические и логические операции: Динамическое вычисление значений:

  • $.sum(a, b) – сложение.
  • $.multiply(a, b) – умножение.
  • $.increment(key) – атомарное увеличение счётчика в хранилище.
  • $.subtract(expr1, expr2) – вычитание expr2 из expr1 (напр. $.subtract($.gS.counter, 1) для уменьшения на 1).
  • $.divide(expr1, expr2) – деление expr1 на expr2 (деление на ноль даёт 0).
  • $.modulo(expr1, expr2) – остаток от деления expr1 / expr2.

Код состояния

Установка кода HTTP-состояния (или кода состояния gRPC для gRPC-моков). Интерфейс предоставляет выпадающий список с распространёнными кодами и их описаниями.

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

Добавление пользовательских заголовков ответа в виде пар ключ-значение. Распространённые заголовки можно выбрать из выпадающего списка для удобства.

Задержка ответа

Настройка искусственной задержки (в миллисекундах) перед отправкой ответа. Полезно для имитации медленных сервисов и тестирования обработки таймаутов.

OneOf-ответы

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

• Упорядоченные: Ответы возвращаются в определённом порядке, циклически возвращаясь к первому после использования всех. Полезно для имитации изменений состояния (например, первый вызов возвращает «pending», второй — «completed»).
• Случайные: Случайный ответ выбирается для каждого запроса. Полезно для имитации нестабильных сервисов или переменного поведения.

Каждый вариант ответа имеет собственные тело, код состояния, заголовки и конфигурацию задержки. Добавляйте варианты с помощью кнопки «Добавить ответ» на вкладке ответа.

Режим прокси

Вместо возврата статического или шаблонного ответа мок может проксировать запрос на реальный бэкенд-сервис:

• Целевой URL: Базовый URL бэкенд-сервиса для перенаправления запросов.
• Задержка ответа: Настраивается на вкладке Response (в миллисекундах) для имитации сетевой задержки или медленной обработки. Применяется как к статическим, так и к проксированным ответам.
• Заголовки ответа: Переопределение или добавление заголовков через вкладку Response — полезно для настройки CORS, добавления заголовков трассировки или изменения токенов аутентификации в проксированном ответе.
• Передавать полный путь запроса (HTTP): адрес на реальном сервисе — цель плюс путь, который запросил клиент. С целью https://api.example.com/v2 запрос /users/7 уходит на https://api.example.com/v2/users/7. Выключено — цель соответствует маршруту самого мока.
• Убрать префикс пути: отрезается от начала пути перед пересылкой — /gateway превращает /gateway/users в /users.
• Заголовки для сервера назначения: по одному на строку в виде Имя: значение, например API-ключ, который нужен реальному сервису. Они заменяют одноимённый заголовок клиента и не попадают в записанный запрос клиента.
• Не пересылать заголовки клиента: имена через запятую (например, Cookie), которые убираются перед отправкой запроса дальше.
• Записывать сквозной трафик: при включении каждый проксированный запрос и реальный ответ апстрима захватываются в «Неопределённые запросы». Оттуда захваченный вызов конвертируется в настоящий мок в один клик — мок создаётся с наблюдённым методом, маршрутом, условиями по query/телу и предзаполненным реальным ответом. Захват работает для прокси-моков HTTP, SOAP, GraphQL, gRPC и MCP.

Режим прокси полезен для:

• Записи и сравнения реальных и мокированных ответов.
• Тестирования поведения при таймаутах (добавление задержки к реальным ответам).
• Добавления «токсичности» к реальным сервисам (прерывистые ошибки, медленные ответы).
• Записи реальных ответов при их прохождении.
• Изменения заголовков ответа без изменения бэкенда.

Экстракторы хранилищ

Экстракторы хранилищ захватывают данные из входящих запросов и сохраняют их в один из трёх типов хранилищ для последующего использования:

• Global Store (gS): Постоянное состояние в рамках пространства имён. Значения сохраняются между запросами и моками. Идеально для счётчиков, флагов функций и общего состояния.
• Chain Store (cS): Состояние в рамках цепочки запросов. Значения сохраняются между связанными моками в рабочем процессе (например, создание -> получение -> обновление). Связываются по идентификатору цепочки.
• Mock Store (mS): Эфемерное состояние на один запрос. Значения существуют только во время обработки одного разрешения мока. Полезно для промежуточных вычислений.

Для каждого экстрактора настройте:

• Источник: Откуда извлекать данные (тело, заголовок, параметр запроса, параметр пути).
• JsonPath: Выражение JsonPath для вычисления (для извлечения из тела).
• Тип хранилища: gS, cS или mS.
• Ключ: Ключ, под которым будет сохранено извлечённое значение.

TTL и лимиты использования

Управление жизненным циклом мока:

• TTL (Time to Live): Мок автоматически истекает после указанного срока (например, 1 час, 24 часа, 7 дней). После истечения мок больше не разрешает запросы. Полезно для временных тестовых сценариев.
• Лимит использования: Мок истекает после указанного количества разрешений. После достижения лимита последующие запросы не сопоставляются. Полезно для одноразовых тестовых сценариев.

Когда мок истекает (по TTL или лимиту использования), он остаётся видимым в списке моков с пометкой «истёкший». Его можно вручную повторно включить или удалить.

Настройка приоритета

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

• Более высокие значения приоритета имеют преимущество.
• Приоритет по умолчанию равен 0.
• Моки с условиями обычно получают более высокий приоритет, чем универсальные моки.
• Приоритет особенно важен при использовании широких шаблонов маршрутов наряду с конкретными.

Теги

Теги обеспечивают гибкую систему категоризации:

• Добавляйте один или несколько тегов к любому моку с помощью поля ввода тегов.
• Теги имеют цветовую кодировку для визуального различения.
• Используйте теги для сквозных задач (например, «payment», «v2», «regression», «flaky»).
• Фильтруйте моки по тегу на странице моков.
• Массово применяйте теги с помощью функции массовых операций.

Внешний вид

Конструктор работает в светлой и тёмной темах. Переключить тему можно в меню профиля.

Если запросы уже закрывает другой мок

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

Поэтому при сохранении Mockarty заранее проверяет маршрут и, если такой мок уже есть,
показывает окно:

• какой именно мок мешает — с ссылкой, открывающей его в новой вкладке, чтобы посмотреть,
  не закрывая заполненную форму;
• кто его создал — чаще всего договориться быстрее, чем менять;
• почему выигрывает именно он — сравниваются приоритет и, при равном приоритете, время
  сохранения (позже сохранённый выигрывает);
• что можно сделать: поднять приоритет одному из них или добавить условие, чтобы каждый
  отвечал на свой запрос.

Кнопки две: отменить создание и всё равно сохранить. Это предупреждение, а не запрет —
если вы намеренно заменяете старый мок, сохраните и удалите его.

Сравниваются только условия срабатывания, не ответы. Сообщение «этот мок перекрывается
таким-то» не значит, что тот мок вам подходит: он может отвечать совсем другое и существовать
для другой задачи. Речь только о том, что оба ловят один и тот же запрос.

Окно появляется, когда совпадение доказуемо: одинаковые маршрут и метод, и при этом либо
оба мока без условий, либо набор условий полностью совпадает. Частично пересекающиеся условия
не сообщаются: понять, пересекаются ли они на реальном трафике, без самого трафика нельзя, а
предупреждение, срабатывающее на нормальной паре моков, быстро приучает жать «всё равно
сохранить», не читая.