Anwendung mit dem Cloud Firestore-Emulator verbinden

Bevor Sie Ihre Anwendung mit dem Cloud Firestore-Emulator verbinden, sollten Sie sich mit dem allgemeinen Workflow der Firebase Local Emulator Suite vertraut machen, die Local Emulator Suite installieren und konfigurieren sowie die zugehörigen CLI-Befehle überprüfen.

Firebase-Projekt auswählen

Die Firebase Local Emulator Suite emuliert Produkte für ein einzelnes Firebase-Projekt.

Um das zu verwendende Projekt auszuwählen, führen Sie vor dem Starten der Emulatoren in der Befehlszeile firebase use in Ihrem Arbeitsverzeichnis aus. Alternativ können Sie das Flag --project an jeden Emulatorbefehl übergeben.

Die Local Emulator Suite unterstützt die Emulation echter Firebase-Projekte und Demoprojekte.

Wir empfehlen, nach Möglichkeit Demoprojekte zu verwenden. Die wichtigsten Vorteile:

• Einfachere Einrichtung, da Sie die Emulatoren ausführen können, ohne ein Firebase-Projekt zu erstellen
• Erhöhte Sicherheit: Wenn Ihr Code versehentlich nicht emulierte (Produktionsressourcen) aufruft, besteht keine Möglichkeit einer Datenänderung, Nutzung und Abrechnung.
• Bessere Offline-Unterstützung, da Sie zum Herunterladen der SDK-Konfiguration keinen Zugriff auf das Internet benötigen.

App instrumentieren, um mit den Emulatoren zu sprechen

Beim Start erstellt der Cloud Firestore-Emulator für jede firestore-Konfiguration in der Datei firebase.json eine Standarddatenbank und eine benannte Datenbank.

Benannte Datenbanken werden auch implizit als Reaktion auf SDK- oder REST API-Aufrufe an den Emulator erstellt, die auf eine bestimmte Datenbank verweisen. Solche implizit erstellten Datenbanken arbeiten mit offenen Regeln.

Wenn Sie in der Emulator Suite-UI interaktiv mit Ihren Standard- und benannten Datenbanken arbeiten möchten, aktualisieren Sie in der Adressleiste des Browsers die URL, sodass entweder die Standarddatenbank oder eine benannte Datenbank ausgewählt wird.

• Wenn Sie beispielsweise die Daten in Ihrer Standardinstanz durchsuchen möchten, aktualisieren Sie die URL in localhost:4000/firestore/default/data.
• Aktualisieren Sie auf localhost:4000/firestore/ecommerce/data, um eine Instanz mit dem Namen ecommerce zu durchsuchen.

Android, Apple-Plattformen und Web-SDKs

Richten Sie Ihre In-App-Konfigurations- oder Testklassen so ein, dass sie mit Cloud Firestore interagieren. Beachten Sie, dass in den folgenden Beispielen eine Verbindung zum Anwendungscode zur Standardprojektdatenbank hergestellt wird. Beispiele für weitere Cloud Firestore-Datenbanken, die über die Standarddatenbank hinausgehen, finden Sie in der Anleitung für mehrere Datenbanken.

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
EmulatorSuite.kt

// 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);
EmulatorSuite.java

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);
fs_emulator_connect.js

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}
emulator-suite.js

Um Cloud Functions-Funktionen, die durch Firestore-Ereignisse ausgelöst werden, mit dem Emulator zu testen, ist keine zusätzliche Einrichtung erforderlich. Wenn der Firestore- und der Cloud Functions-Emulator ausgeführt werden, arbeiten sie automatisch zusammen.

Admin-SDKs

Die Firebase Admin SDKs stellen automatisch eine Verbindung zum Cloud Firestore-Emulator her, wenn die Umgebungsvariable FIRESTORE_EMULATOR_HOST festgelegt ist:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Wenn der Code im Cloud Functions-Emulator ausgeführt wird, werden Ihre Projekt-ID und andere Konfiguration beim Aufrufen von initializeApp automatisch festgelegt.

Wenn Sie möchten, dass Ihr Admin SDK-Code mit einem freigegebenen Emulator verbunden wird, der in einer anderen Umgebung ausgeführt wird, müssen Sie dieselbe Projekt-ID angeben, die Sie über die Firebase CLI festgelegt haben. Sie können eine Projekt-ID direkt an initializeApp übergeben oder die Umgebungsvariable GCLOUD_PROJECT festlegen.

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

Datenbank zwischen Tests löschen

Produktions-Firestore bietet keine Plattform-SDK-Methode zum Leeren der Datenbank. Der Firestore-Emulator bietet Ihnen jedoch einen REST-Endpunkt speziell für diesen Zweck, der vor dem Start eines Tests über einen Einrichtungs-/TearDown-Schritt des Test-Frameworks, aus einer Testklasse oder aus der Shell (z. B. mit curl) aufgerufen werden kann. Sie können diesen Ansatz als Alternative verwenden, um den Emulator-Prozess einfach herunterzufahren.

Führen Sie in einer geeigneten Methode einen HTTP-DELETE-Vorgang aus und geben Sie dabei Ihre Firebase-Projekt-ID, z. B. firestore-emulator-example, an den folgenden Endpunkt an:

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

Natürlich sollte Ihr Code auf die REST-Bestätigung warten, dass der Leerungsvorgang abgeschlossen wurde oder fehlgeschlagen ist.

Sie können diesen Vorgang über die Shell ausführen:

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

