Connecter votre application à l'émulateur Cloud Firestore

Avant de connecter votre application à l'émulateur Cloud Firestore, assurez-vous de comprendre le workflow global de la suite d'émulateurs locaux Firebase, d'installer et de configurer la suite d'émulateurs locaux et d'examiner ses commandes CLI.

Sélectionner un projet Firebase

La suite d'émulateurs locaux Firebase émule les produits d'un seul projet Firebase.

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

La suite d'émulateurs locaux permet l'émulation de projets Firebase réels et de projets de démonstration.

Type de projet Caractéristiques Utiliser avec des émulateurs
Situation réelle

Un vrai projet Firebase est un projet que vous avez créé et configuré (probablement via la console Firebase).

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

Lorsque vous utilisez des projets Firebase réels, vous pouvez exécuter des émulateurs pour tout ou partie des produits compatibles.

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

Démonstration

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

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

Lorsque vous utilisez des projets Firebase de démonstration, 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 en cours d'exécution, ce code échouera.

Nous vous recommandons d'utiliser des projets de démonstration dans la mesure du possible. Voici quelques-uns de ses avantages :

  • Configuration plus facile, puisque vous pouvez exécuter les émulateurs sans jamais créer de projet Firebase
  • Une sécurité renforcée, car si votre code appelle accidentellement des ressources non émulées (de production), il n'y a aucun risque de modification, d'utilisation et de facturation des données.
  • Meilleure compatibilité hors connexion, car il n'est pas nécessaire d'accéder à Internet pour télécharger la configuration du 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 une base de données nommée pour chaque configuration firestore de votre fichier firebase.json.

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

Pour utiliser vos bases de données par défaut et nommées de manière interactive dans l'interface utilisateur de la suite d'émulateurs, mettez à jour l'URL dans la barre d'adresse de votre navigateur pour sélectionner la base de données par défaut ou 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.

Plates-formes Android, Apple et SDK Web

Configurez vos classes de test ou de configuration dans l'application 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 obtenir des exemples impliquant des bases de données Cloud Firestore supplémentaires au-delà de la base de données par défaut, consultez le guide pour l'utilisation de 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);
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

API Web modulaire

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

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

API d'espace de noms Web

// 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 des fonctions Cloud déclenchées par des é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 Admin

Les SDK Admin Firebase 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 est exécuté dans l'émulateur Cloud Functions, votre ID de projet et d'autres configurations sont automatiquement définis lorsque vous appelez initializeApp.

Si vous souhaitez que le code de votre SDK Admin se connecte à un émulateur partagé exécuté dans un autre environnement, vous devez spécifier l'ID de projet 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 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 de SDK de plate-forme pour vider la base de données, mais l'émulateur Firestore fournit un point de terminaison REST spécialement conçu à cet effet. Il 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.

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 s'est terminé ou a é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"

Une fois cette étape effectuée, vous pouvez séquencer vos tests et déclencher vos fonctions en ayant l'assurance que les anciennes données seront définitivement supprimées entre les exécutions et que 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 à partir d'une instance d'émulateur en cours d'exécution. Définissez un ensemble de données de référence à utiliser dans vos tests unitaires ou vos workflows d'intégration continue, puis exportez-le pour le partager avec 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 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, consultez la documentation de référence sur les commandes de l'émulateur.

Visualiser l'activité liée aux règles de sécurité

Lorsque vous travaillez sur des boucles de prototypage et de test, vous pouvez utiliser les outils de visualisation et les rapports fournis par la suite d'émulateurs locaux.

Utiliser l'outil de surveillance des requêtes

L'émulateur Cloud Firestore vous permet de visualiser les requêtes client dans l'interface utilisateur de la suite d'émulateurs, y compris le traçage d'évaluation pour les règles de sécurité Firebase.

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 à l'aide des outils de débogage de la suite d'émulateurs locaux.

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 non définies et des valeurs nulles:

En quoi l'émulateur Cloud Firestore diffère-t-il de la production ?

L'émulateur Cloud Firestore tente de répliquer fidèlement le comportement du service de production, avec quelques limites notables.

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

Actuellement, l'interface utilisateur de la suite d'émulateurs permet de créer, modifier, supprimer, surveiller des requêtes et visualiser la sécurité de manière interactive pour une base de données par défaut, mais pas pour d'autres bases de données nommées.

Toutefois, l'émulateur lui-même crée une base de données nommée en fonction de 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 actuellement pas tous les comportements de transaction observés en production. Lorsque vous testez des fonctionnalités qui impliquent plusieurs écritures simultanées dans un document, l'émulateur peut mettre du temps à traiter les requêtes d'écriture. Dans certains cas, les verrouillages peuvent mettre jusqu'à 30 secondes à se déverrouiller. Envisagez d'ajuster les délais avant expiration des tests en conséquence, si nécessaire.

Index

L'émulateur ne suit pas les index composés, mais exécute toute 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 refusées comme trop volumineuses par le service de production. Assurez-vous de connaître les limites documentées et de concevoir votre application de manière à les éviter de manière proactive.

Quelles sont les prochaines étapes ?