Installer, configurer et intégrer la suite d'émulateurs locaux

La suite d'émulateurs locaux Firebase peut être installée et configurée pour différents environnements de prototypage et de test, allant de sessions de prototypage ponctuelles à des workflows d'intégration continue à l'échelle de la production.

Installer la suite d'émulateurs locaux

Avant d'installer la suite d'émulateurs, vous devez disposer des éléments suivants:

  • Node.js version 16.0 ou ultérieure
  • JDK Java version 11 ou ultérieure

Pour installer la suite d'émulateurs:

  1. Installez la CLI Firebase. Si la CLI Firebase n'est pas déjà installée, installez-la maintenant. Vous devez disposer de la version 8.14.0 ou ultérieure de la CLI pour utiliser la suite d'émulateurs. Vous pouvez vérifier la version installée à l'aide de la commande suivante : 
    firebase --version
  2. Si vous ne l'avez pas déjà fait, initialisez le répertoire de travail actuel en tant que projet Firebase, en suivant les instructions à l'écran pour spécifier les produits à utiliser : 
    firebase init
  3. Configurez la suite d'émulateurs. Cette commande lance un assistant de configuration qui vous permet de sélectionner les émulateurs qui vous intéressent, de télécharger les fichiers binaires correspondants et de définir les ports de l'émulateur si les valeurs par défaut ne sont pas appropriées. 
    firebase init emulators

Une fois un émulateur installé, aucune vérification de mise à jour n'est effectuée et aucun téléchargement automatique supplémentaire n'a lieu tant que vous n'avez pas mis à jour la version de la CLI Firebase.

Configurer la suite d'émulateurs

Vous pouvez éventuellement configurer les ports réseau des émulateurs et le chemin d'accès aux définitions des règles de sécurité dans le fichier firebase.json:

  • Modifiez les ports de l'émulateur en exécutant firebase init emulators ou en modifiant firebase.json manuellement.
  • Modifiez le chemin d'accès aux définitions des règles de sécurité en modifiant firebase.json manuellement.

Si vous ne configurez pas ces paramètres, les émulateurs écouteront sur leurs ports par défaut, et les émulateurs Cloud Firestore, Realtime Database et Cloud Storage for Firebase s'exécuteront avec une sécurité des données ouverte.

Commande Description
Émulateurs init Lancez un assistant d'initialisation de l'émulateur. Identifiez les émulateurs à installer et spécifiez éventuellement les paramètres de port de l'émulateur. init emulators est non destructif. L'acceptation des valeurs par défaut permet de conserver la configuration actuelle de l'émulateur.

Configuration des ports

Chaque émulateur se lie à un port différent de votre machine avec une valeur par défaut préférée.

Émulateur Port par défaut
Authentication 9099
Emulator Suite UI 4000
Cloud Functions 5001
Eventarc 9299
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage for Firebase 9199
Firebase Hosting 5000
Pub/Sub 8085

Configuration de l'ID de projet

Selon la manière dont vous appelez les émulateurs, vous pouvez exécuter plusieurs instances d'un émulateur à l'aide d'ID de projet Firebase différents ou plusieurs instances d'émulateur pour un ID de projet donné. Dans ce cas, les instances d'émulateur s'exécutent dans un environnement distinct.

Il est généralement recommandé de définir un ID de projet pour toutes les invocations d'émulateur afin que Emulator Suite UI, les différents émulateurs de produits et toutes les instances en cours d'exécution d'un émulateur particulier puissent communiquer correctement dans tous les cas.

Local Emulator Suite émet des avertissements lorsqu'il détecte plusieurs ID de projet dans l'environnement. Toutefois, vous pouvez remplacer ce comportement en définissant la clé singleProjectMode sur false dans votre firebase.json.

Vous pouvez vérifier les déclarations d'ID de projet pour détecter les incohérences dans:

  • Projet par défaut dans la ligne de commande. Par défaut, l'ID de projet est extrait au démarrage du projet sélectionné avec firebase init ou firebase use. Pour afficher la liste des projets (et voir celui qui est sélectionné), utilisez firebase projects:list.
  • Tests unitaires des règles L'ID de projet est souvent spécifié dans les appels aux méthodes de la bibliothèque de test unitaire des règles initializeTestEnvironment ou initializeTestApp.
  • Option --project de la ligne de commande. Transmettre l'option --project de la CLI Firebase remplace le projet par défaut. Vous devez vous assurer que la valeur de l'indicateur correspond à l'ID du projet dans les tests unitaires et l'initialisation de l'application.