Wenn Sie einen solchen Schritt implementiert haben, können Sie Ihre Tests sequenzieren und Ihre Funktionen mit der Gewissheit auslösen, dass alte Daten zwischen Ausführungen dauerhaft gelöscht werden und Sie eine neue Referenztestkonfiguration verwenden.

Daten importieren und exportieren

Mit den Datenbank- und Cloud Storage for Firebase-Emulatoren können Sie Daten aus einer laufenden Emulatorinstanz exportieren. Definieren Sie einen Basissatz von Daten, die in Ihren Unittests oder Continuous-Integration-Workflows verwendet werden sollen, und exportieren Sie diese dann, um sie mit dem Team zu teilen.

firebase emulators:export ./dir

Importieren Sie die Referenzdaten beim Start des Emulators in Tests.

firebase emulators:start --import=./dir

Sie können den Emulator anweisen, Daten beim Herunterfahren zu exportieren. Dazu geben Sie entweder einen Exportpfad an oder verwenden den Pfad, der an das Flag --import übergeben wurde.

firebase emulators:start --import=./dir --export-on-exit

Diese Optionen für den Datenimport und -export funktionieren auch mit dem Befehl firebase emulators:exec. Weitere Informationen finden Sie in der Referenz zu Emulatorbefehlen.

Aktivität zu Sicherheitsregeln visualisieren

Während Sie Prototyp- und Testschleifen durcharbeiten, können Sie Visualisierungstools und Berichte der Local Emulator Suite verwenden.

Anfragemonitor verwenden

Mit dem Cloud Firestore-Emulator können Sie Clientanfragen in der Emulator Suite-UI visualisieren, einschließlich der Auswertungsverfolgung für Firebase-Sicherheitsregeln.

Öffnen Sie den Tab Firestore > Anfragen, um die detaillierte Bewertungssequenz für jede Anfrage aufzurufen.

Berichte zu Regelauswertungen visualisieren

Wenn Sie Ihrem Prototyp Sicherheitsregeln hinzufügen, können Sie diese mit den Fehlerbehebungstools der Local Emulator Suite debuggen.

Nachdem Sie eine Reihe von Tests ausgeführt haben, können Sie auf Berichte zur Testabdeckung zugreifen, die Aufschluss darüber geben, wie die einzelnen Sicherheitsregeln bewertet wurden.

Um die Berichte abzurufen, fragen Sie einen bereitgestellten Endpunkt im Emulator ab, während er ausgeführt wird. Verwenden Sie für eine browserfreundliche Version die folgende URL:

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

Dadurch werden Ihre Regeln in Ausdrücke und Teilausdrücke aufgeteilt. Bewegen Sie die Maus auf einen Ausdruck oder Teilausdruck, um weitere Informationen zu erhalten, einschließlich der Anzahl der Bewertungen und der zurückgegebenen Werte. Fügen Sie für die JSON-Rohversion dieser Daten die folgende URL in Ihre Abfrage ein:

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

Hier werden in der HTML-Version des Berichts Bewertungen hervorgehoben, die Fehler mit nicht definierten Werten und Nullwerte verursachen:

Unterschiede zwischen Cloud Firestore-Emulator und Produktion

Der Cloud Firestore-Emulator versucht, das Verhalten des Produktionsdienstes originalgetreu zu replizieren. Es gibt jedoch einige Einschränkungen.

Unterstützung mehrerer Datenbanken für Cloud Firestore

Derzeit unterstützt die Emulator Suite-UI das interaktive Erstellen, Bearbeiten, Löschen, das Monitoring von Anfragen und die Sicherheitsvisualisierung für eine Standarddatenbank, jedoch keine zusätzlichen benannten Datenbanken.

Der Emulator selbst erstellt jedoch eine benannte Datenbank anhand der Konfiguration in der firebase.json-Datei und implizit als Antwort auf SDK- oder REST API-Aufrufe.

Transaktionen

Der Emulator implementiert derzeit nicht das gesamte in der Produktion beobachtete Transaktionsverhalten. Wenn Sie Features testen, die mehrere gleichzeitige Schreibvorgänge in einem Dokument beinhalten, führt der Emulator möglicherweise dazu, dass Schreibanfragen langsam ausgeführt werden. In einigen Fällen kann es bis zu 30 Sekunden dauern, bis Sperren aufgehoben werden. Passen Sie die Zeitüberschreitungen bei den Tests bei Bedarf entsprechend an.

Indexe

Der Emulator verfolgt keine zusammengesetzten Indexe und führt stattdessen eine beliebige gültige Abfrage aus. Testen Sie Ihre Anwendung unbedingt an einer echten Cloud Firestore-Instanz, um festzustellen, welche Indexe Sie benötigen.

Limits

Der Emulator erzwingt nicht alle Beschränkungen, die in der Produktion erzwungen werden. Der Emulator kann beispielsweise Transaktionen zulassen, die vom Produktionsdienst als zu groß abgelehnt würden. Machen Sie sich mit den dokumentierten Beschränkungen vertraut und entwickeln Sie Ihre Anwendung so, dass diese proaktiv vermieden werden.

Was kann ich jetzt für Sie tun?

• Eine Auswahl von Videos und detaillierte Anleitungsbeispiele finden Sie in der Playlist zum Firebase Emulators Training.
• Informieren Sie sich über erweiterte Anwendungsfälle im Zusammenhang mit dem Testen von Sicherheitsregeln und dem Firebase Test SDK: Sicherheitsregeln testen (Firestore).
• Da die ausgelösten Funktionen eine typische Integration in Cloud Firestore darstellen, erhalten Sie unter Funktionen lokal ausführen weitere Informationen zum Cloud Functions for Firebase-Emulator.