Before connecting your app to the Realtime Database 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
Set up your in-app configuration or test classes to interact with the
Realtime Database as follows.
Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val database = Firebase.database
database.useEmulator("10.0.2.2", 9000)
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseDatabase database = FirebaseDatabase.getInstance();
database.useEmulator("10.0.2.2", 9000);
Swift
// In almost all cases the ns (namespace) is your project ID.
let db = Database.database(url:"http://127.0.0.1:9000?ns=YOUR_DATABASE_NAMESPACE")
Web modular API
import { getDatabase, connectDatabaseEmulator } from "firebase/database";
const db = getDatabase();
if (location.hostname === "localhost") {
// Point to the RTDB emulator running on localhost.
connectDatabaseEmulator(db, "127.0.0.1", 9000);
}
Web namespaced API
var db = firebase.database();
if (location.hostname === "localhost") {
// Point to the RTDB emulator running on localhost.
db.useEmulator("127.0.0.1", 9000);
}
No additional setup is needed to test Cloud Functions
triggered by Realtime Database events
using the emulator. When the Realtime Database and Cloud Functions emulators are
both running, they automatically work together.
Admin SDKs
The Firebase Admin SDKs automatically connect to the Realtime Database emulator when
the
FIREBASE_DATABASE_EMULATOR_HOST
environment variable is set:
export FIREBASE_DATABASE_EMULATOR_HOST="127.0.0.1:9000"
If your code is running inside the Cloud Functions emulator your project ID
and other configuration will be automatically set when calling
initializeApp
.
If you want your Admin SDK code to connect to a shared emulator running in
another environment, you will need to specify the
the same project ID you set using the Firebase CLI
.
You can pass a project ID to
initializeApp
directly or set the
GCLOUD_PROJECT
environment variable.
Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
Environment Variable
export GCLOUD_PROJECT="your-project-id"
Clear your database between tests
To flush the Realtime Database between activities, you can clear the database reference. You can use this approach as an alternative to simply shutting down the emulator process.
Kotlin+KTX
// With a DatabaseReference, write null to clear the database.
database.reference.setValue(null)
Java
// With a DatabaseReference, write null to clear the database.
database.getReference().setValue(null);
Swift
// With a DatabaseReference, write nil to clear the database.
Database.database().reference().setValue(nil);
Web modular API
import { getDatabase, ref, set } from "firebase/database";
// With a database Reference, write null to clear the database.
const db = getDatabase();
set(ref(db), null);
Web namespaced API
// With a database Reference, write null to clear the database.
firebase.database().ref().set(null);
Naturally, your code should await confirmation that the flush finished or failed using the asynchronous event handling features of your platform.
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 and Cloud Storage for Firebase 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 tools.
After running a suite of tests, you can access test coverage reports that show
how each of your 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:9000/.inspect/coverage?ns=<database_name>
This breaks your rules into expressions and subexpressions that you can
mouseover for more information, including number of executions and values
returned. For the raw JSON version of this data, include the following URL in
your query:
http://localhost:9000/.inspect/coverage.json?ns=<database_name>
What next?