Before connecting your app to the Cloud Firestore emulator, make sure that you understand the overall Firebase Local Emulator Suite workflow and that you install and configure the Local Emulator Suite.
Instrument your app to talk to the emulators
Android, iOS, and Web SDKs
Set up your in-app configuration or test classes to interact with Cloud Firestore as follows.
Android
// 10.0.2.2 is the special IP address to connect to the 'localhost' of // the host computer from an Android emulator. FirebaseFirestore firestore = FirebaseFirestore.getInstance(); firestore.useEmulator("10.0.2.2", 8080); FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder() .setPersistenceEnabled(false) .build(); 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 // Firebase previously initialized using firebase.initializeApp(). var db = firebase.firestore(); if (location.hostname === "localhost") { db.useEmulator("localhost", 8080); }
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.
Admin SDKs
The Firebase Admin SDKs automatically connect to the Cloud Firestore
emulator when the FIRESTORE_EMULATOR_HOST
environment variable is set:
export FIRESTORE_EMULATOR_HOST="localhost:8080"
If your code is running inside the Cloud Functions emulator your project ID
and other configuration will be automatically set when calling initalizeApp
.
When connecting to the Cloud Firestore emulator from any other environment,
you will need to specify a project ID. You can pass a project ID to
initializeApp
directly or set the GCLOUD_PROJECT
environment variable.
Note that you do not need to use your real Firebase project ID; the
Cloud Firestore emulator will accept any project ID, as long as it has a
valid format.
Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" };
Environment Variable
export GCLOUD_PROJECT="your-project-id"
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.
Import and export data
The database emulators allow 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
You can instruct the emulator to export data on shutdown, either specifying an
export path or simply using the path passed to the --import
flag.
firebase emulators:start --import=./dir --export-on-exit
These data import and export options work with the
firebase emulators:exec
command as well. For more, refer to the
emulator command reference.
Visualize Security Rules activity
As you work through prototype and test loops, you can use visualization tools and reports provided by the Local Emulator Suite.
Visualize Rules evaluations
As you add Security Rules to your prototype you can debug them with Local Emulator Suite debug tools.
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:
Limitations
The Cloud Firestore Emulator attempts to faithfully replicate the behavior of the production service with some notable limitations:
- Indexes. The emulator does not track compound indexes and instead will execute any valid query. Make sure to test your app against a real Cloud Firestore instance to determine which indexes you will need.
- Limits. The emulator does not enforce all limits enforced in production. For example the emulator may allow transactions that would be rejected as too large by the production service. Make sure you are familiar with the documented limits and that you design your app to proactively avoid them.
What next?
- For a curated set of videos and detailed how-to examples, follow the Firebase Emulators Training Playlist.
- Investigate advanced use cases involving Security Rules testing and the Firebase Test SDK: Test Security Rules (Firestore)
- Since triggered functions are a typical integration with Cloud Firestore, learn more about the Cloud Functions for Firebase emulator at Run functions locally.