Firebase emulator로 트리거 함수 로컬에서 테스트해보기

상황

firebase firestore db에 데이터가 업데이트되면, onDocumentWrite라는 트리거를 걸어두어 db에 새로운 컬렉션을 자동으로 저장하게 하는 코드를 짜고 있다.

그런데, 테스트를 어떻게 해야하는거지?

로컬환경에서 개발하고 있는 코드가 잘 작동되는지 확인하고 싶을때마다 매번 firebase에 배포해서 일일이 확인해야하는걸까? 

말도 안됨!!!

 

이럴때 실제 운영되고 있는 db와는 관련없이, 작성한 코드가 제대로 작동하는지 로컬에서 테스트해볼 수 있는 `Firebase Emulator Suite`라는 에뮬레이터라는 도구가 있다. 

 

목표

로컬환경에서 작성한 트리거 코드가 Firestore에 잘 저장되는지 에뮬레이터로 테스트해보며 확인한다. 

 

Firebase Emulator Suite 으로 로컬에서 테스트하는 법

1. Firebase Emulator 설치

 

터미널에서 아래와 같이 에뮬레이터를 설치한다.

firebase setup:emulators:firestore

 

 

아래처럼 init 명령어로 설치해도 무방하다. 

firebase init emulators

 

이 경우 아래와 같이 원하는 Emulator를 선택 가능.

=== Emulators Setup
? Which Firebase emulators do you want to set up? Press Space to select emulators, then Enter to confirm your choices. (Press
<space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
 ◯ App Hosting Emulator
❯◯ Firestore Emulator
❯◯ Functions Emulator
 ◯ Database Emulator
 ◯ Hosting Emulator
 ◯ Pub/Sub Emulator
 ◯ Storage Emulator
 ◯ Eventarc Emulator

 

나는 firestore와 functions를 함께 테스트해야하니 두 가지를 선택했다.

 

2. 에뮬레이터 실행

프로젝트 루트 (package.json, firebase.json)이 있는 경로에서 에뮬레이터를 실행한다. 

firebase emulators:start --only firestore,functions

 

그럼 터미널에 성공했다고 뜨고 에뮬레이터가 켜진다. 아래와 같이 링크가 나온다.

 

 

링크를 타고 들어가면 에뮬레이터를 켜면 아래와 같이 브라우저에서 인터페이스로 확인이 가능하다. 

 

 

3. 기존 코드 (HTTP 함수) 테스트 방법

우선 trigger 함수를 작성하기 이전, 기존 버전의 코드는 아래와 같다. 

HTTP 함수(express)는 이미 배포가 되어있는 상태였고, 아래와 같이 코드를 작성했었다.

 

//server/firebase.json
//...
"functions": [
    {
      "source": ".",
      "codebase": "default",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log",
        "*.local"
      ],
      "rewrites": [
        {
          "source": "**",
          "function": "api"
        }
      ],
      "runtime": "nodejs22"
    }
  ]
//...

 

`firebase.json`에서 `"functions"`의 `"source": "."` 라고 설정해뒀다. 즉, 서버 프로젝트 root 디렉토리에서 firebase functions코드가 실행되도록 설정해둠.

더해서, `firebase.json`에서 `"rewrites"`설정을 보면 모든 요청을 `api`라는 네이밍으로 보내고있다. 즉, 모든 HTTP 요청 함수는 `api`라는 이름의 Firebase Functions로 연결하라는 뜻 이다. 

 

물론 api 함수는 루트 디렉토리 내부에 정의가 되어 있어야 한다.

 

//server/src/index.ts
import express, { Express } from "express";
import { onRequest } from "firebase-functions/v2/https";

const app: Express = express();
//...
export const api = onRequest(app);

 

따라서 위와 같이 프로젝트에는 `src/index.ts`에 `api`로 네이밍한 함수도 export 되어있다. 

express 앱을 firebase functions 로 래핑해두었었다. 

 

자, 그리고 나서 이상태에서 에뮬레이터를 켜서 functions 로그를 보면, 아래와 같이 뜬다.

 

functions: Loaded functions definitions from source: api.

 

source: api 가 찍히는 것을 보니 우선 에뮬레이터가 잘 작동하는 건 맞다.

 

4. trigger 코드 테스트 방법

트리거 함수 작성

firestore 함수 트리거 공식문서 참고

//server/src/functions/triggers/waterCreated.ts

import { onDocumentWritten } from "firebase-functions/v2/firestore";
import { logger } from "firebase-functions/v2";

export const waterCreated = onDocumentWritten(
  `${water컬렉션이름}/{documentId}`,
  (event) => {
    const snapshot = event.data;

    if (!snapshot) {
      logger.log("No data associated with the event");
      return;
    }
    const newData = snapshot.after.data();
    logger.log(newData, "뉴데이터");
  }
);

 

위는 파이어스토어에 내가 지정한 컬렉션이 새로 업데이트 될때마다 호출되는 트리거 함수이다.

water라는 상세값이 담긴 컬렉션이 업데이트되면, 히스토리 내역 컬렉션을 새로 생성해서 water라는 상세값에서 받은 값을 새로운 필드값으로 가공해서 새로 db에 저장하려는 로직을 작성 예정이라, 우선 새로 들어오는 데이터가 로그에 잘 찍히는 지 확인해보는 로직이다. 

 

여기서, 에뮬레이터에서 로그를 확인해보려면 console.log가 아닌 `logger.log`로 확인해야한다. 

 

