Watch demos on how to build & run AI-powered apps with Firebase at Demo Day '24. Watch now.

Cette page a été traduite par l'API Cloud Translation.

Créer des tests unitaires

Les Firebase Local Emulator Suite permettent de valider plus facilement l'ensemble des fonctionnalités et du comportement de votre application. Il s'agit également d'un excellent outil pour vérifier vos configurations Firebase Security Rules. Utilisez les émulateurs Firebase pour exécuter et automatiser des tests unitaires dans un environnement local. Les méthodes décrites dans ce document devraient vous aider à créer et à automatiser des tests unitaires pour votre application qui valident votre Rules.

Si ce n'est pas déjà fait, configurez les émulateurs Firebase.

Avant d'exécuter l'émulateur

Avant de commencer à utiliser l'émulateur, gardez à l'esprit les points suivants :

L'émulateur charge initialement les règles spécifiées dans le champ firestore.rules ou "storage.rules" de votre fichier firebase.json. Si le fichier n'existe pas et que vous n'utilisez pas la méthode loadFirestoreRules ou "loadStorageRules" comme décrit ci-dessous, l'émulateur considère que tous les projets ont des règles ouvertes.
Bien que la plupart des SDK Firebase fonctionnent directement avec les émulateurs, seule la bibliothèque @firebase/rules-unit-testing accepte une simulation d'option auth dans les règles de sécurité, ce qui facilite considérablement les tests unitaires. En outre, la bibliothèque est compatible avec quelques fonctionnalités spécifiques à l'émulateur, telles que la suppression de toutes les données, comme indiqué ci-dessous.
Les émulateurs acceptent également les jetons d'authentification Firebase de production fournis par les SDK du client et évaluent les règles en conséquence, ce qui permet de connecter directement votre application aux émulateurs dans les tests d'intégration et les tests manuels.

Différences entre les émulateurs de base de données et l'environnement de production

Vous n'avez pas besoin de créer explicitement une instance de base de données. L'émulateur crée automatiquement une instance de base de données à laquelle vous accédez.
Chaque nouvelle base de données est démarrée avec des règles fermées. Les utilisateurs non administrateurs ne peuvent donc pas lire ni écrire.
Chaque base de données émulée applique les limites et les quotas du plan Spark (ce qui limite chaque instance à 100 connexions simultanées, en particulier).
Toute base de données accepte la chaîne "owner" comme jeton d'authentification administrateur.
Les émulateurs n'ont actuellement aucune interaction fonctionnelle avec d'autres produits Firebase. Il est à noter que le flux Firebase Authentication normal ne fonctionne pas. Vous pouvez utiliser la méthode initializeTestApp() dans la bibliothèque rules-unit-testing, qui accepte un champ auth. L'objet Firebase créé à l'aide de cette méthode se comporte comme s'il était authentifié comme n'importe quelle entité que vous fournissez. Si vous transmettez la valeur null, il se comporte comme un utilisateur non authentifié (les règles auth != null échouent, par exemple).

Interagir avec l'émulateur Realtime Database

Une instance Realtime Database Firebase de production est accessible sur un sous-domaine de firebaseio.com. Vous pouvez accéder à l'API REST comme suit:

https://<database_name>.firebaseio.com/path/to/my/data.json

L'émulateur s'exécute localement et est disponible à l'adresse localhost:9000. Pour interagir avec une instance de base de données spécifique, vous devez utiliser le paramètre de requête ns afin de spécifier le nom de la base de données.

http://localhost:9000/path/to/my/data.json?ns=<database_name>

Exécuter des tests unitaires locaux avec le SDK JavaScript version 9

Firebase distribue une bibliothèque de tests unitaires de règles de sécurité avec son SDK JavaScript version 9 ainsi qu'avec son SDK version 8. Les API de bibliothèques sont très différentes. Nous recommandons d'utiliser la bibliothèque de tests v9, qui est bien plus simple et nécessite moins d'opérations de configuration pour la connexion aux émulateurs. Cela permet d'éviter toute utilisation accidentelle des ressources de production. Dans un souci de rétrocompatibilité, nous laissons la bibliothèque de tests v8 disponible.

