Connecter votre application à l'émulateur Cloud Firestore

Avant de connecter votre application à l'émulateur Cloud Firestore, assurez-vous que vous comprenez le workflow Firebase Local Emulator Suite global, et que vous installez et configurez Local Emulator Suite et examinez ses commandes CLI.

Sélectionner un projet Firebase

Firebase Local Emulator Suite émule des produits pour un seul projet Firebase.

Pour sélectionner le projet à utiliser, avant de démarrer les émulateurs, exécutez la CLI dans la CLI firebase use dans votre répertoire de travail. Vous pouvez également transmettre L'indicateur --project sur chaque émulateur .

Local Emulator Suite est compatible avec l'émulation de projets Firebase réels et de projets de démonstration.

Type de projet Fonctionnalités Utiliser avec des émulateurs
Situation réelle

Un projet Firebase réel est un projet que vous avez créé et configuré via la console Firebase).

Les projets réels ont des ressources actives, telles que des instances de base de données, des espaces de stockage des buckets, des fonctions ou toute autre ressource configurée pour ce projet.

Lorsque vous travaillez sur de vrais projets Firebase, vous pouvez exécuter des émulateurs pour ou tous les produits pris en charge.

Pour tous les produits que vous n'émulez pas, vos applications et votre code interagissent avec la ressource en direct (instance de base de données, bucket de stockage, fonction, etc.).

Démo

Un projet Firebase de démonstration n'a pas de configuration Firebase réelle. aucune ressource active. Ces projets sont généralement accessibles via des ateliers de programmation ou d'autres tutoriels.

Les ID de projet des projets de démonstration portent le préfixe demo-.

Lorsque vous utilisez des projets Firebase de démonstration, vos applications et votre code interagissent avec émulateurs uniquement. Si votre application tente d'interagir avec une ressource pour laquelle aucun émulateur n'est en cours d'exécution, ce code échouera.

Nous vous recommandons d'utiliser des projets de démonstration autant que possible. Voici quelques-uns de ses avantages :

  • Configuration simplifiée, puisque vous pouvez exécuter les émulateurs sans avoir à créer Projet Firebase
  • Sécurité renforcée, car si votre code appelle accidentellement des ressources non émulées (de production), il n'y a aucune chance de modification, d'utilisation et de facturation des données.
  • Meilleure gestion hors connexion, puisqu'il n'est pas nécessaire d'accéder à Internet téléchargez la configuration de votre SDK.

Instrumenter votre application pour communiquer avec les émulateurs

Au démarrage, l'émulateur Cloud Firestore crée une base de données par défaut et un nom pour chaque configuration firestore de votre fichier firebase.json.

Les bases de données nommées sont également créées implicitement en réponse à tout SDK ou Appels de l'API REST à l'émulateur qui référencent une base de données spécifique. Telles les bases de données créées implicitement fonctionnent avec des règles ouvertes.

Pour travailler avec vos bases de données par défaut et nommées de manière interactive dans le Emulator Suite UI, dans la barre d'adresse de votre navigateur, mettez à jour l'URL pour sélectionner soit la base de données par défaut, soit une base de données nommée.

  • Par exemple, pour parcourir les données de votre instance par défaut, remplacez l'URL par localhost:4000/firestore/default/data
  • Pour parcourir une instance nommée ecommerce, passez à localhost:4000/firestore/ecommerce/data

Android, plates-formes Apple et SDK Web

Définissez la configuration dans l'application ou les classes de test avec lesquelles interagir. Cloud Firestore comme suit. Notez que dans les exemples suivants, le code de l'application se connecte à la base de données du projet par défaut. Pour les exemples impliquant des ressources Cloud Firestore autres que la base de données par défaut, reportez-vous à guide pour plusieurs bases de données.

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
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web

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

Web

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

Aucune configuration supplémentaire n'est requise pour tester Cloud Functions déclenchés par des événements Firestore à l'aide de l'émulateur. Lorsque les émulateurs Firestore et Cloud Functions sont tous deux ils fonctionnent automatiquement ensemble.

Admin SDK s

Les Firebase Admin SDK se connectent automatiquement au Cloud Firestore. émulateur lorsque la variable d'environnement FIRESTORE_EMULATOR_HOST est définie:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Si votre code s'exécute dans l'émulateur Cloud Functions, l'ID de votre projet et d'autres configurations sont automatiquement définies lors de l'appel de initializeApp.

Si vous souhaitez que votre code Admin SDK se connecte à un émulateur partagé s'exécutant dans dans un autre environnement, vous devez spécifier le même ID de projet que celui défini à l'aide de la CLI Firebase. Vous pouvez transmettre directement un ID de projet à initializeApp ou définir le GCLOUD_PROJECT.

SDK Admin Node.js
admin.initializeApp({ projectId: "your-project-id" });
Variable d'environnement
export GCLOUD_PROJECT="your-project-id"

Effacer votre base de données entre les tests

