Verbinden Sie Ihre App mit dem Cloud Firestore Emulator

Bevor Sie Ihre App mit dem Cloud Firestore-Emulator verbinden, stellen Sie sicher, dass Sie den gesamten Firebase Local Emulator Suite-Workflow verstehen , dass Sie die Local Emulator Suite installieren und konfigurieren und ihre CLI-Befehle überprüfen.

Wählen Sie ein Firebase-Projekt

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 CLI 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 Ihnen, nach Möglichkeit Demoprojekte zu verwenden. Zu den Vorteilen gehören:

• Einfachere Einrichtung, da Sie die Emulatoren ausführen können, ohne jemals ein Firebase-Projekt zu erstellen
• Höhere Sicherheit, denn wenn Ihr Code versehentlich nicht emulierte (Produktions-)Ressourcen aufruft, besteht keine Chance auf Datenänderung, Nutzung und Abrechnung
• Bessere Offline-Unterstützung, da zum Herunterladen Ihrer SDK-Konfiguration kein Zugriff auf das Internet erforderlich ist.

Instrumentieren Sie Ihre App, um mit den Emulatoren zu kommunizieren

Beim Start erstellt der Cloud Firestore-Emulator eine Standarddatenbank und eine benannte Datenbank für jede firestore Konfiguration in Ihrer Datei firebase.json . Verwenden Sie Ihre Datei firebase.json , um Cloud Firestore-Sicherheitsregeln explizit einer benannten Datenbank zuzuweisen.

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

Derzeit unterstützt die Benutzeroberfläche der Emulator Suite interaktives Arbeiten mit der Standarddatenbank .

Android-, Apple-Plattformen und Web-SDKs

Richten Sie Ihre In-App-Konfiguration oder Testklassen wie folgt für die Interaktion mit Cloud Firestore ein. Beachten Sie, dass in den folgenden Beispielen der App-Code eine Verbindung zur Standardprojektdatenbank herstellt. Beispiele für zusätzliche Cloud Firestore-Datenbanken über die Standarddatenbank hinaus finden Sie im Leitfaden 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.isPersistenceEnabled = false 
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

Es ist keine zusätzliche Einrichtung erforderlich, um durch Firestore-Ereignisse ausgelöste Cloud-Funktionen mit dem Emulator zu testen. Wenn sowohl die Firestore- als auch die Cloud Functions-Emulatoren 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 Ihr Code im Cloud Functions-Emulator ausgeführt wird, werden Ihre Projekt-ID und andere Konfigurationen beim Aufruf initializeApp automatisch festgelegt.

Wenn Sie möchten, dass Ihr Admin-SDK-Code eine Verbindung zu einem gemeinsam genutzten Emulator herstellt, der in einer anderen Umgebung ausgeführt wird, müssen Sie dieselbe Projekt-ID angeben, die Sie mit der 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"

Löschen Sie Ihre Datenbank zwischen den Tests

Production Firestore bietet keine Plattform-SDK-Methode zum Leeren der Datenbank, aber der Firestore-Emulator stellt Ihnen speziell für diesen Zweck einen REST-Endpunkt zur Verfügung, der von einem Test-Framework-Setup/TearDown-Schritt, von einer Testklasse oder von der Shell (z. B. mit curl ) aufgerufen werden kann, bevor ein Test gestartet wird. Sie können diesen Ansatz als Alternative zum einfachen Herunterfahren des Emulatorprozesses verwenden.

Führen Sie in einer geeigneten Methode einen HTTP-DELETE-Vorgang durch und geben Sie Ihre Firebase-Projekt-ID, zum Beispiel 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 Flush abgeschlossen ist 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"

Nachdem Sie einen Schritt wie diesen implementiert haben, können Sie Ihre Tests sequenzieren und Ihre Funktionen mit der Gewissheit auslösen, dass alte Daten zwischen den Läufen gelöscht werden und Sie eine neue Basistestkonfiguration 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 Basisdatensatz zur Verwendung in Ihren Unit-Tests oder Continuous-Integration-Workflows und exportieren Sie ihn dann zur gemeinsamen Nutzung im Team.

firebase emulators:export ./dir

Importieren Sie in Tests beim Start des Emulators die Basisdaten.

firebase emulators:start --import=./dir

