Миграция с Mockoon на Mockarty

Если вы уже используете Mockoon (десктопное приложение,
mockoon-cli или контейнер) для эмуляции API, ваши environment’ы
можно перенести в Mockarty. Маршруты, response rules, шаблонные тела и
data buckets, которые они читают, переезжают как есть. Документ
описывает импорт и точно указывает, где Mockoon и Mockarty расходятся.

Кратко

• Тот же environment.json — Mockarty принимает файл, который
  сохраняет Mockoon: маршруты, папки, определения ответов и response
  rules.
• Те же response rules — equals, regex, regex_i, null,
  empty_array, array_includes для body, query, header, cookie,
  params, path, method и request_number, с той же семантикой
  rulesOperator (OR/AND) и invert.
• Та же шаблонизация. Handlebars-хелперы Mockoon —
  {{urlParam 'id'}}, {{body 'user.name'}}, {{data 'pets'}},
  {{int 1 100}}, {{faker 'person.firstName'}}, {{#each}},
  {{#switch}} — вычисляются Mockarty на каждом запросе: и в теле
  ответа, и в его заголовках. Переписывать ничего не нужно. Полный
  список и три хелпера, которые не переехали, — в разделе
  Шаблонизация: что работает.
• Те же data buckets. Бакеты, которые читают ваши шаблоны,
  импортируются вместе с маршрутами, поэтому {{data 'pets'}}
  возвращает ваши данные.

Перед миграцией прочитайте раздел «Что импортируется»: там перечислено,
какие части environment переносятся, а какие нет.

Два способа использовать ваш environment

Вариант 1 — Drop-in контейнер

Запустите универсальный образ mockarty/cli с --format=mockoon,
смонтировав файл environment:

docker run --rm -p 3001:8080 \
  -v $(pwd)/environment.json:/data/env.json:ro \
  mockarty/cli mock serve --data-dir /data --format mockoon

Контейнер отдаст каждый маршрут из environment’а, применит правила
ответов и шаблонизацию точно так же, как mockoon-cli. Без
лицензии работает ограничение в 5 стабов — установите
MOCKARTY_LICENSE_KEY или выполните mockarty-cli login чтобы
снять кап.

Вариант 2 — Импорт в ваш инстанс Mockarty

Сконвертируйте окружение в файлы моков Mockarty и импортируйте их:

mockarty-cli login --server https://mockarty.company.com --token mk_xxx
mockarty-cli mock convert --from mockoon --out ./mockarty-mocks ./mockoon-env/
mockarty-cli mock import -f ./mockarty-mocks

convert пишет по одному файлу на маршрут Mockoon и переносит правила выбора
ответа; import загружает их в namespace, под которым вы вошли (другой
задаётся флагом --namespace). Обе команды возвращают ненулевой код, если хоть
один файл не прошёл, — шаг CI может полагаться на код выхода.

mockarty-cli mock serve --format mockoon --data-dir ./mockoon-env/ — это
другое: он обслуживает окружение локально как drop-in замену (Вариант 1) и
ничего никуда не загружает.

Каждый маршрут Mockoon становится одним моком Mockarty. UUID
Mockoon сохраняется (Mockarty хранит как mn_<uuid>), так что один
и тот же экспорт можно переимпортировать без дублей.

Что попадает в импорт

Шаблонизация: что работает

Handlebars-хелперы Mockoon вычисляются Mockarty в момент отдачи мока,
поэтому тело вида

{
  "id": "{{urlParam 'id'}}",
  "name": "{{faker 'person.firstName'}}",
  "pets": {{data 'pets'}}
}

возвращает реальные значения, а не текст хелпера. Шаблонизация работает
в теле ответа и в значениях response-заголовков. Переписывать
ничего не нужно.

Поддерживаемые хелперы

Именованные аргументы тоже работают:
{{faker 'number.int' min=10 max=100}},
{{dateTimeShift date='2024-01-01' format='YYYY-MM-DD' days=7}},
{{object id='7' name='Ada'}}.

{{ }} и {{{ }}} ведут себя как в Mockoon: HTML не экранируется, поэтому
JSON-тело остаётся валидным JSON.

Что не поддерживается

Три хелпера не переехали. Тело с любым из них всё равно отрендерится —
пустым будет только сам этот хелпер.

Где поведение близкое, но не идентичное

• jsonPath вычисляет стандартный JSONPath. Селекторы и простые
  фильтры работают; расширения JSONPath-Plus (^, @property, @path)
  — нет.
• Faker покрывает основные пространства имён (person, internet,
  location, company, commerce, finance, date, string,
  number, lorem, image, phone, vehicle, music, animal,
  git, database, system, color), но не каждый метод Faker.js.
  Неизвестный метод отдаёт пустое значение; старые написания name.* и
  address.* резолвятся наравне с person.* / location.*.
• Токены формата даты: YYYY, YY, MM, DD, HH, mm, ss,
  SSS. Остальные символы переносятся в результат как есть.
• Глобальные переменные (setGlobalVar / getGlobalVar) живут в
  пределах вашего неймспейса, поэтому две команды на одном сервере
  Mockarty не видят и не перезаписывают значения друг друга.
• disableTemplating в Mockoon — чекбокс у ответа, в Mockarty —
  настройка маршрута. Выключите его у всех ответов маршрута — скобки
  отдадутся дословно; выключите у части — импорт предупредит, такие
  ответы стоит вынести в отдельный маршрут.
• Тело, которое не удалось отрендерить (например, незакрытый
  {{#each}}), отдаётся как написано, а причина попадает в лог сервера.
  Мок продолжает отвечать и никогда не превращается в 500.

Если всё-таки нужен синтаксис Mockarty

У Mockarty есть собственный синтаксис динамических ответов — им
пользуются моки, созданные прямо в Mockarty. К импортированному телу
Mockoon он не применяется, поэтому два синтаксиса не конфликтуют.
Соответствия, если вы захотите перевести тело:

Полный каталог хелперов Mockarty — в админке (Docs → Templating).

Чем Mockoon и Mockarty отличаются

Несколько фич пока остаются только в Mockoon:

• PFX TLS bundles — Mockarty читает их, но не расшифровывает;
  экспортируйте сертификат в PEM (openssl pkcs12 -in cert.pfx -out cert.pem -nodes) и поставьте TLS-терминирующий reverse-proxy (nginx/Caddy) перед mock serve.
• CRUD-маршруты (type: "crud") — CRUD-маршрут Mockoon
  порождает девять эндпоинтов поверх data bucket. Импорт помечает
  маршрут тегом type:crud, но эти эндпоинты не создаёт —
  соберите их как обычные моки.
• WebSocket маршруты (type: "ws") — импортируются только как
  тег. Пересоздайте их как Socket-моки Mockarty.
• Proxy mode (proxyMode, proxyHost, правила proxy-заголовков)
  — записывается тегом; проксирование настраивается на стороне Mockarty.
• cors — записывается тегом; включается в админке.
• PFX TLS bundles — экспортируйте сертификат в PEM
  (openssl pkcs12 -in cert.pfx -out cert.pem -nodes) и поставьте
  TLS-терминирующий reverse-proxy (nginx/Caddy) перед mock serve.

По каждому из этих пунктов импорт печатает предупреждение — как и по
каждому response rule, чей target или оператор мы не реализуем
(таргеты global_var, data_bucket, templating и оператор
valid_json_schema: такое правило никогда не срабатывает, а не
срабатывает ошибочно). Читайте предупреждения — это и есть список
того, что после импорта надо доделать руками.

Round-trip экспорт

Mockarty выгружает ваши моки в формате Mockarty (для бэкапа или
переноса между инстансами). Обратной выгрузки в формат
Mockoon-environment нет:

mockarty-cli mock export -d ./mocks/

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

Траблшутинг

• «environment lastMigration=NN exceeds known max» — ваш файл
  Mockoon из новой версии, незнакомой релизу Mockarty. Большинство
  полей всё ещё импортируется корректно; обновите Mockarty когда
  выйдет новая версия.
• В теле ответа виден дословный {{ ... }} — шаблон не удалось
  разобрать, и тело отдано как написано. Причина — в логе сервера
  (обычно незакрытый блок: {{#each}} без {{/each}}). Если
  environment импортирован более старой версией Mockarty, выполните
  импорт заново: шаблонизация включается для маршрута в момент импорта.
• Один хелпер пустой, остальные работают — либо он не поддерживается
  (setData, jmesPath, getEnvVar), либо это метод Faker вне
  покрытых пространств имён. См. «Шаблонизация: что работает».
• Response rule никогда не срабатывает — посмотрите предупреждения
  импорта. Правила с таргетами global_var, data_bucket,
  templating и с оператором valid_json_schema не реализованы и
  намеренно не матчатся.
• CORS preflight возвращает 404 — включите namespace-level CORS
  в admin-настройках Mockarty (CORS из Mockoon-environment’а
  попадает как тэг, не как глобальное правило).