Firebase Local Emulator Suite — Firebase 한 묶음을 노트북에 띄우기

Firebase 는 2011 년 작은 스타트업으로 시작해 2014 년 Google 에 인수됐습니다. 매니지드 모델이 강한 서비스답게 한동안은 "로컬에서 띄우는 길이 없다" 가 맞는 답이었지만, 2020 년 3 월 Firebase Local Emulator Suite 가 정식 GA 되면서 그림이 바뀌었습니다.

1. Suite 에 대한 이야기

Firebase Local Emulator Suite 는 Firebase CLI (firebase-tools) 안에 들어 있는 로컬 에뮬레이터 묶음입니다. Java 가상머신 위에서 도는 9 개 에뮬레이터가 한 프로세스로 부팅되고, 단일 Web UI (디폴트 4000 포트) 에서 시각적으로 다 볼 수 있습니다.

에뮬레이터	디폴트 포트	흉내 대상
Authentication	9099	Firebase Auth (이메일·OAuth·OTP·MFA).
Cloud Firestore	8080	NoSQL 문서 DB.
Realtime Database	9000	JSON 트리 DB.
Cloud Storage	9199	객체 스토리지 (S3 비호환).
Cloud Functions	5001	서버리스 함수.
Cloud Pub/Sub	8085	메시지 큐.
Eventarc	9299	CloudEvents 라우팅.
Hosting	5000	정적 사이트.
Firebase Extensions	(각자)	확장 패키지.

가장 중요한 사실 — FCM (Cloud Messaging) 은 이 목록에 없습니다. Firebase 가 공식적으로 emulator 미제공. 이유는 단순 — FCM 은 실제 디바이스 토큰과 Google 의 푸시 인프라를 거쳐야 동작하므로 시뮬레이션이 의미 없는 도메인입니다. 인터넷에 흔히 떠도는 "FCM emulator" 는 모두 비공식 wrapper 또는 HTTP mock.

2. 한 프로세스, 여러 포트

firebase emulators:start 한 번으로 전부 부팅. 각 에뮬레이터는 자체 포트에 listen. SDK 는 환경변수 (FIRESTORE_EMULATOR_HOST · FIREBASE_AUTH_EMULATOR_HOST) 가 있으면 자동으로 emulator 로 향하므로 코드 변경 0.

3. 데이터 영속성 · Web UI

기본은 메모리 — 종료 시 데이터 사라짐. --export-on-exit ./data + --import ./data 옵션을 쓰면 종료 시 export, 시작 시 import. 또는 emulator 캐시 디렉터리 자체를 볼륨 마운트.

Web UI (디폴트 4000 포트) — Authentication 탭에서 사용자를 직접 추가하면 즉시 ID 토큰 발급. Firestore 탭에선 문서를 직접 추가/수정/삭제. "API 호출 → DB 변경" 흐름 디버깅의 가장 빠른 길.

Firestore Security Rules — firestore.rules 파일을 마운트하면 emulator 안에서 그 규칙이 적용. SDK 호출이 거부되면 정확한 거부 사유가 로그에. 운영 배포 전에 규칙 회귀 테스트하는 표준 방법.

4. 호스트에서 직접

npm i -g firebase-tools
firebase init emulators
firebase emulators:start

firebase init emulators 가 firebase.json 의 emulator 섹션을 만듭니다. 어떤 emulator 를 활성화할지 인터랙티브하게 선택.

5. Docker 컨테이너

공식 Docker 이미지는 없고, 커뮤니티 이미지가 표준입니다.

services:
  firebase:
    image: andreysenov/firebase-tools:13.x
    user: node
    working_dir: /home/node
    command:
      - firebase
      - emulators:start
      - --project=demo
      - --only=auth,firestore,storage,functions
    ports:
      - "4400:4400"   # UI (디폴트 4000)
      - "9099:9099"   # Auth
      - "8085:8085"   # Firestore
    volumes:
      - ./firebase.json:/home/node/firebase.json:ro

이미지 500 MB. 첫 부팅 시 emulator JAR 다운로드 + Java 부팅으로 3060 초.

6. SDK 호출

Node.js (firebase-admin) — 환경변수만 잡으면 자동 분기:

export FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
export FIRESTORE_EMULATOR_HOST=localhost:8085
export FIREBASE_STORAGE_EMULATOR_HOST=localhost:9199
export GOOGLE_CLOUD_PROJECT=demo

import { initializeApp } from "firebase-admin/app";
import { getFirestore } from "firebase-admin/firestore";

initializeApp({ projectId: "demo" });
await getFirestore().collection("users").add({ name: "테스트 사용자" });

Web 클라이언트 (firebase) — 환경변수 자동 인식이 안 되어 명시 호출:

import { initializeApp } from "firebase/app";
import { connectAuthEmulator, getAuth } from "firebase/auth";
import { connectFirestoreEmulator, getFirestore } from "firebase/firestore";

const app = initializeApp({ projectId: "demo", apiKey: "fake-api-key" });
connectAuthEmulator(getAuth(app), "http://localhost:9099");
connectFirestoreEmulator(getFirestore(app), "localhost", 8085);

7. 한계

FCM 없음 — 서버 측 송신 호출 검증은 WireMock 같은 HTTP mock 으로 별도.

Firebase Hosting 의 SSR — 일부 미지원. Functions 와의 연동 일부 제약.

Cloud Storage 의 다운로드 URL — emulator 가 발급하는 URL 이 운영과 형식이 다릅니다. URL 을 DB 에 저장해 두는 패턴은 환경 분기 필요.

Performance Monitoring · Crashlytics · Remote Config — emulator 가 아예 없습니다. 운영에서만 검증.

App Check · App Hosting — 부분 지원 또는 미지원. 공식 매트릭스 확인.

Java 의존 — 컨테이너 안에 JDK 가 들어 있어 이미지가 무겁습니다 (~500 MB+). 메모리도 ~500 MB.

단일 인스턴스 가정 — 하나의 PC 에서 한 번만. 팀 공유는 별도 호스트.

8. CI 에서 쓰기

- run: docker compose up -d firebase
- run: |
    until curl -sf http://localhost:4400 >/dev/null; do sleep 2; done
- run: pnpm test

테스트 시작 전 emulator ready 폴링이 핵심. 안 그러면 첫 호출이 ECONNREFUSED.

하고픈 말

Firebase Emulator Suite 는 9 개 중 FCM 만 빠진다는 점이 가장 자주 검색되는 함정입니다. 환경변수만 잡으면 SDK 가 자동 분기하므로 코드 변경 0. CI 에서 ready 폴링만 잘 처리하면 통합 테스트의 표준 채널이 됩니다.

Next

• api-mocking-wiremock

Firebase Emulator Suite · Connect & Prototype · andreysenov/firebase-tools · FCM 공식 (emulator 미지원 명시) 를 참고합니다.