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

graph TB subgraph "Your Test Suite / Application" TC[Test Code / App Code] end subgraph "API Mock Services (1 process, 51 MB, 78 mocks)" HARNESS[Harness Core
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

graph LR subgraph "Before: The Old Way" CP1[Copy of mock in Repo A] CP2[Copy of mock in Repo B] CP3[Copy of mock in Repo C] DRIFT[Drift: each copy
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

graph LR subgraph "API Mock Services (1 process)" P1[1 process] M1[51 MB] C1[0.2% CPU] T1[352 ms startup] end subgraph "4 Containers (typical)" P4[4 processes] M4[250 MB] C4[7.9% CPU] T4[20+ s startup] end P1 -.->|vs| P4 M1 -.->|vs| M4 C1 -.->|vs| C4 T1 -.->|vs| T4

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

ProfileMocks StartedPorts
paymentsstripe, paypal, square, adyen, paystack, interswitch, flutterwave, monnify4001, 4028, 4029, 4030, 4005, 4006, 4010, 4011
socialfacebook, instagram, x, bluesky, telegram, reddit, linkedin, tiktok, youtube4019-4027
messagingtwilio, termii, whatsapp, fcm, onesignal4008-4012, 4015, 4016
identityyouverify, smileid, identitypass4007, 4013, 4014
shippingshippo, easypost, fedex, ups, dhl4031-4035
marketplacesamazon-sp-api, shopify, ebay, etsy, walmart4036-4040
crmhubspot, salesforce, pipedrive, attio4045-4048
erpcin7, dear, tradegecko, katana4052-4055
taxavalara, taxjar, vertex4056-4058
possquare-terminal, clover, toast, lightspeed4059-4062
analyticssegment, mixpanel, amplitude, rudderstack4063-4066
allall 78 mocks4001-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:

RoutePurposeExample
POST /_control/outcomeSet next payment outcome{ "outcome": "failed" }
POST /_control/failMake next call fail{ "kind": "timeout", "times": 2 }
POST /_control/webhookConfigure & send webhook{ "url": "...", "send": true }
POST /_control/resetReset all state{}
GET /_control/requestsInspect all requests—
GET /_control/logsLive 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:

EndpointReturns
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.

← Home Architecture →