Migrating from Mockoon to Mockarty

If you already use Mockoon (the desktop app, mockoon-cli, or the
container image) to serve mock APIs, you can move your environments
to Mockarty. Routes, response rules, templated bodies and the data
buckets they read transfer as they are. This guide walks through the
import path and states exactly where Mockoon and Mockarty diverge.

At a glance

• Same environment.json — Mockarty imports the file Mockoon
  saves: routes, folders, response definitions and response rules.
• Same response rules — equals, regex, regex_i, null,
  empty_array, array_includes work on the body, query, header,
  cookie, params, path, method and request_number targets, with the
  same rulesOperator (OR/AND) and invert semantics.
• Same templating. Mockoon’s Handlebars helpers — {{urlParam 'id'}},
  {{body 'user.name'}}, {{data 'pets'}}, {{int 1 100}},
  {{faker 'person.firstName'}}, {{#each}}, {{#switch}} — are
  evaluated by Mockarty at request time, in the response body and in
  response headers. You do not rewrite them. See
  Templating: what runs for the full list and
  the three helpers that do not carry over.
• Same data buckets. The buckets your templates read are imported
  with the routes that use them, so {{data 'pets'}} returns your data.

Read “What gets imported” below before migrating: it lists exactly
which parts of an environment transfer and which do not.

Two ways to use your Mockoon environment

Option 1 — Drop-in container

Run the universal mockarty/cli image with --format=mockoon and
mount your environment file:

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

The container serves every route from the environment, applies your
response rules and evaluates your Handlebars templating. Anonymous mode is capped at 5 stubs — set
MOCKARTY_LICENSE_KEY or run mockarty-cli login to lift the cap.

Option 2 — Import into your Mockarty instance

Convert the environment to Mockarty mock files, then import them:

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 writes one file per Mockoon route and carries the route’s response
rules across; import uploads them to the namespace you are logged in to (pass
--namespace to target another one). Both commands exit non-zero if any file
fails, so a CI step can rely on the exit code.

mockarty-cli mock serve --format mockoon --data-dir ./mockoon-env/ is a
different thing: it serves the environment locally as a drop-in replacement
(Option 1) and does not upload anything.

Each Mockoon route becomes one Mockarty mock. The Mockoon UUID is
preserved (Mockarty stores it as mn_<uuid>), so the same export
can be re-imported without duplicates.

What gets imported

Templating: what runs

Mockoon’s Handlebars helpers are evaluated by Mockarty when the mock is
served, so a body like

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

returns real values, not the helper text. Templating runs in the
response body and in response header values. Nothing needs
rewriting.

Supported helpers

Named (hash) arguments work too: {{faker 'number.int' min=10 max=100}},
{{dateTimeShift date='2024-01-01' format='YYYY-MM-DD' days=7}},
{{object id='7' name='Ada'}}.

{{ }} and {{{ }}} behave as in Mockoon: neither escapes HTML, so a
JSON body stays JSON.

Not supported

Three helpers do not carry over. A body using one of them still renders —
that helper alone produces an empty value.

Where behaviour is close but not identical

• jsonPath evaluates standard JSONPath. Selectors and simple
  filters behave as expected; the JSONPath-Plus-only extensions
  (^, @property, @path) do not.
• Faker covers the commonly used namespaces (person, internet,
  location, company, commerce, finance, date, string,
  number, lorem, image, phone, vehicle, music, animal,
  git, database, system, color) — not every method Faker.js
  offers. An unknown method renders as an empty value; the older name.*
  and address.* spellings resolve as well as person.* / location.*.
• Date format tokens cover YYYY, YY, MM, DD, HH, mm,
  ss, SSS. Other tokens are passed through literally.
• Global variables (setGlobalVar / getGlobalVar) are scoped to
  your namespace, so two teams on the same Mockarty instance cannot
  read or overwrite each other’s values.
• disableTemplating is a per-response checkbox in Mockoon and a
  per-route setting in Mockarty. Disable it on every response of a route
  and the braces are served verbatim; disable it on only some and the
  import warns you — split those into their own route.
• A body that fails to render — an unclosed {{#each}}, for example —
  is served as written, with the error in the server log. The mock keeps
  answering; it never turns into a 500.

If you also want Mockarty’s own syntax

Mockarty has its own dynamic-response syntax, used by mocks you create in
Mockarty itself. It is never applied to an imported Mockoon body, so the
two cannot collide. The equivalents, if you ever want to move a body over:

The full catalogue of Mockarty helpers is in the in-product reference
(admin UI → Docs → Templating).

Where Mockoon and Mockarty differ

A few features stay on the Mockoon side only:

• PFX TLS bundles — Mockarty reads them but cannot decrypt them
  yet; export your cert to PEM (openssl pkcs12 -in cert.pfx -out cert.pem -nodes) and put a TLS-terminating reverse proxy (nginx/Caddy) in front of mock serve.
• CRUD routes (type: "crud") — a Mockoon CRUD route generates
  nine endpoints backed by a data bucket. The import marks the route
  with a type:crud tag but does not generate those endpoints;
  rebuild them as ordinary mocks.
• WebSocket routes (type: "ws") — imported as a tag only.
  Re-create them as Mockarty Socket mocks.
• Proxy mode (proxyMode, proxyHost, proxy header rules) —
  recorded as a tag; configure proxying on the Mockarty side.
• cors — recorded as a tag; enable it in the admin UI.
• PFX TLS bundles — export your cert to PEM (openssl pkcs12 -in cert.pfx -out cert.pem -nodes) and terminate TLS with a reverse
  proxy (nginx/Caddy) in front of mock serve.

The import prints a warning for each of these, plus for any response
rule whose target or operator we do not implement (global_var,
data_bucket, templating targets and the valid_json_schema
operator — a rule using one of them never fires, rather than firing
wrongly). Read the warnings: they are the checklist of what still
needs doing by hand after the import.

Round-trip export

Mockarty exports your mocks (Mockarty format) for backup or moving
between instances:

mockarty-cli mock export -d ./mocks/

UUIDs are preserved, so re-importing does not create duplicates.

Troubleshooting

• “environment lastMigration=NN exceeds known max” — your
  Mockoon file is from a newer version than this Mockarty release.
  Most fields still import correctly; please upgrade Mockarty when
  the new version lands.
• Response body contains literal {{ ... }} — the template could
  not be parsed, so the body was served as written. Check the server log
  for the reason (usually an unclosed block such as {{#each}} without
  {{/each}}). If you imported the environment with an older Mockarty,
  import it again: templating is switched on for a route during the
  import itself.
• One helper renders empty, the rest work — that helper is either not
  supported (setData, jmesPath, getEnvVar) or is a Faker method
  outside the covered namespaces. See “Templating: what runs”.
• A response rule never fires — check the import warnings. Rules
  targeting global_var, data_bucket or templating, and rules
  using the valid_json_schema operator, are not implemented and
  deliberately never match.
• CORS preflight returns 404 — enable namespace-level CORS in
  Mockarty admin settings (Mockoon’s per-environment CORS is
  surfaced as a tag, not auto-applied to your namespace).