Connect your app and start prototyping

Before you jump in with Firebase Local Emulator Suite, make sure you've created a Firebase project, set up your development environment, and selected and installed Firebase SDKs for your platform according to the Get started with Firebase topics for your platform: iOS, Android or Web.

Check what's emulated on your platform

If you're eager to get started with Firebase emulators and haven't read through What is Firebase Local Emulator Suite?, check which emulators are supported before you start coding.

The Firebase Local Emulator Suite allows you to test your code with our core products in an interoperable way. The Cloud Functions emulator supports HTTP functions, callable functions, and background functions triggered by Cloud Firestore, Realtime Database and Cloud Pub/Sub; the Cloud Functions emulator does not support background functions triggered by Auth or Cloud Storage for Firebase. For Cloud Firestore and Realtime Database emulators, Security Rules emulation is built in.

Android SDK n/a
iOS SDK n/a
Web SDK n/a
Node.js Admin SDK n/a

Prototype and test

Locally initialize a Firebase project

Make sure that you install the CLI or update to its latest version.

curl -sL | bash

If you haven't already done so, initialize the current working directory as a Firebase project, following the onscreen prompts to specify you're using Cloud Functions and either Firestore or Realtime Database:

firebase init

Instrument your app to talk to the emulators

Your test classes or in-app configuration will point your code at the Firestore emulator.

// is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()

FirebaseFirestore firestore = FirebaseFirestore.getInstance();
iOS - Swift
let settings = Firestore.firestore().settings = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
// Initialize your Web app as described in the Get started for Web
// firebaseApp previously initialized using firebase.initializeApp().
var db = firebaseApp.firestore();
if (location.hostname === "localhost") {
    host: "localhost:8080",
    ssl: false

No additional setup is needed to test Cloud Functions triggered by Firestore events using the emulator. When the Firestore and Cloud Functions emulators are both running, they automatically work together.

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

iOS - Swift
Functions.functions().useFunctionsEmulator(origin: "http://localhost:5001")

Start the database and Cloud Functions emulators

With prototype code and test operations implemented, let's start up the Firestore and Cloud Functions emulators.

$ firebase emulators:start --only firestore,functions

Security Rules are loaded automatically at Firestore emulator startup. They'll also be reloaded automatically if you change your Rules configuration file, so there is no need to restart the emulator to apply a rules change.

Note confirmation from the CLI that the emulators are running on localhost and the Cloud Functions emulator is watching for events associated with function triggers.

i  emulators: Starting emulators: functions, firestore
✔  hub: emulator hub started at http://localhost:4400
✔  functions: functions emulator started at http://localhost:5001
i  firestore: firestore emulator logging to firestore-debug.log
✔  firestore: firestore emulator started at http://localhost:8080
i  firestore: For testing set FIRESTORE_EMULATOR_HOST=localhost:8080
✔  logging: logging emulator started at http://localhost:4500
i  gui: emulator GUI logging to gui-debug.log
✔  gui: emulator GUI started at http://localhost:4000
i  functions: Watching "/Users/apptest/Dev/FirebaseEmulators/functions" for Cloud Functions...
✔  emulators: All emulators started, it is now safe to connect.

Clear your database between tests

Production Firestore provides no platform SDK method for flushing the database, but the Firestore emulator gives you a REST endpoint specifically for this purpose, which can be called from a test framework setup/tearDown step, from a test class, or from the shell (e.g., with curl) before a test is kicked off. You can use this approach as an alternative to simply shutting down the emulator process.

In an appropriate method, perform an HTTP DELETE operation, supplying your Firebase projectID, for example firestore-emulator-example, to the following endpoint:


Naturally, your code should await REST confirmation that the flush finished or failed.

You can perform this operation from the shell:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Having implemented a step like this, you can sequence your tests and trigger your functions with confidence that old data will be purged between runs and you're using a fresh baseline test configuration.

Run test scripts

The previous examples assume a "shared" emulator environment in which emulators are launched with firebase emulators:start, flushed and reset between iterations, and manually terminated when a container or other resource is freed up. For unit testing or other CI strategies, you can start up emulators, run scripted tests, and shut down emulators in a single command with the exec command:

firebase emulators:exec --only functions,firestore "./testdir/"

Set up baseline data for testing

The Cloud Firestore emulator allows you to export data from a running emulator instance. Define a baseline set of data to use in your unit tests or continuous integration workflows, then export it to be shared among the team.

firebase emulators:export ./dir

In tests, on emulator startup, import the baseline data.

firebase emulators:start --import=./dir

Monitor emulators with the Emulator Suite UI

The Emulator Suite provides a user interface that allows you to:

  • Check the status and basic configuration of emulators
  • Add and remove data from Realtime Database and/or Cloud Firestore databases as you prototype, useful for testing Firebase Security Rules and for interactively triggering functions
  • View logs from each running emulator

You can view this UI in your browser at http://localhost:4000 after running the firebase emulators:start command.

Visualize Security Rules activity

As you work through prototype and test loops, you can use visualization tools and reports provided by the Emulator Suite.

Visualize Rules evaluations

As you add Security Rules to your prototype you can debug them with tools provided by the Emulator Suite.

After running a suite of tests, you can access test coverage reports that show how each of your security rules was evaluated.

To get the reports, query an exposed endpoint on the emulator while it's running. For a browser-friendly version, use the following URL:


This breaks your rules into expressions and subexpressions that you can mouseover for more information, including number of evaluations and values returned. For the raw JSON version of this data, include the following URL in your query:


Here, the HTML version of the report highlights evaluations that throw undefined and null-value errors:

What next?