How it is built.
One implementation, no dependencies, and a promise that is checked. The short version is all of it. The rest of this page is why each piece is the way it is.
System Overview
The following diagram shows the high-level architecture of API Mock Services:
src/harness.js] STATE[State Manager
service.state, service.requests] ROUTER[Route Matcher
service.on(), service.routes] CONTROL[Control Surface
/_control/*] SHUTDOWN[Shutdown Manager
src/shutdown.js] end subgraph "Provider Mocks (78)" direction TB PAYMENTS[Payments: Stripe, PayPal,
PayPal, Square, Adyen,
Paystack, Interswitch,
Flutterwave, Monnify] IDENTITY[Identity: YouVerify,
SmileID, IdentityPass] MESSAGING[Messaging: Twilio, Termii,
WhatsApp, FCM, OneSignal] EMAIL[Email: Resend, SendGrid,
Mailchimp, Klaviyo, Postmark] ACCOUNTING[Accounting: Xero, QuickBooks,
NetSuite, Sage] DNS[DNS: Cloudflare] AI[AI: OpenAI] STORAGE[Storage: S3] SHIPPING[Shipping: Shippo, EasyPost,
FedEx, UPS, DHL] MARKETPLACES[Marketplaces: Amazon SP-API,
Shopify, eBay, Etsy, Walmart] CRM[CRM: HubSpot, Salesforce,
Pipedrive, Attio] ERP[ERP/Inventory: Cin7, DEAR,
TradeGecko, Katana] TAX[Tax: Avalara, TaxJar, Vertex] POS[POS: Square Terminal,
Clover, Toast, Lightspeed] ANALYTICS[Analytics: Segment,
Mixpanel, Amplitude,
RudderStack] SOCIAL[Social: Facebook, Instagram,
X, Bluesky, Telegram,
Reddit, LinkedIn,
TikTok, YouTube] end subgraph "UI Layer (optional)" PANEL[Control Panel
/_panel] CHECKOUT[Hosted Checkout
/checkout/:ref] end TC -->|HTTP| PAYMENTS TC -->|HTTP| IDENTITY TC -.->|HTTP| EMAIL TC -.->|HTTP| MESSAGING TC -.->|HTTP| SHIPPING TC -.->|HTTP| MARKETPLACES TC -.->|HTTP| CRM TC -.->|HTTP| ERP TC -.->|HTTP| TAX TC -.->|HTTP| POS TC -.->|HTTP| ANALYTICS TC -.->|HTTP| SOCIAL CLI -->|/_control| CONTROL CONTROL --> HARNESS HARNESS --> ROUTER HARNESS --> STATE HARNESS --> CONTROL HARNESS --> SHUTDOWN ROUTER --> PAYMENTS ROUTER --> IDENTITY ROUTER --> EMAIL ROUTER --> MESSAGING ROUTER --> SHIPPING ROUTER --> MARKETPLACES ROUTER --> CRM ROUTER --> ERP ROUTER --> TAX ROUTER --> POS ROUTER --> ANALYTICS ROUTER --> SOCIAL ROUTER --> SHIPPING ROUTER --> STORAGE ROUTER --> DNS ROUTER --> AI PAYMENTS --> STATE IDENTITY --> STATE EMAIL --> STATE MESSAGING --> STATE SHIPPING --> STATE MARKETPLACES --> STATE CRM --> STATE ERP --> STATE TAX --> STATE POS --> STATE ANALYTICS --> STATE SOCIAL --> STATE PAYMENTS -.->|checkout| CHECKOUT CHECKOUT -.->|onDone| PAYMENTS PANEL -.->|/_control| CONTROL
Source Layout
src/
harness.js the engine — routes, state, the control surface
index.js the public API
spec.js a mock written as a route file
providers/ the mocks, one file per group of them
ui/ everything a person sees: HTML, CSS, the panel
templates/ the markup
assets/ the styles
shutdown.js graceful shutdown manager
cassette.js HTTP record/playback
spec.js spec-based mocks
ui/
templates/ the markup
assets/ the styles
The Engine Knows Nothing About HTML
src/harness.js does four things: it matches a request to a
route, it records what it was asked, it keeps the state the mock
decided on, and it answers over a control surface
(/_control).
Everything a person sees — the control panel, the hosted checkout —
lives in src/ui/ and is put on a mock by
attachViews. The two are separated on purpose.
service.on(method, path, handler)] MATCH[Request Matching
path params extraction] STATE[State Management
service.state, service.requests] CTRL[Control Surface
/_control/* endpoints] SHUT[Shutdown Hooks
SIGTERM, SIGINT handlers] end subgraph "UI Layer (src/ui/)" PANEL[Control Panel HTML/CSS/JS] CHECKOUT[Hosted Checkout Pages] end ROUTE --> MATCH MATCH --> STATE MATCH --> CTRL MATCH --> SHUT CTRL -.->|attaches| PANEL CTRL -.->|attaches| CHECKOUT style ROUTE fill:#e1f5fe style MATCH fill:#e1f5fe style STATE fill:#e1f5fe style CTRL fill:#fff3e0 style SHUT fill:#fff3e0 style PANEL fill:#f3e5f5 style CHECKOUT fill:#f3e5f5
Engine / UI Separation
The engine works without the browser
new MockService('acme') is a perfectly good mock. It
simply has no page until the browser layer is attached.
The page changes without the engine
The markup is in templates/, the styles in
assets/, and the browser code is in the template
itself.
Neither has to know about the other
The engine does not import the UI, and the UI does not import a provider.
A provider that wants a checkout declares it, rather than reaching into the browser layer:
service.checkout = {
title: 'Acme (mock)',
find: (reference) => ({ reference, amount: '10.00', merchant: 'The shop' }),
onDone: (reference, outcome) => recordIt(reference, outcome),
}
The UI mounts it; the engine never looks at it.
No Dependencies
There are none — not at runtime, not in the tests, not in the lint. Node is the whole toolchain. This is not asceticism; it is the thing that makes the mocks easy to adopt.
- A project can depend on the package without an install step of its own.
- A contributor can add a mock without learning a framework.
- The container image has nothing in it to install, so it stays small and starts instantly.
The lint is the clearest example. There is no eslint in it;
scripts/lint.js parses every file with
node --check and checks the house style — no semicolons,
no trailing whitespace, a newline at the end. The footprint budget is
the same idea: scripts/footprint.js measures the running
mocks with node and ps.
The Promise That Is Checked
The README says the mocks are light. A promise nobody checks is a promise that erodes, so it is a budget, and it fails the build.
npm run footprint
mocks 78 in one process
memory 51 MB
idle CPU 0.2%
startup 352 ms
budgets: memory <= 120 MB, startup <= 5000 ms, idle CPU <= 1%
The budgets are deliberately loose. They catch a regression that adds a runtime — a dependency, a poller, a timer that never stops — not a difference between two machines.
The 16 Categories (78 Mocks)
The mocks are grouped by what they stand in for, and the grouping is part of the API.
| Category | Mocks | Count | Compose Profile |
|---|---|---|---|
payments | Stripe, PayPal, Square, Adyen, Paystack, Interswitch, Flutterwave, Monnify | 8 | payments |
social | Facebook, Instagram, X, Bluesky, Telegram, Reddit, LinkedIn, TikTok, YouTube | 9 | social |
messaging | Twilio, Termii, WhatsApp, FCM, OneSignal | 5 | messaging |
email | Resend, SendGrid, Mailchimp, Klaviyo, Postmark | 5 | email |
shipping | Shippo, EasyPost, FedEx, UPS, DHL | 5 | shipping |
marketplaces | Amazon SP-API, Shopify, eBay, Etsy, Walmart | 5 | marketplaces |
crm | HubSpot, Salesforce, Pipedrive, Attio | 4 | crm |
erp | Cin7, DEAR, TradeGecko, Katana | 4 | erp |
tax | Avalara, TaxJar, Vertex | 3 | tax |
pos | Square Terminal, Clover, Toast, Lightspeed | 4 | pos |
analytics | Segment, Mixpanel, Amplitude, RudderStack | 4 | analytics |
identity | YouVerify, SmileID, IdentityPass | 3 | identity |
accounting | Xero, QuickBooks, NetSuite, Sage | 4 | accounting |
ai | OpenAI | 1 | ai |
storage | S3 | 1 | storage |
dns | Cloudflare | 1 | dns |
The compose file uses the same names as profiles, so
--profile payments starts the payment mocks and nothing
else. A project should not pay for 78 containers to test one flow.
One Process, Many Mocks
stripe paystack flutterwave] PORT1[Port 4001
stripe] PORT2[Port 4005
paystack] PORT3[Port 4010
flutterwave] end CMD --> PORT1 CMD --> PORT2 CMD --> PORT3 PORT1 -.->|SIGTERM| STOP[graceful shutdown
all ports freed] PORT2 -.->|SIGTERM| STOP PORT3 -.->|SIGTERM| STOP
One Process, Many Mocks
api-mock-services start stripe paystack flutterwave starts
three servers in one process, on one port each. That is the difference
between one container and three, and between 51MB and 153MB.
It also means the mocks share a fate: one SIGTERM stops
all of them, and the ports are freed properly.
The Control Surface
/_control is the API the command line and the panel both
drive.
| Route | What it does |
|---|---|
POST /_control/outcome | Choose how the next payment goes |
POST /_control/fail | Make the next call fail — server, unauthorised, unavailable, timeout, network |
POST /_control/webhook | Set the webhook settings, and send it |
POST /_control/reset | Forget everything |
GET /_control/requests | Everything the mock was asked |
GET /_control/logs | The requests, as they happen (SSE) |
The panel is a view of it. The command line is a client of it. They cannot drift, because there is only one implementation.
The Rules a Mock Keeps
The real shape
The paths, the fields and the status codes are the provider's, so the code under test does not change when it is pointed at a mock.
The state is kept
What the service was asked, and what it decided, is on
service.state and service.requests.
The reference decides
A reference with success in it comes back successful,
one with failed in it comes back failed — so a test can
ask for either without a special flag.
No dependencies
Node's own server, so it runs anywhere.
The Specifications, Kept Current
The mocks are written by hand, but the shapes they answer with are the providers'. Those two things drift apart unless something keeps them together.
So the specifications are fetched from the providers' own repositories, on a schedule, and the difference is committed for a human to look at. The manifest says where each one comes from:
{
"specs": {
"twilio": {
"url": "https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/yaml/twilio_api_v2010.yaml",
"path": "specs/twilio_api_v2010.yaml"
},
"stripe": {
"url": "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.sdk.json",
"path": "specs/stripe_openapi.json",
"cache": true
}
}
}
scripts/update-specs.js reads that manifest and refreshes
what it points at. The Specs workflow runs it on Mondays
and commits what changed — so a provider that changes its API shows up
as a diff rather than as a broken mock three months later.
The specifications are not in the published package. They are for checking the mocks against, not for running them.
Deliberate Decisions, and Why
Not DNS Masquerading
Hijacking api.paystack.co needs a CA certificate
installed, rights to change /etc/hosts, and it leaks real
traffic for any domain the mock does not cover. The alternative is one
line with no certificate and nothing to clean up:
eval $(api-mock-services env)
Not a Go or Rust Rewrite
A native binary would be lighter and start faster. It would also mean a build step, a toolchain, and a contributor who cannot simply add a mock. The memory is already 51MB for 78 mocks, and it is measured. The shareability is worth more than the last 30MB.
Not Schema-Driven Everywhere
A specification describes a shape; it does not describe a state
machine. A payment that is created, then paid, then refunded cannot
be expressed in a .yaml, so those mocks are written as
code. For the services that are only read from, a route file is
enough — and createSpecMock fills the placeholders in
without a YAML parser and without a dependency.