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 or Android.

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 Cloud Functions

Since the Cloud Functions and database emulators interoperate, the Emulator Suite is the ideal tool for modeling the interaction between your database and other components of your app using functions as go-between.

An example Firestore and Cloud Functions prototyping sequence might be:

  1. Start your preliminary design by analyzing data and dataflows: what is the structure of your data, which modifications of the data should trigger background functions, and what should those functions do?

  2. To start a first implementation of this design, begin by specifying security rules for your initial Firestore database.

  3. Write the first version of your background function(s).

  4. Write test code to populate your emulated database with sample documents, including updates you intend to trigger functions.

  5. Write test code to flush and reset your emulated database between tests.

  6. Execute tests, and verify database content updates and function invocations.

  7. Review test results and iterate on your starting design.

When iterations are complete, you can deploy code to Firebase.

The snippets on this page illustrate this workflow in the iOS SDK and Android SDK using Firestore. iOS and Android snippets assume one or more test classes and a test harness. Details about platform-specific test patterns and frameworks are omitted: development teams have so many strong opinions about their tooling and methodology, we're just going to focus on the key code points where your prototypes interact with the Firestore and Cloud Functions emulators.

Locally initialize a Firebase project

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

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 Firestore and Cloud Functions, associate the directory with a registered Firebase project, and select programming language and other options, as needed:

$ firebase init

Instrument your app to talk to the emulators

For mobile platform development, your test class(es) or in-app configuration will point your code at the Firestore and Cloud Functions emulators.

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
Android
FirebaseFunctions.getInstance().useFunctionsEmulator("10.0.2.2:5001");
iOS - Swift
Functions.functions().useFunctionsEmulator(origin: "http://localhost:5001")

Write a Security Rules test file

In general, before you start any Firebase development, you need to consider what your Firestore Security Rules should look like. For this emulator getting started, since our focus is on Cloud Functions testing, we'll leave the Firestore emulator running with its default open security.

You can learn more about implementing Security Rules at Get Started with Cloud Firestore Security Rules.

Implement a function to trigger from Firestore updates

So we can see how the Cloud Functions and Firestore emulators interoperate, let's implement a function with a Firestore trigger. The following function will be triggered when a userId document is added to the users collection. The function is designed to access the name field of the user record and output that name to the console.

// Save in ./functions/test.js

exports.createUser = functions.firestore
    .document('users/{userId}')
    .onCreate((snap, context) => {
      // Get an object representing the document
      // e.g. {'first': 'Marie', 'last': 'Curie', 'born': 1867}
      const newValue = snap.data();

      // access a particular field as you would any JS property
      const firstname = newValue.first;

      // Output the field to the console
      console.log(firstname);
    });

Implement Firestore update to trigger the function in app code

Now we can use platform SDK methods, identical to any live production code, to update a Firestore document to trigger our function in the Firestore emulator.

Android
// Create a new user with a first and last name
Map<String, Object> user = new HashMap<>();
user.put("first", "Ada");
user.put("last", "Lovelace");
user.put("born", 1815);

// Add a new document with a generated ID
db.collection("users")
        .add(user)
        .addOnSuccessListener(new OnSuccessListener<DocumentReference>() {
            @Override
            public void onSuccess(DocumentReference documentReference) {
                Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId());
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error adding document", e);
            }
        });
iOS - Swift
// Add a new document with a generated ID
var ref: DocumentReference? = nil
ref = db.collection("users").addDocument(data: [
    "first": "Ada",
    "last": "Lovelace",
    "born": 1815
]) { err in
    if let err = err {
        print("Error adding document: \(err)")
    } else {
        print("Document added with ID: \(ref!.documentID)")
    }
}

Start the Firestore 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. In fact, they'll be reloaded automatically if you change your Rules configuration file; there is no need to restart the emulator to check 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: 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.

Execute your test app

Now execute your app test code. In this getting started example, we expect output to the system console. In realistic scenarios, you could check that your function updated documents in the emulated Cloud Firestore database, modifed a panel in your UI test, etc.

Implement a Firestore database reset to run 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 method 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.

Using a more automated process

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 shutdown emulators in a single command with the exec option:

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

For an even more automated functions unit testing workflow, you should get familiar with the Firebase Test SDK for Cloud Functions described below.

Supplemental options for Cloud Functions testing

The Firebase CLI environment provides you tools to prototype and test functions that extend what you can do with the Emulator Suite:

  • The Cloud Functions shell, which allows for interactive, iterative functions development. The shell employs the Cloud Functions emulator but provides a REPL-style interface for development. Using the shell, you can mock data to simulate function calls from products like Storage, PubSub, Analytics, Storage, Auth, and Crashlytics.
  • The Firebase Test SDK for Cloud Functions, a Node.js with mocha framework for functions development.

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

Visualize Emulator Suite activity

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

Visualize Security Rules evaluations

For this tutorial, the Firestore emulator is running with open security, but 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: