Connecter votre application à l'émulateur Cloud Firestore

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

Choisir un projet Firebase

Le 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 firebase use dans votre répertoire de travail dans la CLI. Vous pouvez également transmettre l'option --project à chaque commande d'é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 Utilisation avec des émulateurs
Situation réelle

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

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

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

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

Démonstration

Un projet Firebase de démonstration ne comporte aucune configuration Firebase réelle ni aucune ressource en direct. 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 sont précédés du préfixe demo-.

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

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

  • Configuration plus facile, car 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 non émulées (de production), il n'y a aucun risque de modification des données, d'utilisation ni de facturation
  • Meilleure compatibilité hors connexion, car il n'est pas nécessaire d'accéder à Internet pour télécharger la configuration de votre SDK.
Cloud Functions

Instrumenter votre application pour qu'elle communique 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 firebase.json fichier.

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

Pour interagir 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 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, remplacez l'URL par localhost:4000/firestore/ecommerce/data.

Démarrer l'émulateur dans une édition spécifique

L'émulateur démarre dans l'édition spécifiée dans la firestore.edition section de votre firebase.json fichier. Vous pouvez également spécifier une édition dans la section emulators.firestore.edition de votre fichier firebase.json. Les valeurs valides pour l'édition sont standard et enterprise. Si vous spécifiez edition dans les deux configurations, alors emulators.firestore.edition est prioritaire.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

SDK Android, Apple et Web

Configurez vos classes de configuration ou de test intégrées à 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 supplémentaires au-delà de la base de données par défaut, consultez le guide sur plusieurs bases de données.Cloud Firestore

Kotlin
// 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 nécessaire pour tester les fonctions Cloud Functions 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.

Admin SDKs

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

Si vous souhaitez que votre code Admin SDK se connecte à un émulateur partagé s'exécutant dans un autre environnement, vous devez spécifier le même ID de projet que celui que vous avez défini à l'aide de la CLI Firebase. Vous pouvez transmettre un ID de projet directement à 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"

API REST Cloud Firestore

L'émulateur Cloud Firestore fournit un point de terminaison REST pour interagir avec votre base de données. Tous les appels d'API REST doivent être effectués vers le point de terminaison http://localhost:8080/v1.

Le chemin d'accès complet d'un appel REST suit le modèle suivant :

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

Par exemple, pour lister tous les documents de la collection users du projet my-project-id, vous pouvez utiliser curl :

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

Effacer votre base de données entre les tests

Firestore en production ne fournit aucune méthode SDK de plate-forme pour vider la base de données, mais l'émulateur Firestore vous offre 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 à l'arrêt simple du processus d'émulateur.

Dans une méthode appropriée, effectuez une opération HTTP DELETE en fournissant l'ID de votre 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 a réussi 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"

Une fois cette étape implémentée, vous pouvez séquencer vos tests et déclencher vos fonctions en toute confiance, car les anciennes données seront supprimées entre les exécutions et vous utiliserez 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 des données à l'arrêt, en spécifiant un chemin d'exportation ou en utilisant simplement le chemin transmis à l'option --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 la commande d'émulateur.

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

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

Utiliser l'outil de surveillance des requêtes

L'Cloud Firestore émulateur vous permet de visualiser les requêtes des clients dans l'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 à l'aide des Local Emulator Suite outils de débogage.

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 non définie et nulle :

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 quelques limites notables.

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

Actuellement, le Emulator Suite UI est compatible avec la création, la modification, la suppression, la surveillance des requêtes 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.

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 de manière implicite en réponse aux appels d'API SDK ou REST.

Transactions

L'émulateur n'implémente pas actuellement tous les comportements de transaction observés en production. Lorsque vous testez des fonctionnalités impliquant plusieurs écritures simultanées dans un même document, l'émulateur peut être lent à terminer les requêtes d'écriture. Dans certains cas, les verrous peuvent mettre jusqu'à 30 secondes à être libérés. Si nécessaire, envisagez d'ajuster les délais d'attente des tests en conséquence.

Index

L'émulateur ne suit pas les index composites et exécute à la place toute requête valide. Assurez-vous de tester votre application par rapport à 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. Assurez-vous de connaître les limites documentées et de concevoir votre application de manière à les éviter de manière proactive.

Et maintenant ?