The Firebase CLI includes a Cloud Functions emulator which can emulate the
following function types:
- HTTPS functions
- Callable functions
- Background functions triggered from Firebase Authentication, Realtime Database,
Cloud Firestore, Cloud Storage 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 Cloud Functions shell or
firebase emulators:start
.
To set up admin credentials for emulated functions:
- Open the
Service Accounts pane
of the Google Cloud console.
- Make sure that
App Engine default service account
is selected, and use
the options menu at right to select
Create key
.
- When prompted, select
JSON
for the key type, and click
Create
.
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
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:
Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val functions = Firebase.functions
functions.useEmulator("10.0.2.2", 5001)
Java
// 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);
Swift
Functions.functions().useFunctionsEmulator(origin: "http://127.0.0.1:5001")
Web modular API
import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";
const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "127.0.0.1", 5001);
Web namespaced API
firebase.functions().useEmulator("127.0.0.1", 5001);
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, modify back-end resources using the
Emulator Suite UI, or by connecting your app or test code to the emulators
using the SDK for your platform.
Test handlers for custom events emitted by Extensions
For functions you implement to handle Firebase Extensions custom events
with Cloud Functions v2, the Cloud Functions emulator pairs with the
Eventarc emulator to support
Eventarc triggers
.
To test custom event handlers for extensions that emit events, you must install
the Cloud Functions and Eventarc emulators.
The Cloud Functions runtime sets the
EVENTARC_EMULATOR
environment
variable to
localhost:9299
in the current process if the Eventarc emulator
is running. The Firebase Admin SDKs automatically connect to the Eventarc
emulator when the
EVENTARC_EMULATOR
environment variable is set. You can
modify the default port as discussed under
Configure Local Emulator Suite
.
When environment variables are properly configured, the Firebase Admin SDK
automatically sends events to the Eventarc emulator. In turn, the Eventarc
emulator makes a call back to the Cloud Functions emulator to trigger any
registered handlers.
You can check Functions logs in the Emulator Suite UI for details on
handler execution.
Interactions with other services
The emulator suite includes multiple emulators, which enable
testing of cross-product interactions.
Cloud Firestore
If you have 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 functions are triggered by those writes,
they will be run in the Cloud Functions emulator.
Cloud Storage
If you have functions that use the Firebase Admin SDK (version 9.7.0 or greater)
to write to Cloud Storage, these writes will be sent to the Cloud Storage emulator
if it is running. If further functions are triggered by those writes,
they will be run in the Cloud Functions emulator.
Firebase Authentication
If you have functions that use the Firebase Admin SDK (version 9.3.0 or greater)
to write to Firebase Authentication, these writes will be sent to the Auth emulator
if it is running. If further 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
.