Connectez votre application à l'émulateur Cloud Firestore

Avant de connecter votre application à l'émulateur Cloud Firestore, assurez-vous de bien comprendre le flux de travail global de Firebase Local Emulator Suite , d' installer et de configurer Local Emulator Suite et de consulter ses commandes CLI .

Choisissez un projet Firebase

La suite Firebase Local Emulator émule les produits pour un seul projet Firebase.

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

Local Emulator Suite prend en charge l'émulation de projets Firebase réels et de projets de démonstration .

Type de projet Caractéristiques Utiliser avec des émulateurs
Réel

Un vrai projet Firebase est celui que vous avez créé et configuré (très probablement via la console Firebase).

Les projets réels disposent de ressources actives, telles que des instances de base de données, des compartiments de stockage, des fonctions ou toute autre ressource que vous avez configurée pour ce projet Firebase.

Lorsque vous travaillez avec de vrais projets Firebase, vous pouvez exécuter des émulateurs pour tout ou partie des produits pris en charge.

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

Démo

Un projet de démonstration Firebase n'a pas de véritable configuration Firebase ni de ressources actives. Ces projets sont généralement accessibles via des ateliers de programmation ou d'autres didacticiels.

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

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

Nous vous recommandons d'utiliser des projets de démonstration dans la mesure du possible. Les avantages comprennent :

  • Configuration plus simple, puisque vous pouvez exécuter les émulateurs sans jamais créer de projet Firebase
  • Sécurité renforcée, car si votre code appelle accidentellement des ressources (de production) non émulées, il n'y a aucune chance de modification, d'utilisation et de facturation des données.
  • Meilleure prise en charge hors ligne, puisqu'il n'est pas nécessaire d'accéder à Internet pour télécharger la configuration de votre SDK.

Instrumentez 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 une base de données nommée pour chaque configuration firestore dans votre fichier firebase.json . Utilisez votre fichier firebase.json pour attribuer explicitement des règles de sécurité Cloud Firestore à une base de données nommée.

Les bases de données nommées sont également créées implicitement en réponse à tout appel du SDK ou de l'API REST à l'émulateur faisant référence à une base de données spécifique. Ces bases de données créées implicitement fonctionnent avec des règles ouvertes .

Actuellement, l'interface utilisateur d'Emulator Suite prend en charge le travail interactif avec la base de données par défaut .

Plateformes Android, Apple et SDK Web

Configurez votre configuration dans l'application ou testez vos classes pour interagir avec 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 des exemples impliquant des bases de données Cloud Firestore supplémentaires au-delà de la base de données par défaut, reportez-vous au 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
}
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);
Rapide
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Web modular API

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

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

Web namespaced API

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

Aucune configuration supplémentaire n'est nécessaire pour tester les fonctions Cloud déclenchées par les événements Firestore à l'aide de l'émulateur. Lorsque les émulateurs Firestore et Cloud Functions sont tous deux en cours d'exécution, ils fonctionnent automatiquement ensemble.

SDK d'administration

Les SDK Firebase Admin se connectent automatiquement à l'émulateur Cloud Firestore 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, votre ID de projet et d'autres configurations sont automatiquement définis lors de l'appel initializeApp .

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

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

Effacez votre base de données entre les tests

Production Firestore 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 à cet effet, qui peut être appelé à partir d'une étape de configuration/démontage du framework de test, à partir d'une classe de test ou à partir du shell (par exemple , avec curl ) avant le lancement d'un test. Vous pouvez utiliser cette approche comme alternative à la simple fermeture du processus d'émulateur.

Dans une méthode appropriée, effectuez une opération HTTP DELETE, en fournissant votre ID de projet Firebase, par exemple firestore-emulator-example , au point de terminaison suivant :

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

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

Vous pouvez effectuer cette opération depuis le shell :

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

Après avoir mis en œuvre une étape comme celle-ci, vous pouvez séquencer vos tests et déclencher vos fonctions avec la certitude que les anciennes données seront purgées entre les exécutions et que vous utilisez une nouvelle configuration de test de base.

Importer et exporter des données

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

firebase emulators:export ./dir

Dans les tests, au démarrage de l'émulateur, importez les données de base.

firebase emulators:start --import=./dir

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

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

Ces options d'importation et d'exportation de données fonctionnent également avec la commande firebase emulators:exec . Pour en savoir plus, reportez-vous à la référence des commandes d'émulateur .

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

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

Utiliser le moniteur de demandes

L'émulateur Cloud Firestore vous permet de visualiser les demandes des clients dans l'interface utilisateur d'Emulator Suite, y compris le suivi d'évaluation des règles de sécurité Firebase.

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

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

Visualisez les rapports d'évaluation des règles

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

Après avoir exécuté une suite de tests, vous pouvez accéder aux rapports de 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 conviviale pour le navigateur, utilisez l'URL suivante :

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

Cela divise vos règles en expressions et sous-expressions sur lesquelles vous pouvez passer la souris pour 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 non définies et de valeur nulle :

En quoi l'émulateur Cloud Firestore diffère de la production

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

Prise en charge de plusieurs bases de données pour Cloud Firestore

Actuellement, l'interface utilisateur d'Emulator Suite prend en charge la création, la modification, la suppression, la surveillance des demandes et la visualisation de la sécurité interactives pour une base de données par défaut, mais pas pour les bases de données nommées supplémentaires.

Cependant, l'émulateur lui-même crée une base de données nommée basée sur la configuration de votre fichier firebase.json et implicitement en réponse aux appels du SDK ou de l'API REST.

Transactions

L'émulateur n'implémente pas actuellement tous les comportements de transaction observés en production. Lorsque vous testez des fonctionnalités qui impliquent plusieurs écritures simultanées sur un même document, l'émulateur peut être lent à terminer les demandes d'écriture. Dans certains cas, le déverrouillage peut prendre jusqu'à 30 secondes. Envisagez d'ajuster les délais d'attente des tests en conséquence, si nécessaire.

Index

L'émulateur ne suit pas les index composés et exécutera à la place toute requête valide. Assurez-vous de tester votre application par rapport à une véritable instance Cloud Firestore 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 trop volumineuses par le service de production. Assurez-vous de connaître les limites documentées et de concevoir votre application pour les éviter de manière proactive.

Et ensuite ?