Méthodes de test et fonctions utilitaires courantes dans le SDK v9
Méthodes de test spécifiques à l'émulateur dans le SDK v9

Utilisez le module @firebase/rules-unit-testing pour interagir avec l'émulateur qui s'exécute localement. Si vous obtenez des expirations de délai ou des erreurs ECONNREFUSED, vérifiez que l'émulateur est en cours d'exécution.

Nous vous recommandons vivement d'utiliser une version récente de Node.js afin de pouvoir utiliser la notation async/await. La quasi-totalité du comportement que vous souhaitez tester implique des fonctions asynchrones, et le module de test est conçu pour fonctionner avec du code basé sur Promise.

La bibliothèque de tests unitaires de règles v9 a toujours connaissance des émulateurs et ne modifie jamais vos ressources de production.

Vous importez la bibliothèque à l'aide d'instructions d'importation modulaire v9. Exemple :

import {
  assertFails,
  assertSucceeds,
  initializeTestEnvironment
} from "@firebase/rules-unit-testing"

// Use `const { … } = require("@firebase/rules-unit-testing")` if imports are not supported
// Or we suggest `const testing = require("@firebase/rules-unit-testing")` if necessary.

Une fois importés, les tests unitaires impliquent ce qui suit :

Créer et configurer un RulesTestEnvironment avec un appel vers initializeTestEnvironment
Configurer des données de test sans déclencher Rules, à l'aide d'une méthode pratique qui vous permet de les ignorer temporairement, RulesTestEnvironment.withSecurityRulesDisabled.
Configurer la suite de tests et les hooks avant/après spécifiques à chaque test en effectuant des appels pour nettoyer les données et l'environnement de test, tels que RulesTestEnvironment.cleanup() ou RulesTestEnvironment.clearFirestore()
Mettre en œuvre des scénarios de test qui imitent des états d'authentification à l'aide de RulesTestEnvironment.authenticatedContext et RulesTestEnvironment.unauthenticatedContext

Méthodes et fonctions utilitaires courantes

Consultez également les méthodes de test spécifiques à l'émulateur à l'aide de l'API modulaire.

initializeTestEnvironment() => RulesTestEnvironment

Cette fonction initialise un environnement de test pour les tests unitaires de règles. Appelez d'abord cette fonction pour la configuration du test. Pour que l'exécution aboutisse, les émulateurs doivent être en cours d'exécution.

La fonction accepte un objet facultatif définissant une TestEnvironmentConfig, qui peut être constituée d'un ID de projet et des paramètres de configuration de l'émulateur.

let testEnv = await initializeTestEnvironment({
  projectId: "demo-project-1234",
  firestore: {
    rules: fs.readFileSync("firestore.rules", "utf8"),
  },
});

Remarque : Les émulateurs conservent les données entre les appels de test lors d'une seule exécution de l'émulateur. Cela peut avoir un impact sur vos résultats. Pour effacer les données entre chaque exécution de test, appelez la méthode applicable pour effacer les données de l'émulateur (par exemple clearFirestoreData) entre les tests.

RulesTestEnvironment.authenticatedContext({ user_id: string, tokenOptions?: TokenOptions }) => RulesTestContext

Cette méthode crée un RulesTestContext, qui se comporte comme un utilisateur Authentication authentifié. Les requêtes créées via le contexte renvoyé comportent un jeton Authentication fictif associé. Vous pouvez également transmettre un objet définissant des revendications personnalisées ou des un mécanisme de forçage pour les charges utiles de jeton Authentication.

Utilisez l'objet de contexte de test renvoyé dans vos tests pour accéder aux instances de l'émulateur configurées, y compris celles configurées avec initializeTestEnvironment.

// Assuming a Firestore app and the Firestore emulator for this example
import { setDoc } from "firebase/firestore";

const alice = testEnv.authenticatedContext("alice", { … });
// Use the Firestore instance associated with this context
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

RulesTestEnvironment.unauthenticatedContext() => RulesTestContext

Cette méthode crée un RulesTestContext, qui se comporte comme un client non connecté via Authentication. Les requêtes créées via le contexte renvoyé ne disposent pas de jetons Firebase Auth associés.

