Before connecting your app to theCloud Functions emulator, make sure thatyouunderstand the overallFirebase Local Emulator Suite workflow,and that youinstall and configuretheLocal Emulator Suite and review itsCLI commands.

Choose a Firebase project

TheFirebase Local Emulator Suite emulates products for a single Firebase project.

To select the project to use, before you start the emulators, in the CLI runfirebase use in your working directory. Or, you can pass the --project flag to each emulator command.

Local Emulator Suite supports emulation ofreal Firebase projects anddemo projects.

We recommend you use demo projects wherever possible. Benefits include:

• Easier setup, since you can run the emulators without ever creating aFirebase project
• Stronger safety, since if your code accidentally invokes non-emulated(production) resources, there is no chance of data change, usage and billing
• Better offline support, since there is no need to access the internet todownload your SDK configuration.

If your prototype and test activities involvecallable backend functions, configure interaction with theCloud Functions for Firebase emulator like this:

// 10.0.2.2 is the special IP address to connect to the 'localhost' of// the host computer from an Android emulator.valfunctions=Firebase.functionsfunctions.useEmulator("10.0.2.2",5001)
MainActivity.kt

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

Functions.functions().useEmulator(withHost:"localhost",port:5001)
ViewController.swift

import{getApp}from"firebase/app";import{getFunctions,connectFunctionsEmulator}from"firebase/functions";constfunctions=getFunctions(getApp());connectFunctionsEmulator(functions,"127.0.0.1",5001);
fb_functions_emulator_connect.js

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

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 simplehelloWorld function with the default host port and region would be served at:

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

Instrument your app for task queue functions emulation

The emulator automatically sets up emulated task queues based on triggerdefinitions, and the Admin SDK reroutes enqueued requests to the emulator ifit detects that it is running via theCLOUD_TASKS_EMULATOR_HOST environmentvariable.

Note that the dispatch system used in production is more complex than theone implemented in the emulator, so you should not expect emulatedbehavior to precisely mirror production environments. The parameters within theemulator provide upper bounds to the rate at which tasks get dispatchedand retried.

Instrument your app for background-triggered functions emulation

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

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

To trigger background events, modify back-end resources using theEmulator Suite UI, or by connecting your app or test code to the emulatorsusing the SDK for your platform.

Test handlers for custom events emitted by Extensions

For functions you implement to handleFirebase Extensions custom eventswithCloud Functions v2, theCloud Functions emulator pairs with theEventarc emulator to supportEventarc triggers.

To test custom event handlers for extensions that emit events, you must installtheCloud Functions and Eventarc emulators.

TheCloud Functions runtime sets theEVENTARC_EMULATOR environmentvariable tolocalhost:9299 in the current process if the Eventarc emulatoris running. TheFirebase Admin SDKs automatically connect to the Eventarcemulator when theEVENTARC_EMULATOR environment variable is set. You canmodify the default port as discussed underConfigureLocal Emulator Suite.

When environment variables are properly configured, theFirebase Admin SDKautomatically sends events to the Eventarc emulator. In turn, the Eventarcemulator makes a call back to theCloud Functions emulator to trigger anyregistered handlers.

You can check Functions logs in theEmulator Suite UI for details onhandler execution.

Configure a local testing environment

If your functions rely on dotenv-basedenvironment configuration,you can emulate that behavior in your local testing environment.

When using a localCloud Functions emulator, you can override environmentvariables for your project by setting up a.env.local file. Contents of.env.local take precedence over.env and the project-specific.env file.

For example, a project could include these three files containing slightlydifferent values for development and local testing:

When started in the local context, the emulator loads the environmentvariables as shown:

$firebaseemulators:startiemulators:Startingemulators:functions# Starts emulator with following environment variables:#  PLANET=Earth#  AUDIENCE=Local Humans

Secrets and credentials in theCloud Functions emulator

TheCloud Functions emulator supports the use of secrets tostore and access sensitive configuration information.By default, the emulator will try to access your production secrets usingapplication default credentials.In certain situations like CI environments, the emulator may fail to accesssecret values due to permission restrictions.

Similar toCloud Functions emulator support for environment variables, you canoverride secrets values by setting up a.secret.local file. This makes iteasy for you to test your functions locally, especially if you don't have accessto the secret value.

What other tools for testingCloud Functions exist?

TheCloud Functions emulator is supplemented by other prototype and testtools:

• The Cloud Functions shell, which allows for interactive, iterative functionsprototyping and development. The shell employs the Cloud Functions emulator witha REPL-style interface for development. No integration with theCloud Firestore orRealtime Database emulators is provided. Using the shell, youmock data and perform function calls to simulate interaction with products thattheLocal Emulator Suite does not currently support: Analytics,Remote Config, and Crashlytics.
• The Firebase Test SDK for Cloud Functions, a Node.js with mocha frameworkfor functions development. In effect, the Cloud Functions Test SDK providesautomation atop the Cloud Functions shell.

You can find more about the Cloud Functions shell and Cloud Functions Test SDKatTest functions interactively andUnit testing of Cloud Functions.

How theCloud Functions emulator differs from production

TheCloud Functions emulator is fairly close to the production environmentfor the majority of use cases. We've put extensive work into ensuring everythingwithin the Node runtime is as close to production as possible. However, theemulator does not mimic the full containerized production environment,so while your function code will execute realistically, other aspects of yourenvironment (i.e. local files, behavior after functions crashes, etc.) willdiffer.

Cloud IAM

The Firebase Emulator Suite does not attempt to replicate or respect anyIAM-related behavior for running. Emulators adhere to the Firebase SecurityRules provided, but in situations where IAM would normally be used, for exampleto set Cloud Functions invoking service account and thus permissions, theemulator is not configurable and will use the globally-available account onyour developer machine, similar to running a local script directly.

Memory and processor restrictions

The emulator does not enforce memory or processor restrictions for yourfunctions. However, the emulator does support timing out functions via thetimeoutSeconds runtime argument.

Note that function execution time may differ from production when functions arerun in the emulator. We recommend that after you've designed and testedfunctions with the emulator, you run limited tests in production to confirmexecution times.

Planning for differences in local and production environments

Since the emulator runs on your local machine, it depends on your localenvironment for applications and built-in programs and utilities.

Be aware that your local environment forCloud Functions development maydiffer from the Google production environment:

• Applications you install locally to simulate the production environment (e.g.ImageMagick fromthis tutorial)may differ in behavior from production, especially if you require a differentversions or develop in a non-Linux environment. Consider deploying your ownbinary copy of the missing program alongside your function deployment.

• Similarly, built-in utilities (e.g., shell commands likels,mkdir) maydiffer from versions available in production, especially if you're developing ina non-Linux environment (e.g., macOS). You can handle this issue by usingNode-only alternatives to native commands, or by building Linux binaries tobundle with your deployment.

Retrying

The Cloud Functions emulator does not support retrying functions on failure.

What next?

• For a curated set of videos and detailed how-to examples, follow theFirebase Emulators Training Playlist.
• Learn more about theCloud Functions for Firebase emulator atRun functions locally.