The Firebase CLI includes a Cloud Functions emulator which can emulate the following function types:
- HTTPS functions
- Callable functions
- Cloud Firestore functions
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
version8.0.0
or higher.firebase-functions
version3.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:
- 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
firebase functions:shell
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"
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 quickstart sample.