Utilisez l'objet de contexte de test renvoyé dans vos tests pour accéder aux instances de l'émulateur configurées, y compris celles configurées avec initializeTestEnvironment.

// Assuming a Cloud Storage app and the Storage emulator for this example
import { getStorage, ref, deleteObject } from "firebase/storage";

const alice = testEnv.unauthenticatedContext();

// Use the Cloud Storage instance associated with this context
const desertRef = ref(alice.storage(), 'images/desert.jpg');
await assertSucceeds(deleteObject(desertRef));

RulesTestEnvironment.withSecurityRulesDisabled()

Exécutez une fonction de configuration de test, avec un contexte simulant une désactivation des règles de sécurité.

Cette méthode utilise une fonction de rappel, qui prend le contexte de contournement des règles de sécurité et renvoie une promesse. Le contexte est détruit une fois que la promesse est acceptée ou rejetée.

RulesTestEnvironment.cleanup()

Cette méthode détruit tous les RulesTestContexts créés dans l'environnement de test et nettoie les ressources sous-jacentes, ce qui permet une sortie propre.

Cette méthode ne modifie en aucun cas l'état des émulateurs. Pour réinitialiser les données entre les tests, utilisez la méthode d'effacement de données spécifique à l'émulateur de l'application.

assertSucceeds(pr: Promise<any>)) => Promise<any>

Il s'agit d'une fonction utilitaire de scénario de test.

La fonction indique que la promesse fournie encapsulant une opération d'émulateur sera acceptée, sans violation des règles de sécurité.

await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

assertFails(pr: Promise<any>)) => Promise<any>

Il s'agit d'une fonction utilitaire de scénario de test.

La fonction indique que la promesse fournie encapsulant une opération d'émulateur sera rejetée, avec une violation des règles de sécurité.

await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });

Méthodes spécifiques à l'émulateur

Consultez également les méthodes de test et fonctions utilitaires courantes à l'aide de l'API modulaire.

Cloud Firestore

RulesTestEnvironment.clearFirestore() => Promise<void>

Cette méthode efface les données de la base de données Firestore appartenant au projectId configuré pour l'émulateur Firestore.

RulesTestContext.firestore(settings?: Firestore.FirestoreSettings) => Firestore;

Cette méthode récupère une instance Firestore pour ce contexte de test. L'instance du SDK client Firebase JS renvoyée peut être utilisée avec les API du SDK client (v9 modulaire ou compatible v9).

Realtime Database

RulesTestEnvironment.clearDatabase() => Promise<void>

Cette méthode efface les données de Realtime Database appartenant à projectId configuré pour l'émulateur Realtime Database.

RulesTestContext.database(databaseURL?: Firestore.FirestoreSettings) => Firestore;

Obtenez une instance Realtime Database pour ce contexte de test. L'instance du SDK client Firebase JS renvoyée peut être utilisée avec les API du SDK client (modulaire ou avec un espace de noms, version 9 ou ultérieure). La méthode accepte une URL de l'instance Realtime Database. Si spécifié, renvoie une instance pour une version émulée de l'espace de noms avec des paramètres extraits de l'URL.

Cloud Storage

RulesTestEnvironment.clearStorage() => Promise<void>

Cette méthode efface les objets et les métadonnées des buckets de stockage appartenant au projectId configuré pour l'émulateur Cloud Storage.

RulesTestContext.storage(bucketUrl?: string) => Firebase Storage;

Cette méthode renvoie une instance Storage configurée pour se connecter à l'émulateur. La méthode accepte une URL gs:// vers le bucket Firebase Storage à des fins de test. Si spécifié, renvoie une instance Storage pour une version émulée du nom du bucket.

Exécuter des tests unitaires locaux avec le SDK JavaScript v8

Sélectionnez un produit pour afficher les méthodes utilisées par le SDK de test Firebase pour interagir avec l'émulateur.

Cloud Firestore

initializeTestApp({ projectId: string, auth: Object }) => FirebaseApp

Cette méthode renvoie une application Firebase initialisée correspondant à l'ID du projet et à la variable d'authentification spécifiés dans les options. Utilisez-la pour créer une application authentifiée en tant qu'utilisateur spécifique, à utiliser dans les tests.

