Connectez votre application à l'émulateur Cloud Firestore

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

Choisissez un projet Firebase

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

Pour sélectionner le projet à utiliser, avant de démarrer les émulateurs, dans la CLI, exécutez firebase use dans votre répertoire de travail. Ou, vous pouvez passer l'indicateur --project à chaque commande de l'é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 ont des 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 en direct. 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 ont le préfixe demo- .

Lorsque vous travaillez avec 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 un émulateur n'est pas en cours d'exécution, ce code échouera.

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

  • 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 invoque 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 prise en charge hors ligne, car il n'est pas nécessaire d'accéder à Internet pour télécharger votre configuration SDK.

Instrumentez votre application pour parler aux émulateurs

Plateformes Android, Apple et SDK Web

Configurez votre configuration dans l'application ou testez les classes pour interagir avec Cloud Firestore comme suit.

Android
        // 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 = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Web version 9

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

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

Web version 8

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

Aucune configuration supplémentaire n'est nécessaire pour tester les fonctions Cloud Functions déclenchées par les événements Firestore à l'aide de l'émulateur. Lorsque les émulateurs Firestore et Cloud Functions sont 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="localhost:8080"

Si votre code s'exécute dans l'émulateur Cloud Functions, votre ID de projet et une autre configuration seront automatiquement définis lors de l'appel initalizeApp .

Si vous souhaitez que votre code SDK Admin se connecte à un émulateur partagé s'exécutant dans un autre environnement, vous devrez 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 à initializeApp directement 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"

Videz 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 donne un point de terminaison REST spécifiquement à cette fin, 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 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 depuis le 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 étape comme celle-ci, vous pouvez séquencer vos tests et déclencher vos fonctions en toute confiance que les anciennes données seront purgé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 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 workflows d'intégration continue, puis exportez-le pour le partager avec l'équipe.

firebase emulators:export ./dir

Dans les 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 passé à 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 firebase emulators:exec . Pour plus d'informations, reportez-vous à la référence des commandes de l'émulateur .

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

Lorsque vous travaillez sur des prototypes et des boucles de test, 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 de l'é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 requête.

Firestore Emulator Requests Monitor 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 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 les navigateurs, utilisez l'URL suivante :

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

Cela décompose vos règles en expressions et sous-expressions que vous pouvez survoler avec 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 renvoient des erreurs indé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.

Transactions

L'émulateur n'implémente pas actuellement tous les comportements de transaction vus en production. Lorsque vous testez des fonctionnalités qui impliquent plusieurs écritures simultanées dans un document, l'émulateur peut être lent à traiter les demandes d'écriture. Dans certains cas, les verrous peuvent prendre jusqu'à 30 secondes pour être libérés. Envisagez d'ajuster les délais de test en conséquence, si nécessaire.

Index

L'émulateur ne suit pas les index composés et exécute à la place toute requête valide. Assurez-vous de tester votre application par rapport à une instance réelle de 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 importantes par le service de production. Assurez-vous que vous connaissez les limites documentées et que vous concevez votre application pour les éviter de manière proactive.

Et ensuite ?