Évaluer les extensions à l'aide de l'émulateur d'extensions

Avant d'utiliser l'émulateur Extensions avec votre application, assurez-vous de comprendre le workflow global de Firebase Local Emulator Suite, d'installer et de configurer Local Emulator Suite, et de consulter ses commandes CLI.

Ce guide suppose également que vous connaissez les Firebase Extensions et que vous savez comment les utiliser dans vos applications Firebase.

Que puis-je faire avec l'émulateur Extensions ?

Avec l'émulateur Extensions, vous pouvez installer et gérer des extensions dans un environnement local sécurisé, et mieux comprendre leurs capacités tout en minimisant les coûts facturés. L'émulateur exécute les fonctions de votre extension localement, y compris les fonctions déclenchées par des événements en arrière-plan à l'aide des émulateurs pour Cloud Firestore, Realtime Database, Cloud Storage for Firebase, Authentication et Pub/Sub, ainsi que les fonctions déclenchées par Eventarc implémentées dans Cloud Functions v2.

Choisir un projet Firebase

Firebase Local Emulator Suite émule les produits d'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 de l'é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 Utiliser avec des émulateurs
Situation réelle

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

Les projets réels disposent de ressources actives, telles que des instances de base de données, des buckets de stockage, des fonctions ou toute autre ressource que vous configurez pour ce projet Firebase.

Lorsque vous travaillez avec de vrais projets Firebase, vous pouvez exécuter des émulateurs pour l'un ou l'ensemble des produits compatibles.

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

Démo

Un projet de démonstration Firebase ne comporte pas de véritable configuration Firebase ni de ressources actives. Ces projets sont généralement accessibles via des ateliers de programmation ou d'autres tutoriels.

Les ID des 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 des é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. Voici quelques-uns de ses avantages :

  • Configuration plus simple, car vous pouvez exécuter les émulateurs sans jamais créer de projet Firebase
  • Sécurité renforcée : si votre code appelle accidentellement des ressources non émulées (en production), il n'y a aucun risque de modification des données, d'utilisation et 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.

Installer et évaluer une extension

Il est très simple d'utiliser l'émulateur Extensions pour évaluer si une extension répond à vos besoins.

Supposons que vous vous intéressiez à l'extension Trigger Email (firestore-send-email), bien que le workflow suivant couvre toutes les extensions. Lorsqu'elle est exécutée avec des émulateurs locaux, l'extension Trigger Email utilise automatiquement les émulateurs Cloud Firestore et Cloud Functions.

Pour évaluer une extension localement :

  1. Ajoutez l'extension au fichier manifeste des extensions locales. Un fichier manifeste d'extensions est une liste d'instances d'extensions et de leurs configurations.

    firebase ext:install --local firebase/firestore-send-email

    L'exécution de la commande ci-dessus vous invite à configurer la dernière version de l'extension firebase/firestore-send-email et à enregistrer la configuration dans le fichier manifeste, mais elle ne déploie pas la configuration dans votre projet. Pour en savoir plus, consultez Gérer la configuration des extensions avec des fichiers manifestes.

  2. Démarrez Local Emulator Suite comme vous le feriez normalement.

    firebase emulators:start

À l'aide de l'instance d'extension firestore-send-email listée dans votre fichier manifeste, Local Emulator Suite va maintenant télécharger le code source de cette extension dans ~/.cache/firebase/extensions. Une fois les sources téléchargées, Local Emulator Suite démarre et vous pouvez déclencher n'importe quelle fonction déclenchée en arrière-plan de l'extension et connecter votre application à Local Emulator Suite pour tester son intégration à votre application.

Vous pouvez utiliser Emulator Suite UI pour ajouter des données à la collection de documents d'e-mails et configurer d'autres ressources de backend, comme l'exige l'extension Trigger Email.

Pour les environnements de test non interactifs tels que les workflows d'intégration continue, vous pouvez également écrire un script de test pour évaluer l'extension qui, entre autres étapes, renseigne les données Cloud Firestore nécessaires et déclenche des fonctions. Vous devez ensuite appeler Local Emulator Suite pour exécuter votre script de test :

firebase emulators:exec my-test.sh

Différences entre les tests avec l'émulateur Extensions et la production

L'émulateur Extensions vous permet de tester les extensions d'une manière qui correspond étroitement à l'expérience de production. Cependant, il existe quelques différences par rapport au comportement en production.

Cloud IAM

La suite d'émulateurs Firebase ne tente pas de répliquer ni de respecter un comportement lié à IAM pour l'exécution. Les émulateurs respectent les règles de sécurité Firebase fournies, mais dans les situations où IAM serait normalement utilisé, par exemple pour définir le compte de service appelant Cloud Functions et donc les autorisations, l'émulateur n'est pas configurable et utilise le compte disponible de manière globale sur votre ordinateur de développement, comme si vous exécutiez directement un script local.

Limitation du type de déclenchement

Actuellement, Firebase Local Emulator Suite n'est compatible qu'avec les fonctions déclenchées par des requêtes HTTP, les déclencheurs d'événements personnalisés Eventarc pour les extensions et les fonctions déclenchées par des événements en arrière-plan pour Cloud Firestore, Realtime Database, Cloud Storage for Firebase, Authentication et Pub/Sub. Pour évaluer les extensions qui utilisent d'autres types de fonctions déclenchées, vous devez installer votre extension dans un projet Firebase de test.

Et maintenant ?