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

快速参考

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

分类	规则数	影响程度	使用场景
种子配置	1	高	为测试环境配置emulate.config.yaml
服务选择	1	中	为测试选择GitHub/Vercel/Google服务
Webhook配置	1	中	测试带HMAC验证的Webhook投递
并行CI	1	高	并行运行测试，避免端口冲突
认证令牌	1	中	预填充映射到模拟用户的令牌

总计：5个分类，共5条规则

Quick Start

快速入门

bash

undefined

bash

undefined

Install

安装

npm install --save-dev emulate

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

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

npx emulate

Start specific services with seed data

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

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

支持服务

Service	Default Port	Coverage
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

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

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

工具选择矩阵

Tool	When to Use	Stateful?	Platforms
emulate (FIRST CHOICE)	GitHub/Vercel/Google API testing	YES	GitHub, Vercel, Google
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, 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	否	任意
Nock	Node.js HTTP拦截	否	任意
WireMock	HTTP stub服务器	部分支持	任意

推荐使用emulate的场景：

测试调用GitHub、Vercel或Google API的代码
测试中需要跨多个API调用持久化状态
需要带有真实HMAC签名的Webhook投递
需要级联副作用（删除仓库→PR级联删除）

推荐使用MSW/Nock的场景：

Mock emulate未覆盖的任意HTTP API
需要浏览器端拦截（MSW）
测试仅需单请求/响应对

Related Skills

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

。

emulate-seed

Original

Translation

Emulate Seed Configs

Emulate 种子配置

Quick Reference

快速参考

Quick Start

快速入门

Install

安装

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

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

Start specific services with seed data

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

Generate a starter config

生成初始配置

Services

支持服务

Seed Config Structure

种子配置结构

emulate.config.yaml

emulate.config.yaml

Programmatic SDK

程序化SDK

Webhook Delivery

Webhook投递

CI Integration

CI集成

.github/workflows/test.yml

.github/workflows/test.yml

Parallel Test Execution

并行测试执行

Decision Matrix

工具选择矩阵

Related Skills

相关技能

CLI Reference

CLI参考

SDK Patterns

SDK模式