Back to Details

emulate-seed

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Emulate Seed Configs

Emulate 种子配置

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.
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.
为emulate（Apache-2.0协议）——Vercel Labs推出的有状态API模拟工具——生成并管理种子配置。每个分类在
rules/
目录下都有独立的规则文件，会按需加载。
并非Mock工具。Emulate提供具备级联删除、游标分页、Webhook投递和HMAC签名验证功能的完整状态机。通过API创建PR后，该PR会出现在
GET /repos/:owner/:repo/pulls
接口的返回列表中。删除仓库时，其关联的议题、PR和Webhook会被级联删除。

Quick Reference

快速参考

CategoryRulesImpactWhen to Use
Seed Config1HIGHSetting up emulate.config.yaml for test environments
Service Selection1MEDIUMChoosing GitHub/Vercel/Google for your tests
Webhook Setup1MEDIUMTesting webhook delivery with HMAC verification
Parallel CI1HIGHRunning tests in parallel without port collisions
Auth Tokens1MEDIUMSeeding tokens mapped to emulated users
Total: 5 rules across 5 categories
分类规则数影响程度使用场景
种子配置1高为测试环境配置emulate.config.yaml
服务选择1中为测试选择GitHub/Vercel/Google服务
Webhook配置1中测试带HMAC验证的Webhook投递
并行CI1高并行运行测试，避免端口冲突
认证令牌1中预填充映射到模拟用户的令牌
总计：5个分类，共5条规则

Quick Start

快速入门

bash
undefined
bash
undefined

Install

安装

npm install --save-dev emulate
npm install --save-dev emulate

Start all services (GitHub :4001, Vercel :4000, Google :4002)

启动所有服务（GitHub :4001，Vercel :4000，Google :4002）

npx emulate
npx emulate

Start specific services with seed data

使用种子数据启动特定服务

npx emulate --service github --seed ./emulate.config.yaml
npx emulate --service github --seed ./emulate.config.yaml

Generate a starter config

生成初始配置

npx emulate init --service github
undefined
npx emulate init --service github
undefined

Services

支持服务

ServiceDefault PortCoverage
GitHub
:4001
Repos, PRs, issues, comments, reviews, Actions, webhooks, orgs, teams
Vercel
:4000
Projects, deployments, domains, env vars, teams
Google OAuth
:4002
OAuth 2.0 authorize, token exchange, userinfo
See 
references/api-coverage.md
for full endpoint lists.
服务默认端口覆盖范围
GitHub
:4001
仓库、PR、议题、评论、评审、Actions、Webhook、组织、团队
Vercel
:4000
项目、部署、域名、环境变量、团队
Google OAuth
:4002
OAuth 2.0授权、令牌交换、用户信息
完整的端点列表请查看
references/api-coverage.md
。

Seed Config Structure

种子配置结构

A seed config pre-populates the emulator with tokens, users, repos, and projects so tests start from a known state.
yaml
undefined
种子配置会预先在模拟器中填充令牌、用户、仓库和项目，让测试从已知状态开始。
yaml
undefined

emulate.config.yaml

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

See `rules/seed-config.md` for full schema and best practices.
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

完整的Schema和最佳实践请查看`rules/seed-config.md`。

Programmatic SDK

程序化SDK

typescript
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

// Cleanup
github.reset()       // Synchronous state wipe
await github.close() // Shut down server
See 
references/sdk-patterns.md
for advanced patterns (multi-service, lifecycle hooks).
typescript
import { createEmulator } from 'emulate'

const github = await createEmulator({ service: 'github', port: 4001 })
// github.url -> 'http://localhost:4001'

// 状态是真实的——创建PR后，它会出现在列表中
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`)
// -> 包含我们刚刚创建的PR

// 清理
github.reset()       // 同步清空状态
await github.close() // 关闭服务器
高级模式（多服务、生命周期钩子）请查看
references/sdk-patterns.md
。

Webhook Delivery

Webhook投递

Emulate delivers real webhooks with HMAC-SHA256 signatures when state changes:
typescript
import crypto from 'crypto'

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))
}
See 
rules/webhook-setup.md
for webhook receiver patterns.
当状态发生变化时，Emulate会发送带有HMAC-SHA256签名的真实Webhook：
typescript
import crypto from 'crypto'

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))
}
Webhook接收器模式请查看
rules/webhook-setup.md
。

CI Integration

CI集成

yaml
undefined
yaml
undefined

.github/workflows/test.yml

.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
undefined
jobs: test: steps: - uses: actions/checkout@v4 - name: 启动emulate run: npx emulate --service github --seed .emulate/ci.yaml & - name: 等待emulate启动 run: sleep 2 - name: 运行测试 run: npm test env: GITHUB_API_BASE: http://localhost:4001 VERCEL_API_BASE: http://localhost:4000
undefined

Parallel Test Execution

并行测试执行

Each test worker gets its own port to avoid race conditions:
typescript
// vitest.config.ts
const workerPort = 4001 + parseInt(process.env.VITEST_WORKER_ID || '0')
See 
rules/parallel-ci.md
for full parallel isolation patterns.
每个测试工作进程会分配独立的端口，避免竞争条件：
typescript
// vitest.config.ts
const workerPort = 4001 + parseInt(process.env.VITEST_WORKER_ID || '0')
完整的并行隔离模式请查看
rules/parallel-ci.md
。

Decision Matrix

工具选择矩阵

ToolWhen to UseStateful?Platforms
emulate (FIRST CHOICE)GitHub/Vercel/Google API testingYESGitHub, Vercel, Google
PactContract verification between servicesNoAny
MSWIn-browser/Node HTTP mockingNoAny
NockNode.js HTTP interceptNoAny
WireMockHTTP stub serverPartialAny
Use emulate when:
  • Testing code that calls GitHub, Vercel, or Google APIs
  • You need state persistence across multiple API calls in a test
  • You want webhook delivery with real HMAC signatures
  • You need cascading side-effects (delete repo -> PRs cascade-delete)
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
工具使用场景支持状态持久化？支持平台
emulate（首选）GitHub/Vercel/Google API测试是GitHub、Vercel、Google
Pact服务间契约验证否任意
MSW浏览器/Node.js HTTP Mock否任意
NockNode.js HTTP拦截否任意
WireMockHTTP stub服务器部分支持任意
推荐使用emulate的场景：
  • 测试调用GitHub、Vercel或Google API的代码
  • 测试中需要跨多个API调用持久化状态
  • 需要带有真实HMAC签名的Webhook投递
  • 需要级联副作用（删除仓库→PR级联删除）
推荐使用MSW/Nock的场景：
  • Mock emulate未覆盖的任意HTTP API
  • 需要浏览器端拦截（MSW）
  • 测试仅需单请求/响应对

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)
  • testing-integration
    —— 集成测试模式（API测试首选emulate）
  • testing-e2e
    —— 基于模拟后端的端到端测试模式
  • testing-unit
    —— 单元测试模式（依赖API的单元测试可使用emulate）
  • security-patterns
    —— 认证令牌模式（emulate令牌种子配置）

CLI Reference

CLI参考

See 
references/cli-reference.md
for all CLI flags and commands.
所有CLI标志和命令请查看
references/cli-reference.md
。

SDK Patterns

SDK模式

See 
references/sdk-patterns.md
for programmatic 
createEmulator()
usage.
程序化
createEmulator()
的用法请查看
references/sdk-patterns.md
。