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:

graph TB subgraph "User Code" TC[Test Code / App] CLI[CLI / Panel] end subgraph "API Mock Services Engine" direction TB HARNESS[Harness Core
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.

graph LR subgraph "Engine (harness.js)" ROUTE[Route Registration
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.

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%
78mocks in one process
51 MBof memory
0.2%CPU while idle
352 msto start

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.

CategoryMocksCountCompose Profile
paymentsStripe, PayPal, Square, Adyen, Paystack, Interswitch, Flutterwave, Monnify8payments
socialFacebook, Instagram, X, Bluesky, Telegram, Reddit, LinkedIn, TikTok, YouTube9social
messagingTwilio, Termii, WhatsApp, FCM, OneSignal5messaging
emailResend, SendGrid, Mailchimp, Klaviyo, Postmark5email
shippingShippo, EasyPost, FedEx, UPS, DHL5shipping
marketplacesAmazon SP-API, Shopify, eBay, Etsy, Walmart5marketplaces
crmHubSpot, Salesforce, Pipedrive, Attio4crm
erpCin7, DEAR, TradeGecko, Katana4erp
taxAvalara, TaxJar, Vertex3tax
posSquare Terminal, Clover, Toast, Lightspeed4pos
analyticsSegment, Mixpanel, Amplitude, RudderStack4analytics
identityYouVerify, SmileID, IdentityPass3identity
accountingXero, QuickBooks, NetSuite, Sage4accounting
aiOpenAI1ai
storageS31storage
dnsCloudflare1dns

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

graph LR subgraph "Single Process (51 MB)" direction TB CMD[api-mock-services start
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.

RouteWhat it does
POST /_control/outcomeChoose how the next payment goes
POST /_control/failMake the next call fail — server, unauthorised, unavailable, timeout, network
POST /_control/webhookSet the webhook settings, and send it
POST /_control/resetForget everything
GET /_control/requestsEverything the mock was asked
GET /_control/logsThe 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.

← Overview CI gates →