emulate-seed

Original：🇺🇸 English

Translated

Generate emulate seed configs for stateful API emulation. Wraps Vercel's emulate tool for GitHub (repos, PRs, issues, Actions, webhooks), Vercel (projects, deployments, domains), and Google OAuth APIs. Not mocks — full state machines where create-a-PR-and-it-appears-in-the-list. Use when setting up test environments, CI pipelines, integration tests, or offline development.

2installs

Sourceyonatangross/orchestkit

Added on2026-03-25

NPX Install

npx skill4agent add yonatangross/orchestkit emulate-seed

SKILL.md Content

View Translation Comparison →

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.

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.

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

bash

# Install
npm install --save-dev emulate

# Start all services (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

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.

Seed Config Structure

A seed config pre-populates the emulator with tokens, users, repos, and projects so tests start from a known state.

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.

Programmatic 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).

Webhook Delivery

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.

CI Integration

yaml

# .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:

typescript

// 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 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

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.

SDK Patterns

See

references/sdk-patterns.md

for programmatic

createEmulator()

usage.

emulate-seed

NPX Install

Tags

SKILL.md Content

Emulate Seed Configs

Quick Reference

Quick Start

Services

Seed Config Structure

Programmatic SDK

Webhook Delivery

CI Integration

Parallel Test Execution

Decision Matrix

Related Skills

CLI Reference

SDK Patterns