firebase.initializeTestApp({
  projectId: "my-test-project",
  auth: { uid: "alice", email: "alice@example.com" }
});

Remarque: L'émulateur Cloud Firestore conserve les données entre les appels de test lors d'une seule exécution de l'émulateur. Cela peut avoir un impact sur vos résultats. Pour effacer les données entre chaque exécution de test, appelez la méthode clearFirestoreData entre les tests.

initializeAdminApp({ projectId: string }) => FirebaseApp

Cette méthode renvoie une application Firebase d'administration initialisée. Cette application contourne les règles de sécurité lors de la lecture et de l'écriture. Utilisez-la pour créer une application authentifiée en tant qu'administrateur, afin de définir l'état des tests.

firebase.initializeAdminApp({ projectId: "my-test-project" });

apps() => [FirebaseApp] Cette méthode renvoie toutes les applications de test et d'administration actuellement initialisées. Utilisez-la pour nettoyer les applications pendant ou après les tests.

Promise.all(firebase.apps().map(app => app.delete()))

loadFirestoreRules({ projectId: string, rules: Object }) => Promise

Cette méthode envoie des règles à une base de données exécutée localement. Elle prend un objet qui spécifie les règles sous forme de chaîne. Utilisez cette méthode pour définir les règles de votre base de données.

firebase.loadFirestoreRules({
  projectId: "my-test-project",
  rules: fs.readFileSync("/path/to/firestore.rules", "utf8")
});

assertFails(pr: Promise) => Promise

Cette méthode renvoie une promesse qui est refusée si l'entrée réussit ou qui réussit si l'entrée est rejetée. Utilisez cette méthode pour indiquer si la lecture ou l'écriture d'une base de données échoue.

firebase.assertFails(app.firestore().collection("private").doc("super-secret-document").get());

assertSucceeds(pr: Promise) => Promise

Cette méthode renvoie une promesse qui réussit si l'entrée réussit et qui est rejetée si l'entrée est rejetée. Utilisez cette méthode pour indiquer si la lecture ou l'écriture de la base de données a réussi.

firebase.assertSucceeds(app.firestore().collection("public").doc("test-document").get());

clearFirestoreData({ projectId: string }) => Promise

Cette méthode efface toutes les données associées à un projet particulier dans l'instance Firestore exécutée localement. Utilisez cette méthode pour effectuer un nettoyage après les tests.

firebase.clearFirestoreData({
  projectId: "my-test-project"
});

Realtime Database

initializeTestApp({ databaseName: string, auth: Object }) => FirebaseApp

Utilisez cette option pour créer une application authentifiée en tant qu'utilisateur spécifique à utiliser dans les tests.

Renvoie une application Firebase initialisée correspondant au nom de la base de données et au forçage de la variable d'authentification spécifiés dans les options.

firebase.initializeTestApp({
  databaseName: "my-database",
  auth: { uid: "alice" }
});

initializeAdminApp({ databaseName: string }) => FirebaseApp

Utilisez cette option pour créer une application authentifiée en tant qu'administrateur afin de configurer l'état des tests.

Renvoie une application Firebase d'administration initialisée correspondant au nom de base de données spécifié dans les options. Cette application contourne les règles de sécurité lors de la lecture et de l'écriture dans la base de données.

firebase.initializeAdminApp({ databaseName: "my-database" });

loadDatabaseRules({ databaseName: string, rules: Object }) => Promise

Utilisez-le pour définir les règles de votre base de données.

Envoie des règles à une base de données exécutée localement. Prend un objet d'options qui spécifie "databaseName" et "rules" sous forme de chaînes.

firebase
      .loadDatabaseRules({
        databaseName: "my-database",
        rules: "{'rules': {'.read': false, '.write': false}}"
      });

apps() => [FirebaseApp]

Renvoie toutes les applications de test et d'administration actuellement initialisées.

Utilisez-la pour nettoyer les applications pendant ou après les tests (notez que les applications initialisées avec des écouteurs actifs empêchent JavaScript de se fermer):

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Renvoie une promesse qui est refusée si l'entrée réussit et qui réussit si l'entrée est rejetée.