Vérifiez également les configurations d'ID de projet spécifiques à la plate-forme que vous avez définies lors de la configuration de vos projets Apple, Android et Web.

Configuration des règles de sécurité

Les émulateurs utiliseront la configuration des règles de sécurité à partir des clés de configuration database, firestore et storage dans firebase.json.

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

Spécifier des options Java

L'émulateur Realtime Database, l'émulateur Cloud Firestore et une partie de l'émulateur Cloud Storage for Firebase sont basés sur Java, qui peut être personnalisé avec des indicateurs JVM via la variable d'environnement JAVA_TOOL_OPTIONS.

Par exemple, si vous rencontrez des erreurs liées à l'espace de tas Java, vous pouvez augmenter la taille maximale du tas Java à 4 Go:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

Vous pouvez spécifier plusieurs options entre guillemets, séparées par des espaces, comme JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". Les indicateurs ne concernent que les composants Java des émulateurs et n'ont aucun effet sur les autres parties de la CLI Firebase, telles que Emulator Suite UI.

Démarrer les émulateurs

Vous pouvez démarrer des émulateurs pour qu'ils s'exécutent jusqu'à ce qu'ils soient arrêtés manuellement, ou pour qu'ils s'exécutent pendant la durée d'un script de test désigné, puis qu'ils s'arrêtent automatiquement.

