Connect your app to the Cloud Functions Emulator

Before connecting your app to the Cloud Functions emulator, make sure that you understand the overall Firebase Local Emulator Suite workflow, and that you install and configure the Local Emulator Suite and review its CLI commands.

Choose a Firebase project

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

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

Local Emulator Suite supports emulation of real Firebase projects and demo projects.

Project type Features Use with emulators
Real

A real Firebase project is one you created and configured (most likely via the Firebase console).

Real projects have live resources, like database instances, storage buckets, functions, or any other resource you set up for that Firebase project.

When working with real Firebase projects, you can run emulators for any or all of the supported products.

For any products you are not emulating, your apps and code will interact with the live resource (database instance, storage bucket, function, etc.).

Demo

A demo Firebase project has no real Firebase configuration and no live resources. These projects are usually accessed via codelabs or other tutorials.

Project IDs for demo projects have the demo- prefix.

When working with demo Firebase projects, your apps and code interact with emulators only. If your app attempts to interact with a resource for which an emulator isn't running, that code will fail.

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

  • Easier setup, since you can run the emulators without ever creating a Firebase 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 to download your SDK configuration.

Instrument your app to talk to the emulators

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
Swift
Functions.functions().useFunctionsEmulator(origin: "http://localhost:5001")
ViewController.swift

Web version 9

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

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

Web version 8

firebase.functions().useEmulator("localhost", 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 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.

What other tools for testing Cloud Functions exist?

The Cloud Functions emulator is supplemented by other prototype and test tools:

  • The Cloud Functions shell, which allows for interactive, iterative functions prototyping and development. The shell employs the Cloud Functions emulator with a REPL-style interface for development. No integration with the Cloud Firestore or Realtime Database emulators is provided. Using the shell, you mock data and perform function calls to simulate interaction with products that the Local Emulator Suite does not currently support: Analytics, Remote Config, and Crashlytics.
  • The Firebase Test SDK for Cloud Functions, a Node.js with mocha framework for functions development. In effect, the Cloud Functions Test SDK provides automation atop the Cloud Functions shell.

You can find more about the Cloud Functions shell and Cloud Functions Test SDK at Test functions interactively and Unit testing of Cloud Functions.

How the Cloud Functions emulator differs from production

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

Cloud IAM

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

Memory and processor restrictions

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

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

Planning for differences in local and production environments

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

Be aware that your local environment for functions development may differ from the Google production environment:

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

  • Similarly, built-in utilities (e.g., shell commands like ls, mkdir) may differ from versions available in production, especially if you're developing in a non-Linux environment (e.g., macOS). You can handle this issue by using Node-only alternatives to native commands, or by building Linux binaries to bundle with your deployment.

Retrying

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

What next?