Utilisez cette méthode pour affirmer qu'une lecture ou une écriture de base de données échoue:

firebase.assertFails(app.database().ref("secret").once("value"));

assertSucceeds(pr: Promise) => Promise

Renvoie une promesse qui réussit si l'entrée réussit et qui est rejetée si l'entrée est rejetée.

Utilisez cette méthode pour vérifier qu'une lecture ou une écriture de base de données a réussi:

firebase.assertSucceeds(app.database().ref("public").once("value"));

Cloud Storage

initializeTestApp({ storageBucket: string, auth: Object }) => FirebaseApp

Utilisez-la pour créer une application authentifiée en tant qu'utilisateur spécifique, à utiliser dans les tests.

Renvoie une application Firebase initialisée correspondant au nom du bucket de stockage et au forçage de la variable d'authentification spécifiés dans les options.

firebase.initializeTestApp({
  storageBucket: "my-bucket",
  auth: { uid: "alice" }
});

initializeAdminApp({ storageBucket: string }) => FirebaseApp

Utilisez-la pour créer une application authentifiée en tant qu'administrateur afin de configurer l'état des tests.

Renvoie une application Firebase d'administration initialisée correspondant au nom du bucket de stockage spécifié dans les options. Cette application contourne les règles de sécurité lors de la lecture et de l'écriture dans le bucket.

firebase.initializeAdminApp({ storageBucket: "my-bucket" });

loadStorageRules({ storageBucket: string, rules: Object }) => Promise

Utilisez-le pour définir les règles de votre bucket de stockage.

Envoie des règles à des buckets de stockage gérés localement. Prend un objet d'options qui spécifie votre "storageBucket" et vos "rules" sous forme de chaînes.

firebase
      .loadStorageRules({
        storageBucket: "my-bucket",
        rules: fs.readFileSync("/path/to/storage.rules", "utf8")
      });

apps() => [FirebaseApp]

Renvoie toutes les applications de test et d'administration actuellement initialisées.

Utilisez-la pour nettoyer les applications pendant ou après les tests (notez que les applications initialisées avec des écouteurs actifs empêchent JavaScript de se fermer):

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Renvoie une promesse qui est rejetée si l'entrée réussit et qui réussit si l'entrée est rejetée.

Utilisez cette méthode pour vérifier qu'une lecture ou une écriture de bucket de stockage échoue:

firebase.assertFails(app.storage().ref("letters/private.doc").getMetadata());

assertSucceeds(pr: Promise) => Promise

Renvoie une promesse qui réussit si l'entrée réussit et qui est rejetée si l'entrée est rejetée.

Utilisez cette méthode pour vérifier qu'une lecture ou une écriture de bucket de stockage a réussi:

firebase.assertFails(app.storage().ref("images/cat.png").getMetadata());

API de la bibliothèque RUT pour le SDK JS v8

Sélectionnez un produit pour afficher les méthodes utilisées par le SDK Firebase Test pour interagir avec l'émulateur.

Cloud Firestore

initializeTestApp({ projectId: string, auth: Object }) => FirebaseApp

firebase.initializeTestApp({
  projectId: "my-test-project",
  auth: { uid: "alice", email: "alice@example.com" }
});

initializeAdminApp({ projectId: string }) => FirebaseApp

firebase.initializeAdminApp({ projectId: "my-test-project" });

Promise.all(firebase.apps().map(app => app.delete()))

loadFirestoreRules({ projectId: string, rules: Object }) => Promise

firebase.loadFirestoreRules({
  projectId: "my-test-project",
  rules: fs.readFileSync("/path/to/firestore.rules", "utf8")
});

assertFails(pr: Promise) => Promise

firebase.assertFails(app.firestore().collection("private").doc("super-secret-document").get());

assertSucceeds(pr: Promise) => Promise

firebase.assertSucceeds(app.firestore().collection("public").doc("test-document").get());

clearFirestoreData({ projectId: string }) => Promise

Cette méthode efface toutes les données associées à un projet particulier dans l'instance Firestore exécutée localement. Utilisez cette méthode pour effectuer un nettoyage après les tests.

