Upstream version reference: emulate 0.12.0 (2026-09-30).
Emulate Seed Configs
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:
mongoatlas, okta, resend, stripe, with drop-in seed YAML blocks (current default ports: see the services table below).
- Resend local inbox —
GET http://localhost:4008/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.
- Entra / Apple / Slack expansions (v0.4.0) — PKCE + refresh rotation (Entra), RS256 JWKS (Apple), OAuth v2 consent UI (Slack).
@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) |
$ bash "${CLAUDE_SKILL_DIR}/scripts/auto-discover.sh"
emulate-seed --auto — scanning /path/to/package.json
Detected:
@octokit/rest → github · Any GitHub API client
next-auth → google-oauth, apple-auth, microsoft-entra · Default OAuth providers
stripe → stripe
@vercel/blob → aws · @vercel/blob is S3-compatible
Union: apple-auth, aws, github, google-oauth, microsoft-entra, stripe
$ bash "${CLAUDE_SKILL_DIR}/scripts/auto-discover.sh" --apply
…
✓ Wrote /path/to/emulate.config.yaml with 6 service(s)
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.
dev reads the resulting emulate.config.yaml at boot — see src/skills/dev/scripts/boot.sh.
Quick Reference
| Category |
Rules |
Impact |
When to Use |
| Seed Config |
1 |
HIGH |
Setting up emulate.config.yaml for test environments |
| Service Selection |
1 |
MEDIUM |
Choosing GitHub/Vercel/Google for your tests |
| Webhook Setup |
1 |
MEDIUM |
Testing webhook delivery with HMAC verification |
| Parallel CI |
1 |
HIGH |
Running tests in parallel without port collisions |
| Auth Tokens |
1 |
MEDIUM |
Seeding tokens mapped to emulated users |
Total: 5 rules across 5 categories
Quick Start
# 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.10.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.
- 0.6.0 — expanded Slack (OAuth v2 consent UI, conversations/reactions).
- 0.6.1 — Vercel Blob store.
- 0.7.0 — added Linear (13th provider): stateful orgs/teams/issues/cycles + webhooks.
- 0.8.0 — added Twilio (14th provider): accounts, phone numbers, messages, calls, conversations, messaging services, Verify flows, and simulator endpoints, with a Next.js SMS-verification example.
- 0.9.0 — added a Nuxt emulator adapter (alongside the Next.js adapter); provider count unchanged.
- 0.10.0 — stateful GitHub repository contents and commit history (
GET /repos/:owner/:repo/readme, GET/PUT/DELETE /repos/:owner/:repo/contents/:path where writes produce real commits, GET /repos/:owner/:repo/commits, and GET /repositories/:id by numeric ID); a readonly generatedSecrets array on the Emulator object with a new exported GeneratedSecret type; GitHub App JWT verification now accepts PKCS#8 as well as PKCS#1 keys. Provider count unchanged.
All backwards-compatible, with one behaviour change worth knowing: 0.10.0 switched
Stripe webhook deliveries to Stripe's own Stripe-Signature header format. Upstream
files it under bug fixes rather than breaking changes, but a test asserting the old
GitHub-style sha256= header on a Stripe delivery will now fail. See Webhook Delivery
below for both formats.
| Service |
Default Port |
Coverage |
| Vercel |
:4000 |
Projects, deployments, domains, env vars, teams |
| GitHub |
:4001 |
Repos, PRs, issues, comments, reviews, Actions, webhooks, orgs, teams |
| Google OAuth |
:4002 |
OAuth 2.0 authorize, token exchange, userinfo |
| Slack |
:4003 |
Chat, conversations, users, reactions, OAuth v2 with consent UI |
| Apple Auth |
:4004 |
Sign in with Apple — OIDC discovery, JWKS (RS256), auth flow, token exchange |
| Microsoft Entra |
:4005 |
OAuth 2.0/OIDC v2.0, authorization code + PKCE, refresh token rotation, v1 token endpoint, Graph /users/{id} |
| Okta (0.4+) |
:4006 |
OIDC discovery, JWKS, authorize/token/userinfo/revoke/introspect, Users/Groups/Apps CRUD |
| AWS |
:4007 |
S3 buckets, SQS queues, IAM users/roles, STS identity |
| Resend (0.4+) |
:4008 |
Send + batch (100/req), list/retrieve/cancel, domains, API keys, audiences, contacts, local inbox (GET /inbox) |
| Stripe (0.4+) |
:4009 |
Customers, payment methods, customer sessions, payment intents, charges, products, prices, hosted checkout session w/ webhook delivery |
| MongoDB Atlas (0.4+) |
:4010 |
Admin API v2 (projects, clusters, DB users) + Data API v1 (full CRUD + aggregate) |
| Clerk (0.5+) |
:4011 |
Users, sessions, organizations |
| Linear (0.7+) |
:4012 |
Orgs, teams, issues, cycles, webhooks |
| Twilio (0.8+) |
:4013 |
Accounts, phone numbers, messages, calls, conversations, messaging services, Verify flows, simulator endpoints |
Default ports are 4000 plus each service's position in emulate's service list (0.12.0), so this
table is the one place ports are written down; tests/skills/structure/test-emulate-ports.mjs
checks it, its references and the emulate-engineer agent against that order.
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.
// next.config.js
const { withEmulate } = require('@emulators/adapter-next')
module.exports = withEmulate({ /* your next config */ })
// app/api/[...emulate]/route.ts
import { createEmulateHandler } from '@emulators/adapter-next'
export const { GET, POST } = createEmulateHandler({
services: ['github', 'stripe', 'resend'],
persistence: { /* load(), save() or built-in filePersistence */ },
})
Seed Config Structure
A seed config pre-populates the emulator with tokens, users, repos, and projects so tests start from a known state.
# emulate.config.yaml
tokens:
dev_token:
login: yonatangross
scopes: [repo, workflow, admin:org]
ci_token:
login: ci-bot
scopes: [repo]
github:
users:
- login: yonatangross
name: Yonatan Gross
- login: ci-bot
name: CI Bot
repos:
- owner: yonatangross
name: my-project
private: false
default_branch: main
topics: [typescript, testing]
vercel:
users:
- username: yonatangross
email: yonaigross@gmail.com
projects:
- name: my-docs
framework: next
# NEW in 0.4.x — drop-in seed blocks
okta:
users:
- login: alice@example.com
firstName: Alice
lastName: Smith
groups: [{ name: Everyone }, { name: Admins }]
apps: [{ name: My Web App }]
authorization_servers:
- name: default
audiences: ["api://default"]
resend:
domains: [{ name: example.com }]
api_keys: [{ name: default }]
# In tests: GET http://localhost:4008/inbox to assert captured emails
stripe:
customers:
- name: Test Customer
email: customer@example.com
products: [{ name: Pro Plan }, { name: Starter Plan }]
prices:
- { product: Pro Plan, unit_amount: 4900, currency: usd, recurring: { interval: month } }
- { product: Starter Plan, unit_amount: 1900, currency: usd, recurring: { interval: month } }
# Webhook delivery fires on checkout.session.completed / expired
mongoatlas:
projects: [{ name: my-project }]
clusters: [{ project: my-project, name: my-cluster }]
database_users: [{ project: my-project, username: app-user }]
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 = await createEmulator({ service: 'github', port: 4001 })
// github.url -> 'http://localhost:4001'
// State is real — create a PR and it appears in the list
const res = await fetch(`${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 = await fetch(`${github.url}/repos/org/repo/pulls`)
// -> includes the PR we just created
// Auto-generated credentials (0.10.0+): readonly GeneratedSecret[], each
// { service, kind, id, label, value }. A GitHub App emulator, for example,
// generates its own RSA key rather than making you supply one.
github.generatedSecrets
// Cleanup
github.reset() // Synchronous state wipe
await 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. The
signature FORMAT is per-provider, so one generic verifier does not cover every service.
GitHub-format headers remain the default; Stripe has used its own format since 0.10.0.
import crypto from 'crypto'
// GitHub format (the default for most services): sha256=<hmac over the raw body>
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex')
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}
// Stripe format, as of emulate 0.10.0: Stripe-Signature: t=<timestamp>,v1=<hmac>,
// where the HMAC covers `<timestamp>.<raw body>`, NOT the body alone. Verifying a
// Stripe delivery with the GitHub helper above fails on both counts.
function verifyStripeWebhook(rawBody: string, header: string, secret: string): boolean {
const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')))
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex')
return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
}
See rules/webhook-setup.md for webhook receiver patterns.
CI Integration
# .github/workflows/test.yml
jobs:
test:
steps:
- uses: actions/checkout@v4
- name: Start emulate
run: npx emulate --service github --seed .emulate/ci.yaml &
- name: Wait for emulate
run: sleep 2
- name: Run tests
run: npm test
env:
GITHUB_API_BASE: http://localhost:4001
VERCEL_API_BASE: http://localhost:4000
Parallel Test Execution
Each test worker gets its own port to avoid race conditions:
// vitest.config.ts
const workerPort = 4001 + parseInt(process.env.VITEST_WORKER_ID || '0')
See rules/parallel-ci.md for full parallel isolation patterns.
Decision Matrix
| Tool |
When to Use |
Stateful? |
Platforms |
| emulate (FIRST CHOICE) |
GitHub/Vercel/Google/Slack/Apple/Entra/AWS/Okta/Resend/Stripe/MongoDB/Clerk/Linear testing |
YES |
All 13 services |
| Pact |
Contract verification between services |
No |
Any |
| MSW |
In-browser/Node HTTP mocking |
No |
Any |
| Nock |
Node.js HTTP intercept |
No |
Any |
| WireMock |
HTTP stub server |
Partial |
Any |
Use emulate when:
- 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.
| Topic |
First-party source |
Programmatic API (createEmulator, url, reset(), close()), Vitest/Jest wiring, config auto-detection order, token fallback |
references/upstream.md (synced from vercel-labs/emulate, skills/emulate/SKILL.md) |
| GitHub endpoint recipes, GitHub App JWT seeding, Octokit and Auth.js base-URL wiring, GitHub OAuth flow |
https://github.com/vercel-labs/emulate/blob/main/skills/github/SKILL.md |
Google OIDC discovery, JWKS, authorize/token/userinfo/revoke, PKCE, google-auth-library, Passport, openid-client |
https://github.com/vercel-labs/emulate/blob/main/skills/google/SKILL.md |
| Vercel endpoint recipes, cursor pagination, team scoping, integration OAuth flow |
https://github.com/vercel-labs/emulate/blob/main/skills/vercel/SKILL.md |
| Every other emulator (Slack, Apple, Entra, AWS, Okta, Resend, Stripe, MongoDB Atlas, Clerk, Linear, Twilio) |
https://github.com/vercel-labs/emulate/tree/main/skills |
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)
security-patterns — Auth token patterns (emulate token seeding)
CLI Reference
See references/cli-reference.md for all CLI flags and commands.
1---2name: emulate-seed3compatibility: "Claude Code 2.1.277+"4description: "Seed configs for Vercel emulate: stateful GitHub, Vercel, Google, Slack, Stripe, AWS and more, not mocks. Use when setting up test environments, CI or offline development."5user-invocable: false6disable-model-invocation: false7context: inherit8metadata:9 source: https://skillmd.com/skills/yonatangross/emulate-seed10 category: testing11 upstream-package: emulate12 upstream-version-tested: "0.12.0"13 version: "1.3.0"14 author: "OrchestKit"15 complexity: "medium"16 tags: "emulate, testing, api-emulation, github, vercel, google, stripe, resend, okta, clerk, mongodb, seed, ci, stateful-testing"17---1819Upstream version reference: `emulate` 0.12.0 (2026-09-30).2021# Emulate Seed Configs2223Generate and manage seed configs for [emulate](https://github.com/vercel-labs/emulate) (Apache-2.0) — Vercel Labs' stateful API emulation tool. Each category has individual rule files in `rules/` loaded on-demand.2425> **Paired agent:** This skill pairs with the [`emulate-engineer`](../../agents/emulate-engineer.md) 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.2627**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.2829## New in 2026-04 (emulate 0.4.x)3031- **Modular `@emulators/*` packages** — each service is its own package (`@emulators/github`, `@emulators/stripe`, etc.); top-level `emulate` re-exports `createEmulator` and the CLI.32- **4 new services**: `mongoatlas`, `okta`, `resend`, `stripe`, with drop-in seed YAML blocks (current default ports: see the services table below).33- **Resend local inbox** — `GET http://localhost:4008/inbox` returns captured emails for assertions without hitting a real provider.34- **Stripe hosted checkout** — real session redirect flow + `checkout.session.completed`/`expired` webhook delivery, suitable for E2E payment tests.35- **MongoDB Atlas** — Admin API v2 (projects/clusters/DB users) + Data API v1 with full CRUD + aggregate.36- **Okta OIDC** — full discovery, JWKS, `authorize/token/userinfo/revoke/introspect` plus Users/Groups/Apps CRUD.37- **Entra / Apple / Slack expansions (v0.4.0)** — PKCE + refresh rotation (Entra), RS256 JWKS (Apple), OAuth v2 consent UI (Slack).38- **`@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.3940## Auto-Discovery (M125 #4)4142`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:4344| Mode | Behavior |45|---|---|46| (default) | Report matched deps + emulator union on stderr; do not write |47| `--json` | Emit machine-readable JSON instead of human report |48| `--apply` | Write `emulate.config.yaml` (refuses to overwrite without `--force`) |4950```bash51$ bash "${CLAUDE_SKILL_DIR}/scripts/auto-discover.sh"52emulate-seed --auto — scanning /path/to/package.json5354Detected:55 @octokit/rest → github · Any GitHub API client56 next-auth → google-oauth, apple-auth, microsoft-entra · Default OAuth providers57 stripe → stripe58 @vercel/blob → aws · @vercel/blob is S3-compatible5960Union: apple-auth, aws, github, google-oauth, microsoft-entra, stripe6162$ bash "${CLAUDE_SKILL_DIR}/scripts/auto-discover.sh" --apply63…64✓ Wrote /path/to/emulate.config.yaml with 6 service(s)65```6667Multi-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.6869`dev` reads the resulting `emulate.config.yaml` at boot — see `src/skills/dev/scripts/boot.sh`.7071## Quick Reference7273| Category | Rules | Impact | When to Use |74|----------|-------|--------|-------------|75| [Seed Config](#seed-config) | 1 | HIGH | Setting up emulate.config.yaml for test environments |76| [Service Selection](#service-selection) | 1 | MEDIUM | Choosing GitHub/Vercel/Google for your tests |77| [Webhook Setup](#webhook-setup) | 1 | MEDIUM | Testing webhook delivery with HMAC verification |78| [Parallel CI](#parallel-ci) | 1 | HIGH | Running tests in parallel without port collisions |79| [Auth Tokens](#auth-tokens) | 1 | MEDIUM | Seeding tokens mapped to emulated users |8081**Total: 5 rules across 5 categories**8283## Quick Start8485```bash86# Install (packages published under @emulators/* scope)87npm install --save-dev emulate8889# Start all services90npx emulate9192# Start specific services with seed data93npx emulate --service github,stripe --seed ./emulate.config.yaml9495# Generate a starter config96npx emulate init --service github97```9899## Services (0.10.0 — 14 emulators)100101> **New across releases:**102> - **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.103> - **0.6.0** — expanded Slack (OAuth v2 consent UI, conversations/reactions).104> - **0.6.1** — Vercel Blob store.105> - **0.7.0** — added Linear (13th provider): stateful orgs/teams/issues/cycles + webhooks.106> - **0.8.0** — added Twilio (14th provider): accounts, phone numbers, messages, calls, conversations, messaging services, Verify flows, and simulator endpoints, with a Next.js SMS-verification example.107> - **0.9.0** — added a Nuxt emulator adapter (alongside the Next.js adapter); provider count unchanged.108> - **0.10.0** — stateful GitHub repository contents and commit history (`GET /repos/:owner/:repo/readme`, `GET`/`PUT`/`DELETE /repos/:owner/:repo/contents/:path` where writes produce real commits, `GET /repos/:owner/:repo/commits`, and `GET /repositories/:id` by numeric ID); a readonly `generatedSecrets` array on the Emulator object with a new exported `GeneratedSecret` type; GitHub App JWT verification now accepts PKCS#8 as well as PKCS#1 keys. Provider count unchanged.109>110> All backwards-compatible, with one behaviour change worth knowing: 0.10.0 switched111> Stripe webhook deliveries to Stripe's own `Stripe-Signature` header format. Upstream112> files it under bug fixes rather than breaking changes, but a test asserting the old113> GitHub-style `sha256=` header on a Stripe delivery will now fail. See Webhook Delivery114> below for both formats.115116| Service | Default Port | Coverage |117|---------|-------------|----------|118| **Vercel** | `:4000` | Projects, deployments, domains, env vars, teams |119| **GitHub** | `:4001` | Repos, PRs, issues, comments, reviews, Actions, webhooks, orgs, teams |120| **Google OAuth** | `:4002` | OAuth 2.0 authorize, token exchange, userinfo |121| **Slack** | `:4003` | Chat, conversations, users, reactions, OAuth v2 with consent UI |122| **Apple Auth** | `:4004` | Sign in with Apple — OIDC discovery, JWKS (RS256), auth flow, token exchange |123| **Microsoft Entra** | `:4005` | OAuth 2.0/OIDC v2.0, authorization code + PKCE, refresh token rotation, v1 token endpoint, Graph `/users/{id}` |124| **Okta** *(0.4+)* | `:4006` | OIDC discovery, JWKS, authorize/token/userinfo/revoke/introspect, Users/Groups/Apps CRUD |125| **AWS** | `:4007` | S3 buckets, SQS queues, IAM users/roles, STS identity |126| **Resend** *(0.4+)* | `:4008` | Send + batch (100/req), list/retrieve/cancel, domains, API keys, audiences, contacts, **local inbox** (`GET /inbox`) |127| **Stripe** *(0.4+)* | `:4009` | Customers, payment methods, customer sessions, payment intents, charges, products, prices, **hosted checkout session** w/ webhook delivery |128| **MongoDB Atlas** *(0.4+)* | `:4010` | Admin API v2 (projects, clusters, DB users) + Data API v1 (full CRUD + aggregate) |129| **Clerk** *(0.5+)* | `:4011` | Users, sessions, organizations |130| **Linear** *(0.7+)* | `:4012` | Orgs, teams, issues, cycles, webhooks |131| **Twilio** *(0.8+)* | `:4013` | Accounts, phone numbers, messages, calls, conversations, messaging services, Verify flows, simulator endpoints |132133Default ports are `4000` plus each service's position in emulate's service list (0.12.0), so this134table is the one place ports are written down; `tests/skills/structure/test-emulate-ports.mjs`135checks it, its references and the emulate-engineer agent against that order.136137See `references/api-coverage.md` for full endpoint lists.138139### Next.js Adapter (0.4+) — `@emulators/adapter-next`140141Runs 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.142143```typescript144// next.config.js145const { withEmulate } = require('@emulators/adapter-next')146module.exports = withEmulate({ /* your next config */ })147148// app/api/[...emulate]/route.ts149import { createEmulateHandler } from '@emulators/adapter-next'150export const { GET, POST } = createEmulateHandler({151 services: ['github', 'stripe', 'resend'],152 persistence: { /* load(), save() or built-in filePersistence */ },153})154```155156## Seed Config Structure157158A seed config pre-populates the emulator with tokens, users, repos, and projects so tests start from a known state.159160```yaml161# emulate.config.yaml162tokens:163 dev_token:164 login: yonatangross165 scopes: [repo, workflow, admin:org]166 ci_token:167 login: ci-bot168 scopes: [repo]169170github:171 users:172 - login: yonatangross173 name: Yonatan Gross174 - login: ci-bot175 name: CI Bot176 repos:177 - owner: yonatangross178 name: my-project179 private: false180 default_branch: main181 topics: [typescript, testing]182183vercel:184 users:185 - username: yonatangross186 email: yonaigross@gmail.com187 projects:188 - name: my-docs189 framework: next190191# NEW in 0.4.x — drop-in seed blocks192okta:193 users:194 - login: alice@example.com195 firstName: Alice196 lastName: Smith197 groups: [{ name: Everyone }, { name: Admins }]198 apps: [{ name: My Web App }]199 authorization_servers:200 - name: default201 audiences: ["api://default"]202203resend:204 domains: [{ name: example.com }]205 api_keys: [{ name: default }]206 # In tests: GET http://localhost:4008/inbox to assert captured emails207208stripe:209 customers:210 - name: Test Customer211 email: customer@example.com212 products: [{ name: Pro Plan }, { name: Starter Plan }]213 prices:214 - { product: Pro Plan, unit_amount: 4900, currency: usd, recurring: { interval: month } }215 - { product: Starter Plan, unit_amount: 1900, currency: usd, recurring: { interval: month } }216 # Webhook delivery fires on checkout.session.completed / expired217218mongoatlas:219 projects: [{ name: my-project }]220 clusters: [{ project: my-project, name: my-cluster }]221 database_users: [{ project: my-project, username: app-user }]222```223224See `rules/seed-config.md` for full schema and best practices.225226## Programmatic SDK227228> 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.229230```typescript231import { createEmulator } from 'emulate'232233const github = await createEmulator({ service: 'github', port: 4001 })234// github.url -> 'http://localhost:4001'235236// State is real — create a PR and it appears in the list237const res = await fetch(`${github.url}/repos/org/repo/pulls`, {238 method: 'POST',239 headers: { Authorization: 'Bearer dev_token' },240 body: JSON.stringify({ title: 'Test PR', head: 'feature', base: 'main' })241})242243const prs = await fetch(`${github.url}/repos/org/repo/pulls`)244// -> includes the PR we just created245246// Auto-generated credentials (0.10.0+): readonly GeneratedSecret[], each247// { service, kind, id, label, value }. A GitHub App emulator, for example,248// generates its own RSA key rather than making you supply one.249github.generatedSecrets250251// Cleanup252github.reset() // Synchronous state wipe253await github.close() // Shut down server254```255256`seed` here is a parsed object, not a path. Only the CLI `--seed` flag takes a filename.257For multi-service setup, lifecycle hooks, and the Vitest/Jest wiring, see258`references/upstream.md`. For the ork-side corrections to that API, see259`references/ork-delta.md`.260261## Webhook Delivery262263Emulate delivers real webhooks with HMAC-SHA256 signatures when state changes. The264signature FORMAT is per-provider, so one generic verifier does not cover every service.265GitHub-format headers remain the default; Stripe has used its own format since 0.10.0.266267```typescript268import crypto from 'crypto'269270// GitHub format (the default for most services): sha256=<hmac over the raw body>271function verifyWebhook(payload: string, signature: string, secret: string): boolean {272 const expected = 'sha256=' + crypto273 .createHmac('sha256', secret)274 .update(payload)275 .digest('hex')276 return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))277}278279// Stripe format, as of emulate 0.10.0: Stripe-Signature: t=<timestamp>,v1=<hmac>,280// where the HMAC covers `<timestamp>.<raw body>`, NOT the body alone. Verifying a281// Stripe delivery with the GitHub helper above fails on both counts.282function verifyStripeWebhook(rawBody: string, header: string, secret: string): boolean {283 const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')))284 const expected = crypto285 .createHmac('sha256', secret)286 .update(`${parts.t}.${rawBody}`)287 .digest('hex')288 return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))289}290```291292See `rules/webhook-setup.md` for webhook receiver patterns.293294## CI Integration295296```yaml297# .github/workflows/test.yml298jobs:299 test:300 steps:301 - uses: actions/checkout@v4302 - name: Start emulate303 run: npx emulate --service github --seed .emulate/ci.yaml &304 - name: Wait for emulate305 run: sleep 2306 - name: Run tests307 run: npm test308 env:309 GITHUB_API_BASE: http://localhost:4001310 VERCEL_API_BASE: http://localhost:4000311```312313### Parallel Test Execution314315Each test worker gets its own port to avoid race conditions:316317```typescript318// vitest.config.ts319const workerPort = 4001 + parseInt(process.env.VITEST_WORKER_ID || '0')320```321322See `rules/parallel-ci.md` for full parallel isolation patterns.323324## Decision Matrix325326| Tool | When to Use | Stateful? | Platforms |327|------|------------|-----------|-----------|328| **emulate** (FIRST CHOICE) | GitHub/Vercel/Google/Slack/Apple/Entra/AWS/Okta/Resend/Stripe/MongoDB/Clerk/Linear testing | YES | All 13 services |329| Pact | Contract verification between services | No | Any |330| MSW | In-browser/Node HTTP mocking | No | Any |331| Nock | Node.js HTTP intercept | No | Any |332| WireMock | HTTP stub server | Partial | Any |333334**Use emulate when:**335- Testing code that calls GitHub, Vercel, Google, Slack, Apple, Entra, AWS, Okta, Resend, Stripe, MongoDB Atlas, Clerk, or Linear336- You need state persistence across multiple API calls in a test337- You want webhook delivery with real HMAC signatures (GitHub, Stripe)338- You need cascading side-effects (delete repo -> PRs cascade-delete)339- You need to assert on sent emails without hitting a real provider (Resend local `/inbox`)340- You need hosted Stripe checkout sessions with real redirect flow in tests341342**Use MSW/Nock when:**343- Mocking arbitrary HTTP APIs not covered by emulate344- You need in-browser interception (MSW)345- Tests only need single request/response pairs346347## Upstream coverage (do not restate)348349This skill is a wrap plus our delta. emulate ships its own per-service reference docs;350copying them here only produces something that goes stale on the next release. If a351topic below comes up, read the first-party source, not a paraphrase.352353| Topic | First-party source |354|---|---|355| Programmatic API (`createEmulator`, `url`, `reset()`, `close()`), Vitest/Jest wiring, config auto-detection order, token fallback | `references/upstream.md` (synced from `vercel-labs/emulate`, `skills/emulate/SKILL.md`) |356| GitHub endpoint recipes, GitHub App JWT seeding, Octokit and Auth.js base-URL wiring, GitHub OAuth flow | https://github.com/vercel-labs/emulate/blob/main/skills/github/SKILL.md |357| Google OIDC discovery, JWKS, authorize/token/userinfo/revoke, PKCE, `google-auth-library`, Passport, `openid-client` | https://github.com/vercel-labs/emulate/blob/main/skills/google/SKILL.md |358| Vercel endpoint recipes, cursor pagination, team scoping, integration OAuth flow | https://github.com/vercel-labs/emulate/blob/main/skills/vercel/SKILL.md |359| Every other emulator (Slack, Apple, Entra, AWS, Okta, Resend, Stripe, MongoDB Atlas, Clerk, Linear, Twilio) | https://github.com/vercel-labs/emulate/tree/main/skills |360361**What stays ours:** `references/ork-delta.md` (the corrections and house conventions that362are not in any vendor doc), `references/cli-reference.md`, `references/api-coverage.md`,363`references/dep-to-emulator-map.json`, `scripts/auto-discover.sh`, and everything in `rules/`.364365Read `references/ork-delta.md` before copying any snippet out of a vendor doc. It records366the two API facts vendor prose does not spell out (the exported factory is `createEmulator`,367and `seed` in the programmatic options is an object rather than a path) plus the368`*_API_BASE` env-var convention this repo uses instead of the vendor's `*_EMULATOR_URL`.369370## Related Skills371372- `testing-integration` — Integration test patterns (emulate as first choice for API tests)373- `testing-e2e` — End-to-end test patterns with emulated backends374- `testing-unit` — Unit test patterns (use emulate for API-dependent units)375- `security-patterns` — Auth token patterns (emulate token seeding)376377## CLI Reference378379See `references/cli-reference.md` for all CLI flags and commands.