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, qu'il s'agisse de sessions de prototypage ponctuelles ou de workflows d'intégration continue à l'échelle de la production.

Installer la suite d'émulateurs locaux

Avant d'installer la suite d'émulateurs, vous aurez besoin des éléments suivants :

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

Pour installer Emulator Suite :

1. Installez la CLI Firebase. Si la CLI Firebase n'est pas encore installée, installez-la maintenant. Pour utiliser l'Emulator Suite, vous devez disposer de la version 8.14.0 ou ultérieure de la CLI. 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 invites à 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 d'émulateur correspondants et de définir les ports d'émulateur si les valeurs par défaut ne conviennent pas.

   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 votre 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 manuellement le chemin d'accès aux définitions des règles de sécurité en modifiant firebase.json.

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.

Configuration des ports

Chaque émulateur est associé à un port différent sur votre machine, avec une valeur par défaut préférée.

Configuration de l'ID du projet

Selon la manière dont vous appelez les émulateurs, vous pouvez exécuter plusieurs instances d'un émulateur à l'aide de différents ID de projet Firebase 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.

En règle générale, il est recommandé de définir un ID de projet pour toutes les invocations d'émulateur. Ainsi, Emulator Suite UI, les différents émulateurs de produits et toutes les instances en cours d'exécution d'un émulateur particulier peuvent communiquer correctement dans tous les cas.

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

Vous pouvez vérifier si les déclarations d'ID de projet présentent des incohérences :

• Projet par défaut dans la ligne de commande. Par défaut, l'ID du projet sera récupéré au démarrage à partir 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 du projet est souvent spécifié dans les appels aux méthodes de la bibliothèque Rules Unit Testing initializeTestEnvironment ou initializeTestApp.
• Indicateur --project de ligne de commande. Le transfert de l'option --project de la CLI Firebase remplace le projet par défaut. Vous devrez vous assurer que la valeur du flag 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 Platforms, Android et Web.

Configuration des règles de sécurité

Les émulateurs récupèrent 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

Les émulateurs Realtime Database, 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 indicateurs entre guillemets, séparés par des espaces, comme JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". Les indicateurs n'affectent que les composants basés sur Java des émulateurs et n'ont aucun effet sur les autres parties de l'interface de ligne de commande 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 s'arrêtent automatiquement.

La méthode firebase emulators:exec est généralement plus appropriée pour les 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.

Intégrer à votre système CI

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

L'installation et la configuration de l'Emulator Suite avec des conteneurs dans une configuration CI typique sont simples.

Voici quelques points à noter :

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

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

• Si vous n'avez pas de 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 devrez vous connecter à l'aide d'un jeton pour exécuter firebase emulators:exec. Les autres émulateurs ne nécessitent pas de 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 toutes les versions. Le jeton doit être traité comme un mot de passe. Veillez à ce qu'il reste secret.

Si votre environnement d'intégration continue vous permet de spécifier des variables d'environnement utilisables dans les scripts de compilation, il vous suffit de créer une variable d'environnement appelée FIREBASE_TOKEN, dont la valeur est la chaîne du jeton d'accès. L'interface de ligne de commande Firebase récupérera automatiquement la variable d'environnement FIREBASE_TOKEN et les émulateurs démarreront correctement.

En dernier recours, vous pouvez simplement inclure le jeton dans votre script de compilation, mais assurez-vous que les tiers non fiables 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 Emulator Hub

Lister les émulateurs en cours d'exécution

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

curl localhost:4400/emulators

Le résultat sera 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 d'arrière-plan

Dans certains cas, vous devrez désactiver temporairement les déclencheurs de fonctions et d'extensions locales. Par exemple, vous pouvez supprimer toutes les données de l'émulateur Cloud Firestore sans déclencher de fonctions onDelete en cours d'exécution 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 de l'Emulator Hub.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

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

{
  "enabled": false
}

Pour réactiver les déclencheurs de fonctions locales après les avoir désactivés, envoyez une requête PUT au point de terminaison /functions/enableBackgroundTriggers de l'Emulator Hub.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Le résultat sera 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 Admin. À venir signifie que la compatibilité avec l'émulateur est prévue, mais pas encore disponible.

Disponibilité du SDK client

Disponibilité du SDK Admin