firebase.clearFirestoreData({
  projectId: "my-test-project"
});

Realtime Database

initializeTestApp({ databaseName: string, auth: Object }) => FirebaseApp

Utilisez cette option pour créer une application authentifiée en tant qu'utilisateur spécifique à utiliser dans les tests.

Renvoie une application Firebase initialisée correspondant au nom de la base de données et au forçage de la variable d'authentification spécifiés dans les options.

firebase.initializeTestApp({
  databaseName: "my-database",
  auth: { uid: "alice" }
});

initializeAdminApp({ databaseName: string }) => FirebaseApp

Utilisez cette option pour créer une application authentifiée en tant qu'administrateur afin de configurer l'état des tests.

firebase.initializeAdminApp({ databaseName: "my-database" });

loadDatabaseRules({ databaseName: string, rules: Object }) => Promise

Utilisez-le pour définir les règles de votre base de données.

Envoie des règles à une base de données exécutée localement. Prend un objet d'options qui spécifie "databaseName" et "rules" sous forme de chaînes.

firebase
      .loadDatabaseRules({
        databaseName: "my-database",
        rules: "{'rules': {'.read': false, '.write': false}}"
      });

apps() => [FirebaseApp]

Renvoie toutes les applications de test et d'administration actuellement initialisées.

Utilisez-la pour nettoyer les applications pendant ou après les tests (notez que les applications initialisées avec des écouteurs actifs empêchent JavaScript de se fermer):

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Renvoie une promesse qui est refusée si l'entrée réussit et qui réussit si l'entrée est rejetée.

Utilisez cette méthode pour affirmer qu'une lecture ou une écriture de base de données échoue:

firebase.assertFails(app.database().ref("secret").once("value"));

assertSucceeds(pr: Promise) => Promise

Renvoie une promesse qui réussit si l'entrée réussit et qui est rejetée si l'entrée est rejetée.

Utilisez cette méthode pour vérifier qu'une lecture ou une écriture de base de données a réussi:

firebase.assertSucceeds(app.database().ref("public").once("value"));

Cloud Storage

initializeTestApp({ storageBucket: string, auth: Object }) => FirebaseApp

Utilisez-la pour créer une application authentifiée en tant qu'utilisateur spécifique, à utiliser dans les tests.

Renvoie une application Firebase initialisée correspondant au nom du bucket de stockage et au forçage de la variable d'authentification spécifiés dans les options.

firebase.initializeTestApp({
  storageBucket: "my-bucket",
  auth: { uid: "alice" }
});

initializeAdminApp({ storageBucket: string }) => FirebaseApp

Utilisez-la pour créer une application authentifiée en tant qu'administrateur afin de configurer l'état des tests.

firebase.initializeAdminApp({ storageBucket: "my-bucket" });

loadStorageRules({ storageBucket: string, rules: Object }) => Promise

Utilisez-le pour définir les règles de votre bucket de stockage.

Envoie des règles à des buckets de stockage gérés localement. Prend un objet d'options qui spécifie votre "storageBucket" et vos "rules" sous forme de chaînes.

firebase
      .loadStorageRules({
        storageBucket: "my-bucket",
        rules: fs.readFileSync("/path/to/storage.rules", "utf8")
      });

apps() => [FirebaseApp]

Renvoie toutes les applications de test et d'administration actuellement initialisées.

Utilisez-la pour nettoyer les applications pendant ou après les tests (notez que les applications initialisées avec des écouteurs actifs empêchent JavaScript de se fermer):

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Renvoie une promesse qui est rejetée si l'entrée réussit et qui réussit si l'entrée est rejetée.

Utilisez cette méthode pour vérifier qu'une lecture ou une écriture de bucket de stockage échoue:

firebase.assertFails(app.storage().ref("letters/private.doc").getMetadata());

assertSucceeds(pr: Promise) => Promise

Renvoie une promesse qui réussit si l'entrée réussit et qui est rejetée si l'entrée est rejetée.

Utilisez cette méthode pour vérifier qu'une lecture ou une écriture de bucket de stockage a réussi:

firebase.assertFails(app.storage().ref("images/cat.png").getMetadata());