Commande Description
emulators:start Démarrez les émulateurs pour les produits Firebase configurés dans firebase.json. Les processus de l'émulateur continuent de s'exécuter jusqu'à ce qu'ils soient arrêtés explicitement. L'appel de emulators:start télécharge les émulateurs dans ~/.cache/firebase/emulators/ s'ils ne sont pas déjà installés.
Option Description
--only Facultatif. Limitez les émulateurs qui démarrent. Fournissez une liste de noms d'émulateurs séparés par une virgule, en spécifiant un ou plusieurs des éléments suivants : "auth", "database", "firestore", "functions", "hosting" ou "pubsub".
--inspect-functions debug_port Facultatif. À utiliser avec l'émulateur Cloud Functions pour activer le débogage des points d'arrêt des fonctions sur le port spécifié (ou le port par défaut 9229 si l'argument est omis). Notez que lorsque cet indicateur est fourni, l'émulateur Cloud Functions passe à un mode d'exécution sérialisé spécial dans lequel les fonctions sont exécutées dans un seul processus, dans l'ordre séquentiel (FIFO). Cela simplifie le débogage des fonctions, bien que le comportement diffère de l'exécution parallèle multiprocessus des fonctions dans le cloud.
--export-on-exit= Facultatif. À utiliser avec l'émulateur Authentication, Cloud Firestore, Realtime Database ou Cloud Storage for Firebase. Indique aux émulateurs d'exporter les données vers un répertoire lors de l'arrêt, comme décrit pour la commande emulators:export. Le répertoire d'exportation peut être spécifié avec l'option suivante : firebase emulators:start --export-on-exit=./saved-data. Si --import est utilisé, le chemin d'exportation est le même par défaut (par exemple, firebase emulators:start --import=./data-path --export-on-exit). Enfin, si vous le souhaitez, transmettez différents chemins d'accès aux indicateurs --import et --export-on-exit.
--import=import_directory Facultatif. À utiliser avec l'émulateur Authentication, Cloud Firestore, Realtime Database ou Cloud Storage for Firebase. Importez les données enregistrées à l'aide de l'option de démarrage --export-on-exit ou de la commande emulators:export dans une instance d'émulateur Authentication, Cloud Firestore, Realtime Database ou Cloud Storage for Firebase en cours d'exécution. Toutes les données actuellement dans la mémoire de l'émulateur seront écrasées.
emulators:exec scriptpath Exécutez le script à scriptpath après avoir démarré les émulateurs pour les produits Firebase configurés dans firebase.json. Les processus de l'émulateur s'arrêtent automatiquement lorsque l'exécution du script est terminée.
Option Description
--only Facultatif. Limitez les émulateurs qui démarrent. Fournissez une liste de noms d'émulateurs séparés par une virgule, en spécifiant un ou plusieurs des éléments suivants : "firestore", "database", "functions", "hosting" ou "pubsub".
--inspect-functions debug_port Facultatif. À utiliser avec l'émulateur Cloud Functions pour activer le débogage des points d'arrêt des fonctions sur le port spécifié (ou le port par défaut 9229 si l'argument est omis). Notez que lorsque cet indicateur est fourni, l'émulateur Cloud Functions passe à un mode d'exécution sérialisé spécial dans lequel les fonctions sont exécutées dans un seul processus, dans l'ordre séquentiel (FIFO). Cela simplifie le débogage des fonctions, mais le comportement diffère de l'exécution parallèle multiprocessus des fonctions dans le cloud.
--export-on-exit= Facultatif. À utiliser avec l'émulateur Authentication, Cloud Firestore, Realtime Database ou Cloud Storage for Firebase. Indique aux émulateurs d'exporter les données vers un répertoire lors de l'arrêt, comme décrit pour la commande emulators:export. Le répertoire d'exportation peut être spécifié avec l'option suivante : firebase emulators:start --export-on-exit=./saved-data. Si --import est utilisé, le chemin d'exportation est le même par défaut (par exemple, firebase emulators:start --import=./data-path --export-on-exit). Enfin, si vous le souhaitez, transmettez différents chemins d'accès aux indicateurs --import et --export-on-exit.
--import=import_directory Facultatif. À utiliser avec l'émulateur Authentication, Cloud Firestore, Realtime Database ou Cloud Storage for Firebase. Importez les données enregistrées à l'aide de l'option de démarrage --export-on-exit ou de la commande emulators:export dans une instance d'émulateur Authentication, Cloud Firestore, Realtime Database ou Cloud Storage for Firebase en cours d'exécution. Toutes les données actuellement dans la mémoire de l'émulateur seront écrasées.
--ui Facultatif. Exécutez l'UI de l'émulateur pendant l'exécution.

La méthode firebase emulators:exec est généralement plus adaptée aux workflows d'intégration continue.

Exporter et importer des données de l'émulateur

Vous pouvez exporter des données à partir des émulateurs Authentication, Cloud Firestore, Realtime Database et Cloud Storage for Firebase pour les utiliser comme ensemble de données de référence commun et partageable. Ces ensembles de données peuvent être importés à l'aide de l'indicateur --import, comme décrit ci-dessus.

emulators:export export_directory

Émulateur Authentication, Cloud Firestore, Realtime Database ou Cloud Storage for Firebase Exporter des données à partir d'une instance d'émulateur Cloud Firestore, Realtime Database ou Cloud Storage for Firebase en cours d'exécution Le export_directory spécifié sera créé s'il n'existe pas déjà. Si le répertoire spécifié existe, vous êtes invité à confirmer que les données d'exportation précédentes doivent être écrasées. Vous pouvez ignorer cette invite à l'aide de l'indicateur --force. Le répertoire d'exportation contient un fichier manifeste de données, firebase-export-metadata.json.

Vous pouvez demander aux émulateurs d'exporter automatiquement les données lorsqu'ils s'arrêtent à l'aide des indicateurs --export-on-exit décrits ci-dessus.

Intégrer votre système CI

Exécuter des images de la suite d'émulateurs conteneurisées

L'installation et la configuration de la suite d'émulateurs avec des conteneurs dans une configuration CI typique sont simples.

Voici quelques points à prendre en compte:

  • Les fichiers JAR sont installés et mis en cache dans ~/.cache/firebase/emulators/.

    • Vous pouvez ajouter ce chemin à la configuration de votre cache CI pour éviter les téléchargements répétés.

  • Si vous ne disposez pas d'un fichier firebase.json dans votre dépôt, vous devez ajouter un argument de ligne de commande à la commande emulators:start ou emulators:exec pour spécifier les émulateurs à démarrer. Par exemple,
    --only functions,firestore.

Générer un jeton d'authentification (émulateur d'hébergement uniquement)

Si vos workflows d'intégration continue reposent sur Firebase Hosting , vous devez vous connecter à l'aide d'un jeton pour exécuter firebase emulators:exec. Les autres émulateurs ne nécessitent aucune connexion.

Pour générer un jeton, exécutez firebase login:ci dans votre environnement local. Cette opération ne doit pas être effectuée à partir d'un système CI. Suivez les instructions pour vous authentifier. Vous ne devriez avoir besoin d'effectuer cette étape qu'une seule fois par projet, car le jeton sera valide pour tous les builds. Le jeton doit être traité comme un mot de passe. Veillez à le garder secret.

Si votre environnement de CI vous permet de spécifier des variables d'environnement pouvant être utilisées dans les scripts de compilation, créez simplement une variable d'environnement appelée FIREBASE_TOKEN, dont la valeur est la chaîne de jeton d'accès. La CLI Firebase détecte automatiquement la variable d'environnement FIREBASE_TOKEN, et les émulateurs démarrent correctement.

En dernier recours, vous pouvez simplement inclure le jeton dans votre script de compilation, mais assurez-vous que les parties non approuvées n'y ont pas accès. Pour cette approche codée en dur, vous pouvez ajouter --token "YOUR_TOKEN_STRING_HERE" à la commande firebase emulators:exec.

Utiliser l'API REST de l'émulateur Hub

Lister les émulateurs en cours d'exécution

Pour lister les émulateurs actuellement en cours d'exécution, envoyez une requête GET au point de terminaison /emulators du hub d'émulateurs.

curl localhost:4400/emulators

Le résultat est un objet JSON listant tous les émulateurs en cours d'exécution et leur configuration hôte/port, par exemple:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

Activer / Désactiver les déclencheurs de fonctions en arrière-plan

Dans certains cas, vous devrez désactiver temporairement les déclencheurs de fonctions locales et d'extensions. Par exemple, vous pouvez supprimer toutes les données de l'émulateur Cloud Firestore sans déclencher de fonctions onDelete exécutées dans les émulateurs Cloud Functions ou Extensions.

Pour désactiver temporairement les déclencheurs de fonctions locales, envoyez une requête PUT au point de terminaison /functions/disableBackgroundTriggers du hub de l'émulateur.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

Le résultat est un objet JSON détaillant l'état actuel.

{
  "enabled": false
}

Pour activer les déclencheurs de fonction locaux après leur désactivation, envoyez une requête PUT au point de terminaison /functions/enableBackgroundTriggers du hub de l'émulateur.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Le résultat est un objet JSON détaillant l'état actuel.

{
  "enabled": true
}

Intégrations du SDK de l'émulateur

Les tableaux de cette section indiquent les émulateurs compatibles avec les SDK client et administrateur. À venir signifie que la compatibilité avec l'émulateur est prévue, mais pas encore disponible.

Disponibilité du SDK client

Android Plates-formes Apple Web UI Firebase
Android 		IUG Firebase
iOS 		UI Firebase
Web
Realtime Database 19.4.0 7.2.0 8.0.0 6.4.0 Futur N/A
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4.0 Futur N/A
Authentication 20.0.0 7.0.0 8.0.0 7.0.0 Futur 4.7.2
Cloud Storage for Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 N/A
Cloud Functions 19.1.0 7.2.0 8.0.0 N/A N/A N/A
Hosting N/A N/A N/A N/A N/A N/A
Extensions N/A N/A N/A N/A N/A N/A

Disponibilité du SDK Admin

Nœud Java Python Go
Realtime Database 8.6.0 6.10.0 2.18.0 Futur
Cloud Firestore 8.0.0 6.10.0 3.0.0 1.0.0
Authentication 9.3.0 7.2.0 5.0.0 4.2.0
Cloud Storage for Firebase 9.8.0 Futur Futur Futur
Cloud Functions N/A N/A N/A N/A
Hosting N/A N/A N/A N/A
Extensions N/A N/A N/A N/A