Docs
Guides for using, testing and contributing to Mockingbird. Each page is a file in docs/, the same markdown GitHub renders, so the two never differ. Each service's own guide is its README, on itsservice page.
Featured emulators
Explore the guides, coverage, and live playgrounds for these four emulators.
Amazon S3
StorageStateful S3 emulator that answers exactly as MinIO does: every bucket, object, multipart, versioning, object-lock, policy and auth API, verified against recorded MinIO transcripts.
Junction
Health & labsStateful emulator of the Junction (Vital) user API driven by its OpenAPI contract and verified by differential property tests against the Junction sandbox.
PostgreSQL
DatabasesPure TypeScript in-memory PostgreSQL implementation with zero WASM/native dependencies
Stripe
PaymentsStateful emulator of the Stripe API (accounts by key, customers, payments, subscriptions that renew, pause, resume and cancel, invoices, checkout with a hosted page, a hosted customer portal, 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.
Admin controls
Every Mockingbird HTTP emulator answers the same controls: isolate state by key, reset it, snapshot and restore it, move the clock, inject faults, latency and timeouts, and replay all of it from a seed. They are the same on every emulator, and the same whether you set them at boot, call the admin API, or send a request header.
Guides
- Getting startedInstall a Mockingbird emulator, create a runtime, and send vendor-compatible requests. Each service is a self-contained TypeScript package with its own coverage matrix and integration guide.
- Admin controlsEvery Mockingbird HTTP emulator answers the same controls: isolate state by key, reset it, snapshot and restore it, move the clock, inject faults, latency and timeouts, and replay all of it from a seed. They are the same on every emulator, and the same whether you set them at boot, call the admin API, or send a request header.
- Why MockingbirdMockingbird gives applications local, stateful emulators for the vendor APIs and databases they depend on. Run integrations inside your process, control the state and clock, and inspect exactly which vendor operations each emulator supports.
- Testing and parityHow every emulator is proven to behave like its vendor: differential contracts, property-based walks, and live parity against real sandboxes.
- Authoring a Mockingbird serviceHow to add a vendor emulator to this repo. The reference implementation is [packages/service/rxvortex](../packages/service/rxvortex): copy its layout and patterns.
- Developing MockingbirdWorking on this repo: requirements, how the packages are layered, and the quality gates every change passes.
- DesignMockingbird is a developer toolkit for local API and database emulation. Its documentation uses neutral surfaces, clear navigation, technical examples, and explicit coverage. The project name stays Mockingbird; describe each service as an **emulator**.
- Reporting issuesHow coding agents in other projects file a GitHub issue when an emulator diverges from its oracle, lacks a feature they call, or breaks, or when they need a service emulated that the catalog does not have yet. Agents in this repository pick the issues up and resolve them.
- ReleasingHow packages get from main to npm using Trusted Publishing, without a stored npm token.
- Secrets runbookWhere every credential lives, who needs it, and how to run live parity without ever holding a sandbox key: GitHub Actions repo secrets are the only secret store.
- AWS implementation and oracle coverageThe LocalStack expansion is work in progress. No new LocalStack or live AWS oracle run was performed during integration. Implemented services have local transport and state tests; scaffold packages explicitly reject vendor operations. bun run parity fails when no scenario exists or the local oracle is unavailable.
- Emulate coverage auditMockingbird covers the 14 public providers in [Emulate](https://emulate.dev/) and [vercel-labs/emulate](https://github.com/vercel-labs/emulate). The comparison target is the npm package emulate@0.12.1, pinned in packages/parity/package-oracle/package.json and bun.lock. Licensed handler sources are pinned to commit c77cb73e7ab525c5260dd36c04c91a54a23e7e75; packages/http/provider/port.json records every source path and SHA-256 digest.
- FleetsOne service CLI can supervise installed HTTP emulators, PostgreSQL wire servers and Redis RESP servers. Every listener starts before readiness is published; a boot failure names the service, closes listeners that already started, and exits nonzero. SIGINT/SIGTERM closes the whole fleet.
- Infrastructure and orchestration emulatorsThis document defines the boundaries and planned evidence for the Docker Engine, Hermes peer-run, and GitHub REST packages.