Run functions locally

The Firebase CLI includes a Cloud Functions emulator which can emulate the following function types:

• HTTPS functions
• Callable functions
• Background functions triggered from Authentication, Realtime Database, Cloud Firestore, and Cloud Pub/Sub.

You can run functions locally to test them before deploying to production.

Install the Firebase CLI

To use the Cloud Functions emulator, first install the Firebase CLI:

npm install -g firebase-tools

In order to use the local emulator, your Cloud Functions must depend on:

• firebase-admin version 8.0.0 or higher.
• firebase-functions version 3.0.0 or higher.

Set up admin credentials (optional)

If you want your functions tests to interact with Google APIs or other Firebase APIs via the Firebase Admin SDK, you may need to set up admin credentials.

• Cloud Firestore and Realtime Database triggers already have sufficient credentials, and do not require additional setup.
• All other APIs, including Firebase APIs such as Authentication and FCM or Google APIs such as Cloud Translation or Cloud Speech, require the setup steps described in this section. This applies whether you're using the functions shell or firebase emulators:start.

To set up admin credentials for emulated functions:

1. Open the Service Accounts pane of the Google Cloud Console.
2. Make sure that App Engine default service account is selected, and use the options menu at right to select Create key.
3. When prompted, select JSON for the key type, and click Create.

4. Set your Google default credentials to point to the downloaded key:

   Unix

   $ export GOOGLE_APPLICATION_CREDENTIALS="path/to/key.json"
   
   $ firebase emulators:start
   

   Windows

   $ set GOOGLE_APPLICATION_CREDENTIALS=path\to\key.json
   
   $ firebase emulators:start
   

After completing these steps, your functions tests can access Firebase and Google APIs using the Admin SDK. For example, when testing an Authentication trigger, the emulated function could call admin.auth().getUserByEmail(email).

Set up functions configuration (optional)

If you're using custom functions configuration variables, first run the command to get your custom config (run this within the functions directory) in your local environment:

firebase functions:config:get > .runtimeconfig.json
# If using Windows PowerShell, replace the above with:
# firebase functions:config:get | ac .runtimeconfig.json

Run the emulator suite

Note: Code changes you make during an active session are automatically reloaded by the emulator. If your code needs to be transpiled (TypeScript, React) make sure to do so before running the emulator. You can run your transpiler in watch mode with commands like tsc -w to transpile and reload code automatically as you save.

To run the Cloud Functions emulator, use the emulators:start command:

firebase emulators:start

The emulators:start command will start emulators for Cloud Functions, Cloud Firestore, Realtime Database, and Firebase Hosting based on the products you have initialized in your local project using firebase init. If you want to start a particular emulator, use the --only flag:

firebase emulators:start --only functions

If you want to run a test suite or testing script after the emulators have started, use the emulators:exec command:

firebase emulators:exec "./my-test.sh"

Instrument your app to talk to the emulators

To instrument your app to interact with the emulators, you may need to do some additional configuration.

Instrument your app for callable functions

If your prototype and test activities involve callable backend functions, configure interaction with the Cloud Functions for Firebase emulator like this:

Android

        // 10.0.2.2 is the special IP address to connect to the 'localhost' of
        // the host computer from an Android emulator.
        FirebaseFunctions functions = FirebaseFunctions.getInstance();
        functions.useEmulator("10.0.2.2", 5001);
MainActivity.java

iOS - Swift

Functions.functions().useFunctionsEmulator(origin: "http://localhost:5001")
ViewController.swift

Web v8

firebase.functions().useEmulator("localhost", 5001);
emulator-suite.js

Web v9

Learn more about the tree-shakeable Web v9 modular SDK, currently in Beta.

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "localhost", 5001);
fb_functions_emulator_connect.js

Note: Android only. Android network security configuration policies may affect how your code interacts with the Cloud Functions emulator, which serves data locally via unencrypted HTTP. Starting with Android 9 (API level 28), clear text communication is disabled by default. You can set up a network_security_config.xml file to whitelist the Cloud Functions emulator for development on localhost. See the relevant Android developer documentation.

Instrument your app for HTTPS functions emulation

Each HTTPS function in your code will be served from the local emulator using the following URL format:

http://$HOST:$PORT/$PROJECT/$REGION/$NAME

For example a simple helloWorld function with the default host port and region would be served at:

https://localhost:5001/$PROJECT/us-central1/helloWorld

Instrument your app for background-triggered functions emulation

The Cloud Functions emulator supports background-triggered functions from the following sources:

• Realtime Database emulator
• Cloud Firestore emulator
• Authentication emulator
• Pub/Sub emulator

To trigger background events, connect your app or test code to the emulators using the SDK for your platform.

Interactions with other services

The emulator suite includes multiple emulators, which enable testing of cross-product interactions.

Cloud Firestore

If you have Cloud Functions that use the Firebase Admin SDK to write to Cloud Firestore, these writes will be sent to the Cloud Firestore emulator if it is running. If further Cloud Functions are triggered by those writes, they will be run in the Cloud Functions emulator.

Firebase Hosting

If you’re using Cloud Functions to generate dynamic content for Firebase Hosting, firebase emulators:start uses your local HTTP functions as proxies for hosting.

Logging

The emulator streams logs from your functions to the terminal window where they run. It displays all output from console.log(), console.info(), console.error(), and console.warn() statements inside your functions.

Next Steps

For a full example of using the Firebase emulator suite, see the testing quickstart sample.