emulate는 처음 보면 단순한 API 모킹 도구처럼 보인다. 하지만 저장소와 공식 문서를 읽어보면 이 프로젝트가 겨냥하는 지점은 조금 다르다. emulate는 Vercel Labs가 만든 로컬 API 에뮬레이터로, CI 환경이나 네트워크가 차단된 샌드박스에서 Vercel, GitHub, Google API를 로컬 서비스로 대체해 실행하도록 설계됐다. 기본 실행도 단순하다. npx emulate 한 줄이면 별도 설정 없이 Vercel은 4000번, GitHub는 4001번, Google은 4002번 포트에서 바로 올라온다.
단순한 mock이 아니라 상태를 기억하는 에뮬레이션
이 도구가 흥미로운 이유는 스스로를 “mock”이 아니라 상태를 기억하는 API 에뮬레이션으로 규정한다는 점이다. 공식 README와 아키텍처 문서에 따르면 코어는 CRUD, 인덱싱, 필터링, 페이지네이션을 지원하는 in-memory Store를 중심으로 돌아가고, 각 서비스 플러그인이 그 위에 라우트를 얹는다. 그래서 한 번 생성한 사용자, 저장소, 배포, 환경변수 같은 데이터가 다음 요청에서도 이어진다. 즉, 단순히 정해둔 JSON을 돌려주는 스텁이 아니라 “행동한 결과가 다음 상태를 바꾸는” 테스트 환경에 더 가깝다.
지원 범위가 보여주는 방향성
이 차이는 실제 지원 범위를 보면 더 분명해진다. Vercel 쪽은 사용자와 팀, 프로젝트, 배포, 도메인, 환경변수 API를 stateful하게 다루고, Vercel 스타일의 JSON 응답과 cursor 기반 페이지네이션을 따른다. GitHub 쪽은 사용자와 저장소뿐 아니라 이슈, 풀리퀘스트, 리뷰, 라벨, 마일스톤, 브랜치 보호, 릴리즈, 웹훅, 검색, Actions, Checks까지 폭넓게 포함한다. Google 쪽은 OAuth 2.0과 OIDC에 필요한 authorize, token, userinfo, discovery, JWKS 엔드포인트를 제공한다. 문서만 봐도 이 프로젝트가 겨냥하는 대상이 단순 REST 응답 흉내가 아니라 인증, 상태 변화, 이벤트 흐름까지 포함한 통합 시나리오라는 점이 보인다.
OAuth와 앱 생태계까지 로컬에서 검증한다
특히 인상적인 부분은 OAuth와 App 생태계까지 로컬에서 검증할 수 있게 해둔 점이다. 설정 파일에는 GitHub OAuth App, GitHub App, Vercel Integration, Google OAuth client를 seed할 수 있고, GitHub App은 JWT 인증과 installation access token 발급까지 지원한다. 여기에 저장소나 조직에 이벤트가 생기면 등록한 webhook_url로 실제 HTTP webhook을 보내고, 필요하면 X-Hub-Signature-256 서명 헤더까지 붙인다. 이 정도면 “외부 플랫폼 연동을 테스트한다”가 아니라 “외부 플랫폼이 있어야만 돌던 흐름을 로컬에 옮긴다”에 더 가깝다.
테스트 인프라로도 바로 붙일 수 있다
개발 경험도 꽤 현실적이다. CLI에서는 어떤 서비스를 띄울지 고를 수 있고, 포트를 바꿀 수 있고, seed 파일을 주입할 수 있고, starter config를 자동 생성할 수도 있다. 코드에서 직접 붙이고 싶다면 createEmulator()로 서비스별 인스턴스를 띄운 다음 reset()과 close()로 테스트 수명주기를 제어하면 된다. README는 Vitest와 Jest에서 beforeAll, afterEach, afterAll에 연결하는 예시까지 제공한다. 이 덕분에 emulate는 로컬 도구이면서 동시에 테스트 인프라 라이브러리로도 쓸 수 있다.
진짜 가치는 외부 의존성을 로컬로 끌어내리는 데 있다
내가 보기엔 이 프로젝트의 진짜 가치는 “실서비스 의존성을 얼마나 로컬로 끌어내릴 수 있느냐”에 있다. 예를 들어 어떤 앱이 GitHub 로그인, GitHub App 설치, Vercel 프로젝트 생성, Google OAuth 로그인 같은 흐름을 동시에 갖고 있다면, 보통은 테스트를 위해 실제 네트워크, 실제 자격 증명, 실제 외부 계정을 붙여야 한다. 그런데 emulate는 애초에 CI와 no-network sandboxes를 목표로 하고, 상태를 메모리에만 들고 있어 빠르게 초기화하고 반복 실행할 수 있도록 설계돼 있다. 그래서 문서가 직접 말하는 기능들을 종합하면, 이 도구는 단위 테스트용 모킹보다 로컬 통합 테스트와 재현 가능한 검증 환경에 더 큰 의미가 있다고 보는 편이 맞다. 이 문장은 공식 목적과 구조를 바탕으로 한 해석이다.
기대치는 정확하게 잡을 필요가 있다
물론 기대치를 과하게 올릴 필요는 없다. 공식 문서는 많은 핵심 엔드포인트와 흐름을 정리해두고 있지만, GitHub나 Vercel, Google의 전체 기능을 1:1로 완전 복제한다고 말하지는 않는다. 저장 상태도 메모리에만 유지되기 때문에 빠르고 리셋이 쉬운 대신, 영속 저장이나 실서비스와의 완전한 등가성보다는 테스트 재현성과 제어 가능성에 초점이 맞춰져 있다. 다시 말해 emulate는 “로컬에서 진짜 플랫폼을 모두 대체하는 제품”이라기보다, “플랫폼 의존적인 개발 흐름을 로컬에서 다뤄볼 수 있게 만드는 아주 공격적인 테스트 도구”로 이해하는 편이 정확하다.
정리
정리하면 emulate의 핵심은 모킹을 잘하는 데 있지 않다. 외부 API를 단순히 흉내 내는 대신, 상태와 인증과 이벤트까지 포함한 흐름을 로컬 환경 안으로 끌고 들어온다는 점이 이 프로젝트의 본질이다. 그래서 이 도구는 “테스트 편의성”보다 한 단계 더 나아간다. 외부 플랫폼에 종속된 개발 경험 자체를 로컬에서 재구성하려는 시도이기 때문이다. CI가 더 빨라지는 것보다 중요한 건, 이제 플랫폼 연동도 점점 코드처럼, 로컬처럼, 반복 가능하게 다룰 수 있다는 점이다. emulate는 바로 그 방향을 꽤 선명하게 보여주는 프로젝트다.
