Why these mocks exist.
Every project that talks to a payment gateway, an email provider, an accounting service, a DNS provider, a messaging service or an identity check needs something to talk to in a test. This is that something — one implementation, shared, instead of a copy in every repository.
Architecture at a Glance
src/harness.js] ROUTER[Route Matcher] STATE[State Manager] CONTROL[Control Surface
/_control/*] SHUTDOWN[Graceful Shutdown
SIGTERM/SIGINT] end subgraph "78 Provider Mocks (16 Categories)" direction TB PAYMENTS[Payments (8)
Stripe, PayPal, Square, Adyen,
Paystack, Interswitch,
Flutterwave, Monnify] SOCIAL[Social (9)
Facebook, Instagram, X,
Bluesky, Telegram, Reddit,
LinkedIn, TikTok, YouTube] MESSAGING[Messaging (5)
Twilio, Termii, WhatsApp,
FCM, OneSignal] EMAIL[Email (5)
Resend, SendGrid, Mailchimp,
Klaviyo, Postmark] SHIPPING[Shipping (5)
Shippo, EasyPost, FedEx,
UPS, DHL] MARKETPLACES[Marketplaces (5)
Amazon SP-API, Shopify,
eBay, Etsy, Walmart] CRM[CRM (4)
HubSpot, Salesforce,
Pipedrive, Attio] ERP[ERP/Inventory (4)
Cin7, DEAR, TradeGecko, Katana] TAX[Tax (3)
Avalara, TaxJar, Vertex] POS[POS Hardware (4)
Square Terminal, Clover,
Toast, Lightspeed] ANALYTICS[Analytics (4)
Segment, Mixpanel,
Amplitude, RudderStack] SOCIAL[Social (9)
Facebook, Instagram, X,
Bluesky, Telegram, Reddit,
LinkedIn, TikTok, YouTube] end TC -->|HTTP| PAYMENTS TC -.->|HTTP| SOCIAL 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 PAYMENTS -->|routes| ROUTER SOCIAL -.->|routes| ROUTER ROUTER -.->|matches| STATE ROUTER -.->|matches| CONTROL
System architecture: test code talks HTTP to mocks; the engine routes, records state, and exposes a control surface.
The Problem
The need is the same in every repository: a card payment, an identity check, an email, a DNS record, a text message, a model call. Most teams solve it the same way too — with a copy of somebody else's mock, kept in step by hand.
The copy drifts. It answers with shapes the real provider never returns, so the code under test has to change when it is pointed at the real thing. Or the team points the suite at the provider's own test environment, and the tests now depend on the network.
The answer here is a single shared implementation, kept to the provider's real paths, fields and status codes, light enough to start on a laptop and in a test process.
What It Replaces
gets out of sync] end subgraph "After: The API Mock Services Way" SINGLE[Single shared package
@bytesickle/api-mock-services] SYNC[Changes land once
every project gets them] end CP1 -.->|drifts| DRIFT CP2 -.->|drifts| DRIFT CP3 -.->|drifts| DRIFT SINGLE -.->|updates| SYNC
A provider's test environment
The provider's sandbox is somebody else's server. It needs credentials, and it is the spend a team wants to cut. The mocks run on the machine instead, so the suite does not depend on the network.
A copy of a mock in every repository
One implementation, shared. When a provider's shape changes, the change lands once, and every project gets it.
A JVM mock engine
A JVM, a compiled Go binary or a Python environment all add to the footprint before a single request is served. Node is already on the machine, because the project under test runs on it.
A container for every mock
78 mocks in one process cost 51MB. 78 containers cost 78 runtimes, and 78 things to start, stop and clean up.
What It Costs
Measured on a laptop, against the containers this replaces. The checked budget measures the whole set — 78 mocks in one process — at 51 MB.
Who It Is For
A team with a third-party flow to test
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.
A team whose suite must not depend on the network
A mock on the machine answers the same way every time. That is what stops a flaky test, and what keeps the suite fast.
A team that wants its gates to run on a laptop
The local test is the gate. make ci runs it first,
so nothing reaches a runner that has not been through the same tests
on this machine.
Three Ways to Use It
1. In a Test (Recommended)
The mock starts inside the test process. Nothing listens on a port, no container starts, and the mock stops when the test ends.
Basic Payment Test (Stripe)
import { startMock } from '@bytesickle/api-mock-services'
const stripe = await startMock('stripe')
// Point your app at the mock
process.env.STRIPE_API_BASE = `${stripe.url}/v1`
// Run your test
await myPaymentService.charge('cus_123', 1000)
// Assert what the mock saw
expect(stripe.last().path).toBe('/v1/refunds')
expect(stripe.state.refunds[0].payment_intent).toBe('pi_test_1')
await stripe.close()
Testing Failure Paths (Reference-Decides Pattern)
// Success case - reference contains "success"
const payment = await stripe.post('/v1/payment_intents', {
amount: 1000,
currency: 'usd',
reference: 'pi_success_123' // succeeds
})
expect(payment.json.status).toBe('succeeded')
// Failure case - reference contains "failed"
const failed = await stripe.post('/v1/payment_intents', {
amount: 1000,
currency: 'usd',
reference: 'pi_failed_456' // fails
})
expect(failed.json.status).toBe('requires_payment_method')
Inspecting State After Test
// Check all requests the mock received
const requests = stripe.requestsFor('POST', '/v1/payment_intents')
expect(requests).toHaveLength(1)
expect(requests[0].json.amount).toBe(1000)
// Check state
expect(stripe.state.intents.size).toBe(1)
2. As a Container
# Single mock
docker run --rm -p 4001:4001 api-mock-services stripe
# Multiple mocks in one process (one image, one process)
docker run --rm -p 4001:4001 -p 4005:4005 api-mock-services stripe paystack
# Using docker-compose with profiles
docker compose -f examples/docker-compose.yml --profile payments up -d
docker compose -f examples/docker-compose.yml --profile identity up -d
docker compose -f examples/docker-compose.yml --profile all up -d
Profile Categories
| Profile | Mocks Started | Ports |
|---|---|---|
payments | stripe, paypal, square, adyen, paystack, interswitch, flutterwave, monnify | 4001, 4028, 4029, 4030, 4005, 4006, 4010, 4011 |
social | facebook, instagram, x, bluesky, telegram, reddit, linkedin, tiktok, youtube | 4019-4027 |
messaging | twilio, termii, whatsapp, fcm, onesignal | 4008-4012, 4015, 4016 |
identity | youverify, smileid, identitypass | 4007, 4013, 4014 |
shipping | shippo, easypost, fedex, ups, dhl | 4031-4035 |
marketplaces | amazon-sp-api, shopify, ebay, etsy, walmart | 4036-4040 |
crm | hubspot, salesforce, pipedrive, attio | 4045-4048 |
erp | cin7, dear, tradegecko, katana | 4052-4055 |
tax | avalara, taxjar, vertex | 4056-4058 |
pos | square-terminal, clover, toast, lightspeed | 4059-4062 |
analytics | segment, mixpanel, amplitude, rudderstack | 4063-4066 |
all | all 78 mocks | 4001-4077 |
3. Over HTTP, From Any Language
The mocks answer over HTTP, so anything can use them — Go, Python, Ruby, Java, Rust, etc. Point the application at the URL and carry on.
# Start the stack
docker compose -f examples/docker-compose.yml --profile all up -d
# Point your application
PAYSTACK_API_URL=http://localhost:4005
FLUTTERWAVE_API_URL=http://localhost:4010/v3
TERMII_API_URL=http://localhost:4012
WHATSAPP_API_URL=http://localhost:4015
OPENAI_API_BASE=http://localhost:4017/v1
SEGMENT_API_URL=http://localhost:4063/v1
MIXPANEL_API_URL=http://localhost:4064
AMPLITUDE_API_URL=http://localhost:4065
RUDDERSTACK_API_URL=http://localhost:4066
Command Line Env Helper
# Prints env vars for all running mocks
eval $(api-mock-services env)
# Now your app can use
# process.env.STRIPE_API_BASE
# process.env.PAYSTACK_API_URL
# etc.
The Control Surface
Every mock exposes /_control for driving it from tests or the CLI:
| Route | Purpose | Example |
|---|---|---|
POST /_control/outcome | Set next payment outcome | { "outcome": "failed" } |
POST /_control/fail | Make next call fail | { "kind": "timeout", "times": 2 } |
POST /_control/webhook | Configure & send webhook | { "url": "...", "send": true } |
POST /_control/reset | Reset all state | {} |
GET /_control/requests | Inspect all requests | — |
GET /_control/logs | Live request stream (SSE) | — |
From the CLI
# Set next payment to fail
api-mock-services fail stripe timeout
# Set webhook and send
api-mock-services webhook stripe url=http://app:3000/webhook send=true
# Inspect requests
api-mock-services requests stripe
# Live log stream
api-mock-services logs stripe
Identity Endpoints
Every mock exposes two endpoints for self-identification:
| Endpoint | Returns |
|---|---|
GET /_mock | { kind: "mock", service: "stripe", real_service: false } |
Every response also includes the header x-mock-service-kind: mock.
Agents and scripts should check this first — if it's not a mock, stop.
OpenAPI Specs
Every mock serves its own OpenAPI 3.1 spec at /_openapi:
curl http://localhost:4001/_openapi | jq .paths
# Or the combined spec with all 78 mocks:
curl http://localhost:4001/_openapi | jq '.paths | keys | length'
# 180+ endpoints across 78 mocks
Generated from actual routes: npm run openapi -- --write
The Rules
These are not preferences. They are what keeps the engine light, and a contributor who breaks one of them breaks the promise in the first line of the README.
No dependencies
Not "few" — none. The engine runs on Node's own HTTP server. A dependency is a package to install, audit and keep out of the advisories.
In the test, not beside it
A test that needs a mock starts it in the test process, with
startMock(). Nothing listens on a port and the mock
stops when the test ends.
Idle means idle
A mock answers a request and then stops computing. Polling, watching and retrying are how a mock turns into a battery drain.
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.