OAuth認証のテスト、Webhookの受信確認、クラウドストレージへのアップロード処理。外部サービスのAPIに依存した機能を開発するたびに、本番用のアカウントやシークレットキーを用意する手間が発生します。CIパイプラインにAPIキーを渡せばセキュリティリスクが増え、オフライン環境ではテスト自体が実行できません。

Vercel Labsが公開したOSS「emulate」は、この問題をまとめて解決します。GitHub・Google・Slack・AWS・Apple・Microsoft・Vercelの7サービスのAPIをローカルで完全に再現するエミュレーターです。GitHubスターは1,100超、ライセンスはApache-2.0で公開されています。

この記事でわかること

  • emulateが解決する課題とモックとの違い
  • 対応する7サービスのエミュレーション範囲
  • CLIとプログラムAPIによる導入手順
  • Next.jsアプリへの組み込み方法
  • CIでの活用パターン

モックではないステートフルなAPIエミュレーション

GitHub - vercel-labs/emulate: Local API emulation for CI and no-network sandboxes
Local API emulation for CI and no-network sandboxes - vercel-labs/emulate
GitHub

一般的なAPIモックは、固定のレスポンスを返すだけです。データの作成・更新・削除が連動しないため、OAuthフロー全体のテストやWebhookのトリガーといった複雑なシナリオには対応できません。

emulateはモックではなく、インメモリのステートフルなAPIサーバーです。データの作成が他のエンドポイントの返り値に反映され、GitHubのPRをマージすればブランチ保護ルールが適用されます。SlackにメッセージをPOSTすればスレッドが生成され、Google Driveにファイルをアップロードすればリスト取得で返ります。本番APIと同じ振る舞いをローカルで再現できる点が、単純なモックツールとの決定的な違いです。

7サービスの対応範囲

emulateが再現するサービスと主なAPI範囲は以下の通りです。

GitHub — ユーザー、リポジトリ、Issue、Pull Request、ブランチ保護、Webhook配信、Actions、Checks、リリース、検索まで網羅しています。OAuth AppsとGitHub Appsの両方に対応し、JWT認証やインストールアクセストークンも機能します。

Google — OAuth 2.0とOpenID Connectに加え、Gmail（メッセージ送受信・ラベル・フィルター・ドラフト）、Calendar（イベントCRUD・空き時間検索）、Drive（ファイルCRUD・アップロード）をカバーしています。

Slack — Web API全般に対応します。チャンネルの作成・メッセージ投稿・スレッド返信・リアクション・OAuth v2フロー・Incoming Webhookが動作します。

AWS — S3（バケット・オブジェクト操作）、SQS（キュー作成・メッセージ送受信）、IAM（ユーザー・ロール・アクセスキー管理）、STS（GetCallerIdentity・AssumeRole）を提供します。公式AWS SDKがそのまま使えるよう、ワイヤーフォーマットを忠実に再現しています。

Vercel — プロジェクト、デプロイメント、ドメイン、環境変数、チームなどのAPI。カーソルベースのページネーションまで再現されています。

Apple / Microsoft — いずれもOAuth 2.0 / OpenID Connectの認証フロー全体を再現します。Apple Sign InのRS256 IDトークン生成や、Microsoft Entra IDのクライアントクレデンシャルグラントにも対応しています。

CLIで3秒で起動する

導入はコマンド1つです。

npx emulate

設定ファイルなしで全7サービスが起動します。GitHub APIはhttp://localhost:4001、Google APIはhttp://localhost:4002といった具合に、サービスごとにポートが自動割り当てされます。特定のサービスだけ起動する場合は--serviceフラグを使います。

npx emulate --service github,google

初期データを投入したい場合は、YAML設定ファイルを使います。npx emulate initでスターター設定が生成されるため、ゼロから書く必要はありません。たとえばGitHubのユーザーとリポジトリ、Slackのチャンネルとユーザーをあらかじめ用意した状態でエミュレーターを起動できます。

テストコードから直接使うプログラムAPI

CLIだけでなく、Node.jsのプログラムAPIも提供されています。VitestやJestのセットアップファイルから直接エミュレーターを起動し、テスト終了時にクリーンアップする使い方が想定されています。

import { createEmulator } from 'emulate'

const github = await createEmulator({ service: 'github', port: 4001 })
process.env.GITHUB_API_URL = github.url

// テスト実行後
await github.close()

reset()メソッドでストアを初期状態に戻せるため、テストケース間でデータが干渉しません。CIで本番APIキーを使う必要がなくなり、シークレット管理の負担がゼロになります。

Next.jsアプリにエミュレーターを埋め込む

emulateの特徴的な機能として、Next.jsアプリへの直接組み込みがあります。@emulators/adapter-nextパッケージを使うと、エミュレーターがアプリと同じオリジンで動作します。

この設計が解決するのは、Vercelのプレビューデプロイメント問題です。プレビュー環境ではデプロイごとにURLが変わるため、OAuthのコールバックURLを事前に登録できません。エミュレーターをアプリ内に埋め込めば、コールバックURLは常に同一オリジンのパスになり、この問題が消えます。

Auth.js（NextAuth）との連携も想定されており、プロバイダーの設定をエミュレーターのパスに向けるだけで動作します。

HTTPS対応とportless連携

ローカル開発でもHTTPSが必要なケースがあります。同じくVercel Labsが公開している「portless」と組み合わせると、github.emulate.localhostのような名前付きHTTPS URLが自動生成されます。証明書も自動で用意されるため、ブラウザの警告なしでHTTPS通信をテストできます。

npx emulate start --portless

CIでの活用

emulateはCI環境での利用を主要なユースケースとして設計されています。本番APIへの接続が不要なため、CIジョブにシークレットを渡す必要がありません。シード設定で初期データを固定すれば、テスト結果が決定論的になります。ネットワーク遅延も発生しないため、外部API呼び出しを含むテストスイートの実行時間が短縮されます。

GitHub Actionsであれば、ワークフローのservicesではなくnpx emulateをセットアップステップに追加するだけです。Docker不要で動作する点も、CI環境での導入ハードルを下げています。

AIコーディングエージェントとの連携

emulateはVercel Labsの「skills」エコシステムとも統合されています。npx skills add vercel-labs/emulate --skill stripeのようなコマンドで、AIコーディングエージェント（Cursor、Claude Code、Codexなど）にエミュレーターのスキルを追加できます。エージェントが決済機能やOAuth認証を実装する際、自動的にエミュレーターを起動してテスト可能な環境を構築します。

現時点の制限

エミュレーターの状態はデフォルトでインメモリに保持されるため、プロセスを再起動するとデータが消えます。永続化が必要な場合は、KVストアやファイルベースのpersistence adapterを設定する必要があります。

また、各サービスの全APIを網羅しているわけではありません。たとえばAWSはS3・SQS・IAM・STSの4サービスに限られ、Lambda・DynamoDB・CloudFormationなどは含まれていません。本番APIとの完全な互換性を期待するのではなく、開発・テストで頻繁に使うエンドポイントをカバーするツールとして捉えるのが適切です。

emulateは2026年3月に公開された比較的新しいプロジェクトです。今後のサービス追加やAPI拡充の動向を追う価値はあります。