type: service
status: active
timestamp: 2026-06-20
tags: [testing, api-mock, mockoon, out-of-process, e2e, primary]

Mockoon

Out-of-process API mock — OSS desktop + CLI, real HTTP server on localhost

Mockoon

Role

The family’s out-of-process API-mock tool. Used for the surfaces where the code-under-test is the deployed Hono Worker (or a local wrangler dev) hitting a third-party API the family doesn’t own — the test points the Worker at http://localhost:3001 and Mockoon serves the third-party shape on that port:

E2E (Playwright) suites against Razorpay sandbox
Offline / quota-conscious testing against Open-Meteo and Alpha Vantage (per the data-APIs decision, Alpha Vantage’s 25 req/day budget is the family’s tightest cap — burning it from CI is wasteful)
Manual exploratory dev when an upstream is rate-limited / down

In-process unit / Storybook mocking lives at MSW — see api-mocks-msw-plus-mockoon for the surface split.

Free tier

Unlimited — MIT OSS
Desktop app for Windows / macOS / Linux (Electron — but only for the GUI; the actual mock server is plain Node)
Headless CLI (@mockoon/cli) for CI usage — no GUI required
No account, no telemetry by default, no quota

Card / subscription required?

NO. OSS, distributed via the Mockoon site + npm i -g @mockoon/cli.

How CI consumes it

- name: Install Mockoon CLI
  run: pnpm add -D @mockoon/cli

- name: Start Mockoon (Razorpay sandbox shape)
  run: |
    pnpm exec mockoon-cli start \
      --data tests/mockoon/razorpay.json \
      --port 3001 \
      --daemon-off &
    sleep 2

- name: E2E against mocked Razorpay
  run: pnpm playwright test
  env:
    BASE_URL_RAZORPAY: http://localhost:3001
    PREVIEW_URL: ${{ steps.deploy-preview.outputs.url }}

Mockoon environment files (JSON) ship from @chirag127/oriz-kit/testing/mockoon/ — one per third-party shape (razorpay.json, open-meteo.json, alpha-vantage.json). They’re version-controlled alongside the rest of the test scaffolding.

Manual dev usage

# Launch the GUI for exploratory work:
mockoon-cli start --data ~/.config/mockoon/razorpay.json --port 3001
# Or open the GUI app, load the environment, hit "Start"
# Then point your local Worker at it:
echo 'BASE_URL_RAZORPAY=http://localhost:3001' >> .env
pnpm dev

Alternatives

MSW — sibling, picked alongside Mockoon for in-process surfaces, NOT a competitor.
WireMock — JVM-based; install + JVM dependency overhead too heavy for the family’s all-Node toolchain.
json-server — too thin; doesn’t model error paths / latency / state transitions the way Mockoon does.
Postman Mock Server — paid past trial; fights rules/no-card-on-file.md.
Beeceptor — paid past free tier; same.
Mocky.io — paid past free tier; same.

Swap cost

Low — Mockoon environments are a JSON dump of routes + responses. A swap to WireMock / json-server would translate the JSON shape but keep the test plumbing (CI step, BASE_URL_* env-var) intact.

Why this is our pick

Free, OSS, Node-based (no JVM), GUI for exploratory work AND CLI for CI — same JSON definition either way. Importantly: the third-party APIs the family hits (Razorpay, Open-Meteo, Alpha Vantage) all have quota limits or sandbox throttles, and Mockoon’s process model is the right shape for the deployed Worker → upstream pattern that hits those limits hardest.

Cross-refs

Edit on GitHub · Back to index