Go to console

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 BaaS products in an interoperable way. The Cloud Functions emulator supports HTTP functions, callable functions and background functions triggered by Firestore and Realtime Database; the Cloud Functions emulator does not support background functions triggered by Auth or Cloud Storage for Firebase. For Firestore and Realtime Database emulators, Security Rules emulation is built in.

Cloud
Firestore
Realtime
Database
Cloud
Functions
Android SDK
iOS SDK
Web SDK
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 firebase.tools | 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.

Android
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setHost("10.0.2.2:8080")
        .setSslEnabled(false)
        .setPersistenceEnabled(false)
        .build();

FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.setFirestoreSettings(settings);
iOS - Swift
let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
Web
// 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") {
  // Note that the Firebase Web SDK must connect to the WebChannel port
  db.settings({
    host: "localhost:8081",
    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:

Android
FirebaseFunctions.getInstance().useFunctionsEmulator("10.0.2.2:5001");
iOS - Swift
Functions.functions().useFunctionsEmulator(origin: "http://localhost:5001")
Web
Functions.useFunctionsEmulator("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  Starting emulators: ["functions","firestore"]
✔  functions: Emulator started at http://localhost:5001
i  firestore: Serving WebChannel traffic on at http://localhost:8081
i  firestore: Logging to firestore-debug.log
✔  firestore: Emulator started at http://localhost:8080
i  firestore: For testing set FIRESTORE_EMULATOR_HOST=localhost:8080
i  functions: Watching "/Users/apptest/Dev/FirebaseEmulators/functions" for Cloud Functions...
✔  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:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

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/test.sh"

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:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

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:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

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

What next?