Firestore de production ne fournit aucune méthode SDK de plate-forme pour vider la base de données, mais l'émulateur Firestore vous fournit un point de terminaison REST spécifiquement conçu à cet effet, qui peut être appelé à partir d'une étape de configuration/suppression du framework de test, d'une classe de test ou du shell (par exemple, avec curl) avant le lancement d'un test. Vous pouvez utiliser cette approche au lieu d'arrêter simplement le processus de l'émulateur.

Pour utiliser une méthode appropriée, effectuez une opération HTTP DELETE en fournissant votre ID du projet Firebase, par exemple firestore-emulator-example, à l'ID point de terminaison:

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

Naturellement, votre code doit attendre la confirmation REST indiquant que le vidage est terminé ou échoué.

Vous pouvez effectuer cette opération à partir du shell :

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

Après avoir implémenté une telle étape, vous pouvez séquencer vos tests et déclencher vos fonctions avec l'assurance que les anciennes données seront définitivement supprimées entre les exécutions vous utilisez une nouvelle configuration de test de référence.

Importer et exporter des données

La base de données et les émulateurs Cloud Storage for Firebase vous permettent d'exporter des données depuis une instance d'émulateur en cours d'exécution. Définissez un ensemble de données de référence à utiliser dans votre des tests unitaires ou des workflows d'intégration continue, puis exportez-les pour les partager au sein de l'équipe.

firebase emulators:export ./dir

Lors des tests, au démarrage de l'émulateur, importez les données de référence.

firebase emulators:start --import=./dir

Vous pouvez demander à l'émulateur d'exporter des données à l'arrêt, en spécifiant un chemin d'exportation ou simplement en utilisant le chemin d'accès transmis à l'indicateur --import.

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

Ces options d'importation et d'exportation de données sont compatibles firebase emulators:exec. Pour en savoir plus, consultez documentation de référence sur les commandes de l'émulateur.

Visualiser l'activité des règles de sécurité

Lorsque vous travaillez sur les prototypes et les boucles de test, vous pouvez utiliser des outils de visualisation et les rapports fournis par Local Emulator Suite.

Utiliser la surveillance des requêtes

L'émulateur Cloud Firestore vous permet de visualiser les requêtes client dans Emulator Suite UI, y compris le traçage d'évaluation pour Firebase Security Rules.

Ouvrez l'onglet Firestore > Requêtes pour afficher la séquence d'évaluation détaillée de chaque requête.

Surveillance des requêtes de l'émulateur Firestore affichant les évaluations des règles de sécurité

Visualiser les rapports d'évaluation des règles

Lorsque vous ajoutez des règles de sécurité à votre prototype, vous pouvez les déboguer avec Outils de débogage Local Emulator Suite

Après avoir exécuté une suite de tests, vous pouvez accéder à des rapports sur la couverture des tests qui montrent comment chacune de vos règles de sécurité a été évaluée.

Pour obtenir les rapports, interrogez un point de terminaison exposé sur l'émulateur pendant son exécution. Pour une version adaptée aux navigateurs, utilisez l'URL suivante :

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

Cette opération casse vos règles en expressions et sous-expressions que vous pouvez survoler avec la souris pour obtenir plus d'informations, y compris le nombre d'évaluations et les valeurs renvoyées. Pour la version JSON brute de ces données, incluez l'URL suivante dans votre requête :

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

Ici, la version HTML du rapport met en évidence les évaluations qui génèrent des erreurs de valeur nulle et non définie :

Différences entre l'émulateur Cloud Firestore et la production

L'émulateur Cloud Firestore tente de reproduire fidèlement le comportement du service de production, avec certaines limitations notables.

Compatibilité avec plusieurs bases de données pour Cloud Firestore

Actuellement, Emulator Suite UI permet de créer, de modifier, de modifier la suppression, la surveillance des requêtes et la visualisation de la sécurité pour une base de données par défaut, mais pas de bases de données nommées supplémentaires.

Cependant, l'émulateur lui-même crée une base de données nommée en fonction du dans votre fichier firebase.json et implicitement en réponse au SDK ou Appels d'API REST.

Transactions

Actuellement, l'émulateur n'implémente pas tous les comportements de transaction observées en production. Lorsque vous testez des fonctionnalités impliquant plusieurs écritures simultanées dans un même document, l'émulateur peut être lent à traiter les requêtes d'écriture. Dans certains cas, le déverrouillage peut prendre jusqu'à 30 secondes. Envisagez d'ajuster les délais avant expiration des tests en conséquence, si nécessaire.

Index

L'émulateur n'effectue pas le suivi des index composés, mais exécute les requête valide. Veillez à tester votre application sur une instance Cloud Firestore réelle pour déterminer les index dont vous aurez besoin.

Limites

L'émulateur n'applique pas toutes les limites appliquées en production. Par exemple, l'émulateur peut autoriser des transactions qui seraient rejetées comme étant trop volumineuses par le service de production. Veillez à bien connaître les limites documentées et que vous concevez votre application pour les éviter de manière proactive.

Et maintenant ?