Sie können den Emulator anweisen, Daten beim Herunterfahren zu exportieren, indem Sie entweder einen Exportpfad angeben oder einfach den an das Flag --import übergebenen Pfad verwenden.

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

Diese Datenimport- und -exportoptionen funktionieren auch mit dem Befehl firebase emulators:exec . Weitere Informationen finden Sie in der Emulator-Befehlsreferenz .

Visualisieren Sie die Aktivität „Sicherheitsregeln“.

Beim Durcharbeiten von Prototypen- und Testschleifen können Sie Visualisierungstools und Berichte verwenden, die von der Local Emulator Suite bereitgestellt werden.

Verwenden Sie den Anforderungsmonitor

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

Öffnen Sie die Registerkarte Firestore > Anfragen , um die detaillierte Bewertungssequenz für jede Anfrage anzuzeigen.

Visualisieren Sie Regelauswertungsberichte

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

Nachdem Sie eine Reihe von Tests ausgeführt haben, können Sie auf Testabdeckungsberichte zugreifen, die zeigen, wie jede Ihrer Sicherheitsregeln bewertet wurde.

Um die Berichte zu erhalten, fragen Sie einen verfügbar gemachten Endpunkt auf dem Emulator ab, während dieser ausgeführt wird. Für eine browserfreundliche Version verwenden Sie die folgende URL:

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

Dadurch werden Ihre Regeln in Ausdrücke und Unterausdrücke unterteilt, über die Sie mit der Maus fahren können, um weitere Informationen zu erhalten, einschließlich der Anzahl der Auswertungen und zurückgegebenen Werte. Für die JSON-Rohversion dieser Daten fügen Sie die folgende URL in Ihre Abfrage ein:

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

Hier hebt die HTML-Version des Berichts Auswertungen hervor, die undefinierte Fehler und Nullwertfehler auslösen:

Wie sich der Cloud Firestore-Emulator von der Produktion unterscheidet

Der Cloud Firestore-Emulator versucht, das Verhalten des Produktionsdiensts mit einigen bemerkenswerten Einschränkungen originalgetreu nachzubilden.

Unterstützung mehrerer Datenbanken für Cloud Firestore

Derzeit unterstützt die Emulator Suite-Benutzeroberfläche die interaktive Erstellung, Bearbeitung, Löschung, Anforderungsüberwachung und Sicherheitsvisualisierung für eine Standarddatenbank, jedoch nicht für zusätzliche benannte Datenbanken.

Allerdings erstellt der Emulator selbst eine benannte Datenbank basierend auf der Konfiguration in Ihrer Datei firebase.json und implizit als Reaktion auf SDK- oder REST-API-Aufrufe.

Transaktionen

Der Emulator implementiert derzeit nicht das gesamte Transaktionsverhalten, das in der Produktion auftritt. Wenn Sie Funktionen testen, die mehrere gleichzeitige Schreibvorgänge in ein Dokument umfassen, kann es sein, dass der Emulator Schreibanforderungen nur langsam abschließt. In manchen Fällen kann es bis zu 30 Sekunden dauern, bis die Sperren aufgehoben werden. Erwägen Sie bei Bedarf eine entsprechende Anpassung der Test-Timeouts.

Indizes

Der Emulator verfolgt keine zusammengesetzten Indizes und führt stattdessen jede gültige Abfrage aus. Testen Sie Ihre App unbedingt mit einer echten Cloud Firestore-Instanz, um festzustellen, welche Indizes Sie benötigen.

Grenzen

Der Emulator erzwingt nicht alle in der Produktion erzwungenen Grenzwerte. Beispielsweise kann der Emulator Transaktionen zulassen, die vom Produktionsdienst als zu groß abgelehnt würden. Stellen Sie sicher, dass Sie mit den dokumentierten Grenzwerten vertraut sind und dass Sie Ihre App so gestalten, dass diese proaktiv vermieden werden.

Was als nächstes?

• Eine kuratierte Reihe von Videos und detaillierten Anleitungsbeispielen finden Sie in der Firebase Emulators Training Playlist .
• Untersuchen Sie erweiterte Anwendungsfälle mit dem Testen von Sicherheitsregeln und dem Firebase Test SDK: Test Security Rules (Firestore) .
• Da ausgelöste Funktionen eine typische Integration mit Cloud Firestore sind, erfahren Sie mehr über den Cloud Functions for Firebase-Emulator unter Funktionen lokal ausführen .