Verbinden Sie Ihre App mit dem Cloud Firestore-Emulator

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

Wählen Sie ein Firebase-Projekt aus

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

Um das zu verwendende Projekt auszuwählen, bevor Sie die Emulatoren starten, führen Sie in der Befehlszeilenschnittstelle firebase use in Ihrem Arbeitsverzeichnis aus. Oder Sie können das Flag --project an jeden Emulatorbefehl übergeben.

Hinweis: Es empfiehlt sich im Allgemeinen, eine Projekt-ID für alle Emulatoraufrufe zu verwenden, damit die Benutzeroberfläche der Emulator Suite, verschiedene Produktemulatoren und alle ausgeführten Instanzen eines bestimmten Emulators in allen Fällen korrekt kommunizieren können. Tatsächlich warnt die Local Emulator Suite standardmäßig, wenn mehrere verwendete Projekt-IDs erkannt werden, obwohl Sie dieses Verhalten überschreiben können. Anleitungen zum Festlegen und Verwalten von Projekt-IDs finden Sie im Installations- und Konfigurationshandbuch .

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

Projekttyp	Merkmale	Verwenden Sie mit Emulatoren
Real	Ein echtes Firebase-Projekt ist eines, das Sie erstellt und konfiguriert haben (höchstwahrscheinlich über die Firebase-Konsole). Echte Projekte haben Live-Ressourcen wie Datenbankinstanzen, Speicher-Buckets, Funktionen oder andere Ressourcen, die Sie für dieses Firebase-Projekt eingerichtet haben.	Wenn Sie mit echten Firebase-Projekten arbeiten, können Sie Emulatoren für einige oder alle unterstützten Produkte ausführen. Bei allen Produkten, die Sie nicht emulieren, interagieren Ihre Apps und Ihr Code mit der Live- Ressource (Datenbankinstanz, Speicher-Bucket, Funktion usw.).
Demo	Ein Demo-Firebase-Projekt hat keine echte Firebase-Konfiguration und keine Live-Ressourcen. Auf diese Projekte wird normalerweise über Codelabs oder andere Tutorials zugegriffen. Projekt-IDs für Demo-Projekte haben das demo- Präfix.	Wenn Sie mit Firebase-Demoprojekten arbeiten, interagieren Ihre Apps und Ihr Code nur mit Emulatoren . Wenn Ihre App versucht, mit einer Ressource zu interagieren, für die kein Emulator ausgeführt wird, schlägt dieser Code fehl.

Wir empfehlen Ihnen, möglichst 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
• Besserer Offline-Support, da Sie nicht auf das Internet zugreifen müssen, um Ihre SDK-Konfiguration herunterzuladen.

Hinweis: Wenn Sie dienstübergreifende Interaktionen wie datenbankgetriggerte Cloud-Funktionen oder Regeln emulieren möchten, die auf Authentifizierung angewiesen sind, müssen Sie sicherstellen, dass die Projekt-ID in Ihrem Code (in initializeApp() usw.) mit der von verwendeten Projekt-ID übereinstimmt die Firebase-CLI.

Instrumentieren Sie Ihre App, um mit den Emulatoren zu kommunizieren

Android-, Apple-Plattformen und Web-SDKs

Richten Sie Ihre In-App-Konfiguration oder Testklassen für die Interaktion mit Cloud Firestore wie folgt ein.

Hinweis: Der Cloud Firestore-Emulator löscht Datenbankinhalte, wenn er heruntergefahren wird. Da der Offline-Cache des Firestore SDK nicht automatisch gelöscht wird, möchten Sie möglicherweise die lokale Persistenz in Ihrer Emulatorkonfiguration deaktivieren, um Diskrepanzen zwischen der emulierten Datenbank und den lokalen Caches zu vermeiden. im Web SDK ist Persistenz standardmäßig deaktiviert.

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 firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

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

Java

// 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

Schnell

let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web version 9

Erfahren Sie mehr über das modulare Web v9-SDK, das durch Baumstruktur erschüttert werden kann, und aktualisieren Sie es von Version 8.

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

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

Web version 8

Erfahren Sie mehr über das modulare Web v9-SDK, das durch Baumstruktur erschüttert werden kann, und aktualisieren Sie es von Version 8.

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

Es ist keine zusätzliche Einrichtung erforderlich, um Cloud Functions-Funktionen zu testen , die durch Firestore-Ereignisse mit dem Emulator ausgelöst werden . Wenn die Firestore- und Cloud Functions-Emulatoren beide 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="localhost:8080"

Wenn Ihr Code im Cloud Functions-Emulator ausgeführt wird, werden Ihre Projekt-ID und andere Konfigurationen beim Aufrufen initalizeApp automatisch festgelegt.

Wenn Sie möchten, dass Ihr Admin SDK-Code eine Verbindung zu einem freigegebenen 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.

Node.js-Admin-SDK

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

Umgebungsvariable

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 gibt Ihnen einen REST-Endpunkt speziell für diesen Zweck, der von einem Setup-/TearDown-Schritt eines Testframeworks, von einer Testklasse oder von der Shell (z , mit curl ), 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 aus und geben Sie Ihre Firebase-Projekt-ID, z. B. firestore-emulator-example , an den folgenden Endpunkt:

"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 oder fehlgeschlagen ist.

Sie können diese Operation von der Shell aus ausführen:

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

Nachdem Sie einen solchen Schritt implementiert haben, können Sie Ihre Tests sequenzieren und Ihre Funktionen in der Gewissheit auslösen, dass alte Daten zwischen den Läufen gelöscht werden und Sie eine neue Baseline-Testkonfiguration verwenden.

Daten importieren und exportieren

Mit der Datenbank und Cloud Storage for Firebase-Emulatoren können Sie Daten aus einer laufenden Emulatorinstanz exportieren. Definieren Sie einen Basisdatensatz zur Verwendung in Ihren Einheitentests oder kontinuierlichen Integrationsworkflows 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 Pfad verwenden, der an das Flag --import übergeben wird.

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 der 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 Benutzeroberfläche der Emulator Suite visualisieren, einschließlich Auswertungstrace 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 abzurufen, fragen Sie einen exponierten Endpunkt auf dem 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 Unterausdrücke unterteilt, über die Sie mit der Maus fahren können, um weitere Informationen anzuzeigen, einschließlich der Anzahl der zurückgegebenen Auswertungen und Werte. Für die rohe JSON-Version 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 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 zu replizieren.

Transaktionen

Der Emulator implementiert derzeit nicht das gesamte Transaktionsverhalten, das in der Produktion zu sehen ist. Wenn Sie Funktionen testen, die mehrere gleichzeitige Schreibvorgänge in ein Dokument beinhalten, kann der Emulator Schreibanforderungen nur langsam abschließen. In einigen Fällen kann es bis zu 30 Sekunden dauern, bis Sperren freigegeben werden. Erwägen Sie bei Bedarf eine entsprechende Anpassung der Testzeitüberschreitungen.

Indizes

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

Grenzen

Der Emulator erzwingt nicht alle in der Produktion erzwungenen Grenzen. 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 sie 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 fortgeschrittene Anwendungsfälle im Zusammenhang 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 .