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 .

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.

// 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

// 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

let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

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

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

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

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 .

admin.initializeApp({ projectId: "your-project-id" });

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 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 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 commande 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.

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 ?

• Pour un ensemble de vidéos organisées et des exemples détaillés de procédures, suivez la liste de lecture de formation Firebase Emulators .
• Étudiez des cas d'utilisation avancés impliquant des tests de règles de sécurité et le SDK de test Firebase : testez les règles de sécurité (Firestore) .
• Étant donné que les fonctions déclenchées sont une intégration typique avec Cloud Firestore, apprenez-en plus sur l'émulateur Cloud Functions pour Firebase sur Exécuter les fonctions localement .