Generate emulate seed configs for stateful API emulation. Wraps Vercel's emulate tool for GitHub, Vercel, Google OAuth, Slack, Apple Auth, Microsoft Entra, AWS, Okta, Clerk, Resend, Stripe, and MongoDB Atlas APIs — full state machines, not mocks. Use when setting up test environments, CI pipelines, integration tests, or offline development.
Generate emulate seed configs for stateful API emulation. Wraps Vercel's emulate tool for GitHub, Vercel, Google OAuth, Slack, Apple Auth, Microsoft Entra, AWS, Okta, Clerk, Resend, Stripe, and MongoDB Atlas APIs — full state machines, not mocks. Use when setting up test environments, CI pipelines, integration tests, or offline development.
Generate and manage seed configs for emulate (Apache-2.0) — Vercel Labs' stateful API emulation tool. Each category has individual rule files in rules/ loaded on-demand.
Paired agent: This skill pairs with the emulate-engineer subagent (subagent_type: "ork:emulate-engineer"). When a task involves generating a full emulate config from scratch, webhook HMAC setup, CI pipeline integration, or parallel-worker port isolation, spawn the agent rather than handling it inline — it has the full 13-emulator service-port matrix and seed-rules in context.
Not mocks. Emulate provides full state machines with cascading deletes, cursor pagination, webhook delivery, and HMAC signature verification. Create a PR via the API and it appears in GET /repos/:owner/:repo/pulls. Delete a repo and its issues, PRs, and webhooks cascade-delete.
New in 2026-04 (emulate 0.4.x)
Modular @emulators/* packages — each service is its own package (@emulators/github, @emulators/stripe, etc.); top-level emulate re-exports createEmulator and the CLI.
4 new services (12 total): mongoatlas:4007, okta:4008, resend:4009, stripe:4010 with drop-in seed YAML blocks.
Resend local inbox — GET http://localhost:4009/inbox returns captured emails for assertions without hitting a real provider.
Stripe hosted checkout — real session redirect flow + checkout.session.completed/expired webhook delivery, suitable for E2E payment tests.
MongoDB Atlas — Admin API v2 (projects/clusters/DB users) + Data API v1 with full CRUD + aggregate.
Okta OIDC — full discovery, JWKS, authorize/token/userinfo/revoke/introspect plus Users/Groups/Apps CRUD.
@emulators/adapter-next — catch-all Next.js route handler runs emulators on the same origin as the app; fixes OAuth callback URL drift on Vercel preview deploys.
Auto-Discovery (M125 #4)
scripts/auto-discover.sh scans the project's package.json, matches deps against references/dep-to-emulator-map.json, and either reports the matches or writes emulate.config.yaml. Three modes:
Mode
Behavior
(default)
Report matched deps + emulator union on stderr; do not write
--json
Emit machine-readable JSON instead of human report
--apply
Write emulate.config.yaml (refuses to overwrite without --force)
Multi-emulator deps default to all reasonable providers; the user prunes the YAML afterwards. Unmapped deps are silently skipped — extending coverage is a docs PR (edit references/dep-to-emulator-map.json), not a code change.
/ork:dev reads the resulting emulate.config.yaml at boot — see src/skills/dev/scripts/boot.sh.
# Install (packages published under @emulators/* scope)
npm install --save-dev emulate# Start all services
npx emulate# Start specific services with seed data
npx emulate --service github,stripe --seed ./emulate.config.yaml
# Generate a starter config
npx emulate init --service github
Services (0.9.0 — 14 emulators)
New across releases:
0.5.0 — added Clerk, MongoDB Atlas, Stripe, Resend, and Okta emulators; portless integration (embedded emulators without dedicated ports); Google OAuth hd claim support; Stripe Checkout + Resend magic link examples; AWS S3 emulator now matches the official SDK wire format.
See references/api-coverage.md for full endpoint lists.
Next.js Adapter (0.4+) — @emulators/adapter-next
Runs emulators on the same origin as your Next.js app via a catch-all route handler. Fixes the OAuth callback URL drift problem on Vercel preview deploys — no more http://localhost:4001 redirect mismatches.
See rules/seed-config.md for full schema and best practices.
Programmatic SDK
Service packages live under the @emulators/* scope (e.g., @emulators/github, @emulators/stripe). The programmatic API (createEmulator) is exported from the top-level emulate package.
import { createEmulator } from'emulate'const github = awaitcreateEmulator({ service: 'github', port: 4001 })
// github.url -> 'http://localhost:4001'// State is real — create a PR and it appears in the listconst res = awaitfetch(`${github.url}/repos/org/repo/pulls`, {
method: 'POST',
headers: { Authorization: 'Bearer dev_token' },
body: JSON.stringify({ title: 'Test PR', head: 'feature', base: 'main' })
})
const prs = awaitfetch(`${github.url}/repos/org/repo/pulls`)
// -> includes the PR we just created// Cleanup
github.reset() // Synchronous state wipeawait github.close() // Shut down server
seed here is a parsed object, not a path. Only the CLI --seed flag takes a filename.
For multi-service setup, lifecycle hooks, and the Vitest/Jest wiring, see
references/upstream.md. For the ork-side corrections to that API, see
references/ork-delta.md.
Webhook Delivery
Emulate delivers real webhooks with HMAC-SHA256 signatures when state changes:
Testing code that calls GitHub, Vercel, Google, Slack, Apple, Entra, AWS, Okta, Resend, Stripe, MongoDB Atlas, Clerk, or Linear
You need state persistence across multiple API calls in a test
You want webhook delivery with real HMAC signatures (GitHub, Stripe)
You need cascading side-effects (delete repo -> PRs cascade-delete)
You need to assert on sent emails without hitting a real provider (Resend local /inbox)
You need hosted Stripe checkout sessions with real redirect flow in tests
Use MSW/Nock when:
Mocking arbitrary HTTP APIs not covered by emulate
You need in-browser interception (MSW)
Tests only need single request/response pairs
Upstream coverage (do not restate)
This skill is a wrap plus our delta. emulate ships its own per-service reference docs;
copying them here only produces something that goes stale on the next release. If a
topic below comes up, read the first-party source, not a paraphrase.
What stays ours:references/ork-delta.md (the corrections and house conventions that
are not in any vendor doc), references/cli-reference.md, references/api-coverage.md,
references/dep-to-emulator-map.json, scripts/auto-discover.sh, and everything in rules/.
Read references/ork-delta.md before copying any snippet out of a vendor doc. It records
the two API facts vendor prose does not spell out (the exported factory is createEmulator,
and seed in the programmatic options is an object rather than a path) plus the
*_API_BASE env-var convention this repo uses instead of the vendor's *_EMULATOR_URL.
Related Skills
testing-integration — Integration test patterns (emulate as first choice for API tests)
testing-e2e — End-to-end test patterns with emulated backends
testing-unit — Unit test patterns (use emulate for API-dependent units)
