Mock the APIs you depend on, with the behavior they really have.
Mockingbird is a catalog of stateful test doubles for third-party HTTP APIs and SQL databases. Each one speaks the vendor's real surface, keeps state, and runs in-process.
npm install -D @crvouga/mockingbird-service-stripepnpm add -D @crvouga/mockingbird-service-stripeyarn add -D @crvouga/mockingbird-service-stripebun add -d @crvouga/mockingbird-service-stripeimport { createRuntime } from "@crvouga/mockingbird-service-stripe"
const stripe = createRuntime()
const res = await stripe.fetch(
new Request("https://api.stripe.com/v1/customers", {
method: "POST",
headers: {
authorization: "Bearer sk_test_mockingbird",
"content-type": "application/x-www-form-urlencoded",
},
body: "email=ada@example.com",
}),
)
console.log(res.status) // 200
const customer = await res.json() // { id: "cus_…", object: "customer", email: "ada@example.com", … }
// State persists: the customer is there when you list customers.
const list = await stripe.fetch(
new Request("https://api.stripe.com/v1/customers", {
headers: { authorization: "Bearer sk_test_mockingbird" },
}),
)
console.log((await list.json()).data[0].id === customer.id) // trueThe README's quick start. The build runs it against the published package.
Start with the 5 that are ready.
These are complete and kept stable. The other 36 are marked work in progress: usable in a suite, but their operations and shapes can still change.
Junction
Health & labsStateful mock of the Junction (Vital) user API driven by its OpenAPI contract and verified by differential property tests against the Junction sandbox.
Medplum
Health & labsStateful, portable mock of the self-hosted Medplum server (FHIR R4 REST, OAuth2 and admin API) that runs anywhere JavaScript runs, proven at parity with a real self-hosted Medplum used as the oracle.
PostgreSQL
DatabasesPure TypeScript in-memory PostgreSQL implementation with zero WASM/native dependencies
SQLite
DatabasesPure TypeScript in-memory SQLite implementation with zero WASM/native dependencies
Stripe
PaymentsStateful mock of the Stripe API (accounts by key, customers, payments, subscriptions with renewals, invoices, checkout with a hosted page, a Stripe.js stand-in, signed webhooks) at API versions 2024-06-20 and 2025-02-24.acacia, verified by differential property tests against Stripe test mode.
Test doubles that don't drift from the vendor.
Hand-written stubs return whatever you guessed. Mockingbird mocks are driven by the vendor's contract and checked against it.
The vendor's real surface
Each mock answers the provider's own paths, headers, status codes and error envelopes through fetch(Request) → Response. Point the official SDK at it.
State that behaves
Records persist in an in-memory SQL engine. Created customers can be listed, orders move through their lifecycle, webhooks fire, and reset or snapshot takes one call.
Checked against the real thing
Random walks generated from each vendored OpenAPI contract run against two mock instances in CI, and against the live sandbox when credentials exist.
No network, no waiting
Everything runs in your test process. No sandbox keys, rate limits, shared test accounts or flaky round trips.
Runs anywhere JavaScript runs
Most mocks are portable: Node, Bun, browsers and Workers. The docs site's playgrounds run the published packages in your browser tab.
One contract for every service
Every HTTP mock shares /health, /__admin reset, snapshots, clock control, fault injection, request journals and per-namespace isolation.
Payments, health, messaging, AI, and more.
Every category links to a filtered view of the catalog.
Payments
2Charges, subscriptions, checkout and HSA/FSA billing.
Health & labs
11EHRs, lab ordering, diagnostics, telehealth, nutrition.
Pharmacy
5eRx, compounding pharmacies and fulfilment.
Communication
6Email, SMS, chat, video and inbox testing.
Marketing
3Customer data, campaigns and referral tracking.
AI & speech
3LLM runtimes, retrieval, speech synthesis and transcription.
Observability
2Product analytics, feature flags and telemetry.
Productivity
4Calendars, issue trackers, CMS and surveys.
Maps & logistics
2Places, geocoding and shipment tracking.
Identity
1Identity verification and KYC.
Databases
2In-memory SQL engines with real dialect semantics.
One contract for every HTTP service.
Every HTTP service ships an in-process fetch, a Node server and a CLI, and all answer the same control surface, so a stack learns it once.
| Surface | What it gives you |
|---|---|
createRuntime() · createServer() (./server) · mockingbird-<service> serve | The mock as one runtime-neutral fetch, or a listening server from Node or the CLI |
GET /health | Unauthenticated readiness probe, outside the vendor's auth gate |
/__admin/* (x-mockingbird-admin-key optional) | Reset, snapshot and restore, clock control, fault injection, a request journal, metrics with unmatched-route counts, plus service-specific routes |
x-mockingbird-namespace | Per-request isolation: parallel workers share one process without sharing data |
--seed, clock control | Seeded randomness and an injectable clock, so a run replays exactly |
--log json | One structured line per request: operation id, status, duration, namespace, fault |
mockingbird.json names services by their package suffix and takes each one's serve flags; any installed service's CLI can serve all of them. The database engines are not HTTP APIs, so they are outside this contract.
Docs an agent can read, generated from the code.
Every service README doubles as its integration guide and ships inside the npm tarball (node_modules/<package>/README.md). llms.txt indexes them by tier, and the docs site publishes the same content as markdown and JSON, rebuilt from the packages on every build. When a mock diverges from the real API, lacks a feature you call, or the vendor you need is not in the catalog, file an issue: the filing guide gives the title format, templates and the behavior spec for feature and service requests.