하지만 로컬에서 코드를 바꾸고, 아무리 에뮬레이터를 재시작하고 Firestore 에뮬레이터에 새 데이터를 추가해봐도, 위 로그는 보이지 않았다. 

 

디버깅

여기서.. 

 

trigger함수도 api함수로 보내야하는 건가?라고 헷갈리기 시작했다.

하지만, 트리거 함수는 Firestore의 데이터 변화로 자동 호출되는 함수이기때문에 api 함수와는 무관하다.

 

그렇다면?

 

trigger 함수가 functions에 아직 등록이 안된거다.

즉, 트리거함수를 실제 export 해줘야지 firebase functions에서 트리거 함수를 인식할 수 있다.

 

트리거 함수 export 시키기

 

 `src/index.ts`에 아래와 같이 위와 같이 적어준 트리거함수를 export 시켜야한다. 

//server/src/index.ts

export { waterCreated } from "./functions/triggers/waterCreated";

 

trigger 함수는 그냥 export만 해두고, Firebase가 직접 감지해서 Firestore 변경될 때 실행시킨다.

 

 

번외로 얘기하자면 나는 여기서 디버깅이 또 엄청 오래걸렸는데..

서버프로젝트/
├── src/
│   ├── index.ts         <- Firebase Emulator가 읽는 진짜 index
│   └── functions/
│       └── triggers/
│           └── waterCreated.ts
├── firebase.json
├── package.json

 

내 `firebase.json`에서 적어둔 코드처럼 functions의 source가 `"."` (root) 이기 때문에 파이어베이스가 보고 있는건 루트디렉토리이다.

파이어베이스는 기본적으로 `firebase.json`의 `source` 설정을 기준으로 functions 를 어디서 찾아야 할지를 판단하기때문에 Firebase가 직접 읽는 파일은 오직 `src/index.ts`라는 거다. 

 

근데 이걸 정확히 몰라서 트리거함수를 다른데서 export 했었었다;;

 

`firebase.json`에 정의한대로 `functions`의 `source` 설정을 기준으로 그 디렉토리에서 export를 해줘야 파이어베이스가 읽을 수 있다!!!! 

 

자, 이렇게 바꾸고 다시 한번 `firebase emulators:start --only firestore,functions`로 에뮬레이터를 재실행했다.

근데.. 여전히 안됨.. 

 

어이없게도 당연한걸 놓쳤다.

 

빌드하기

• 에뮬레이터를 시작하기 전에 tsc 빌드를 먼저 해야한다.
• 새로 작성한 trigger 함수를 빌드해야지 새로운 코드를 에뮬레이터가 읽을 수 있다.

 

에뮬레이터에서 돌리려면 빌드가 필요한 이유?

1. TypeScript는 브라우저나 Node.js가 바로 이해할 수 없다.
   → Node.js (에뮬레이터 포함)는 .ts 파일을 실행할 수 없고 .js 파일만 실행할 수 있다.
2. tsc(또는 npm run build)는 TypeScript를 JavaScript로 변환하는 작업이다.
   → 빌드하면 src/index.ts 같은 파일이 dist/index.js 같은 실행 가능한 자바스크립트 파일로 바뀐다.
3. Firebase Emulator는 빌드된 자바스크립트 파일을 실행한다.
   → 에뮬레이터가 dist/폴더 같은 데서 .js 파일을 읽어 실행하는 구조이다. 

 

(작성) src/index.ts  --[tsc 빌드]--> (변환) dist/index.js
src/ → 내가 개발하는 곳 (TypeScript, 최신 문법 사용 가능)

dist/ → 실제로 에뮬레이터/서버가 실행하는 곳 (Node.js가 읽을 수 있는 JS)

"에뮬레이터 = 자바스크립트(.js) 파일만 읽는다" → 그래서 매번 빌드가 필요하다.

 

에뮬레이터 실행하기

firebase emulators:start --only firestore,functions

 

위 명령어로 다시 에뮬레이터를 실행해준다.

 

 

따라서, 정상 작동하는 플로우를 정리하면 아래와 같다. 

 

정리

🛠 정리된 "정상 작동 플로우"

• trigger 파일 내부 onDocumentWritten 정확히 작성 (v2 버전 문법으로 사용)
• src/index.ts에서 export (`firebase.json`에 정의한대로 `functions`의 `source` 설정을 기준으로 export하기)
• tsconfig 설정 점검 (src 기준으로 컴파일하도록 세팅되어있는지, module 설정이 "commonjs" 혹은 "esnext"로 되어있는지 확인)
• npm run build
• firebase emulators:start (빌드 후 매번 에뮬레이터 재 실행)
• 로딩 로그 확인

 

이렇게 제대로 했다면, 아래와 같이 에뮬레이터 Functions 로그에는 트리거 함수까지 잘 로드가 되었다고 찍힌다.

아래와 같이 functions: Loaded functions definitions from source: waterCreated. 이런 로그가 잘 찍히는 걸 확인할 수 있다. 

 

 

 

Firestore 에뮬레이터에서도 내가 원하는대로 water라는 컬렉션에 상세 데이터를 넣으면, (트리거함수가 호출되면서) 저절로 histories라는 컬렉션에 데이터가 새로 추가되는 것을 눈으로 직접 확인해 볼 수 있다. 

 

 

 

🍀🍀🍀

끝