Testez vos règles de sécurité Cloud Firestore

Pendant que vous créez votre application, vous souhaiterez peut-être verrouiller l'accès à votre base de données Cloud Firestore. Cependant, avant de vous lancer, vous aurez besoin de règles de sécurité Cloud Firestore plus nuancées. Avec l'émulateur Nuage Firestore, en plus de prototypage et de test de votre application caractéristiques générales et le comportement , vous pouvez écrire des tests unitaires qui vérifient le comportement de votre Cloud FireStore Règles de sécurité.

Démarrage rapide

Pour quelques cas de test de base avec des règles simples, essayer l' échantillon QuickStart .

Comprendre les règles de sécurité de Cloud Firestore

Mettre en œuvre Firebase d' authentification et de Cloud FireStore Règles de sécurité pour l' authentification serveur, l' autorisation et la validation des données lorsque vous utilisez les bibliothèques clientes mobiles et Web.

Les règles de sécurité Cloud Firestore comprennent deux éléments :

  1. Une match déclaration qui identifie les documents dans votre base de données.
  2. Une allow l' expression qui contrôle l' accès à ces documents.

Firebase Authentication vérifie les informations d'identification des utilisateurs et fournit la base des systèmes d'accès basés sur les utilisateurs et les rôles.

Chaque requête de base de données d'une bibliothèque cliente mobile/web Cloud Firestore est évaluée par rapport à vos règles de sécurité avant de lire ou d'écrire des données. Si les règles refusent l'accès à l'un des chemins de document spécifiés, la demande entière échoue.

En savoir plus sur Nuage Firestore Règles de sécurité dans Commencez avec Cloud FireStore Règles de sécurité .

Installer l'émulateur

Pour installer l'émulateur cloud Firestore, utilisez la CLI Firebase et exécutez la commande suivante:

firebase setup:emulators:firestore

Exécuter l'émulateur

Commencez par initialiser un projet Firebase dans votre répertoire de travail. Ceci est une première étape commune lors de l' utilisation de la CLI Firebase .

firebase init

Démarrez l'émulateur à l'aide de la commande suivante. L'émulateur fonctionnera jusqu'à ce que vous tuiez le processus :

firebase emulators:start --only firestore

Dans de nombreux cas, vous souhaitez démarrer l'émulateur, exécuter une suite de tests, puis arrêter l'émulateur après l'exécution des tests. Vous pouvez le faire facilement en utilisant les emulators:exec commande:

firebase emulators:exec --only firestore "./my-test-script.sh"

Au démarrage, l'émulateur tentera de s'exécuter sur un port par défaut (8080). Vous pouvez modifier le port de l' émulateur en modifiant la "emulators" section de votre firebase.json fichier:

{
  // ...
  "emulators": {
    "firestore": {
      "port": "YOUR_PORT"
    }
  }
}

Avant d'exécuter l'émulateur

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

  • L'émulateur sera d' abord charger les règles spécifiées dans le firestore.rules champ de votre firebase.json fichier. Il attend le nom d'un fichier local contenant vos règles de sécurité Cloud Firestore et applique ces règles à tous les projets. Si vous ne fournissez pas le chemin de fichier local ou utiliser le loadFirestoreRules procédé tel que décrit ci - dessous, l'émulateur traite tous les projets ayant des règles ouvertes.
  • Alors que la plupart Firebase SDKs travail avec les émulateurs directement, seul le @firebase/rules-unit-testing bibliothèque prend en charge se moquant auth dans les règles de sécurité, ce qui rend les tests unitaires beaucoup plus facile. De plus, la bibliothèque prend en charge quelques fonctionnalités spécifiques à l'émulateur, telles que l'effacement de toutes les données, comme indiqué ci-dessous.
  • Les émulateurs accepteront également les jetons Firebase Auth de production fournis via les SDK clients et évalueront les règles en conséquence, ce qui permet de connecter votre application directement aux émulateurs lors des tests d'intégration et manuels.

Exécuter des tests unitaires locaux

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

Firebase distribue une bibliothèque de tests unitaires de règles de sécurité avec à la fois son SDK JavaScript version 9 et son SDK version 8. Les API de bibliothèque sont très différentes. Nous recommandons la bibliothèque de test v9, qui est plus rationalisée et nécessite moins de configuration pour se connecter aux émulateurs et ainsi éviter en toute sécurité l'utilisation accidentelle des ressources de production. Pour une compatibilité ascendante, nous continuons à la bibliothèque de tests v8 disponibles .

Utilisez le @firebase/rules-unit-testing module pour interagir avec l'émulateur qui fonctionne localement. Si vous obtenez les délais d' attente ou ECONNREFUSED erreurs, vérifiez que l'émulateur est en fait en cours d' exécution.

Nous vous recommandons fortement d' utiliser une version récente de Node.js pour que vous puissiez utiliser async/await notation. Presque tous les comportements que vous souhaitez tester impliquent 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 est toujours au courant des émulateurs et ne touche jamais vos ressources de production.

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

import {
  assertFails,
  assertSucceeds,
  initializeTestEnvironment,
  RulesTestEnvironment,
} 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, la mise en œuvre des tests unitaires implique :

  • Création et configuration d' un RulesTestEnvironment avec un appel à initializeTestEnvironment .
  • Mise en place des données de test sans règles de déclenchement, en utilisant une méthode pratique qui vous permet de les contourner temporairement, RulesTestEnvironment.withSecurityRulesDisabled .
  • Mise en place suite de tests et par-test avant / après des crochets avec des appels à nettoyer les données de test et de l' environnement, comme RulesTestEnvironment.cleanup() ou RulesTestEnvironment.clearFirestore() .
  • La mise en œuvre des cas de test qui simulent des états d'authentification en utilisant RulesTestEnvironment.authenticatedContext et RulesTestEnvironment.unauthenticatedContext .

Méthodes courantes et fonctions utilitaires

Voir aussi les méthodes de test spécifiques émulateur dans le SDK v9 .

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. Une exécution réussie nécessite l'exécution d'émulateurs.

La fonction accepte un objet optionnel définissant un TestEnvironmentConfig , qui peut consister en un identifiant de projet et l' émulateur paramètres de configuration.

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

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

Cette méthode crée un RulesTestContext , qui se comporte comme un utilisateur authentifié d' authentification. Les demandes créées via le contexte renvoyé auront un jeton d'authentification fictif attaché. Facultativement, transmettez un objet définissant des revendications personnalisées ou des remplacements pour les charges utiles du jeton d'authentification.

Utilisez l'objet de contexte de test retourné dans vos tests pour accéder à toutes les instances de l' émulateur configurés, y compris ceux qui sont configurés 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 qui n'est pas connecté via l' authentification. Les requêtes créées via le contexte renvoyé n'auront pas de jetons Firebase Auth attachés.

Utilisez l'objet de contexte de test retourné dans vos tests pour accéder à toutes les instances de l' émulateur configurés, y compris ceux qui sont configurés 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 qui se comporte comme si les règles de sécurité étaient désactivées.

Cette méthode prend une fonction de rappel, qui prend le contexte de contournement des règles de sécurité et renvoie une promesse. Le contexte sera détruit une fois la promesse résolue/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 change en rien l'état des émulateurs. Pour réinitialiser les données entre les tests, utilisez la méthode d'effacement des données spécifique à l'émulateur d'application.

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

Il s'agit d'une fonction utilitaire de cas de test.

La fonction affirme que la promesse fournie enveloppant une opération d'émulateur sera résolue 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 cas de test.

La fonction affirme que la promesse fournie enveloppant 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

Voir aussi les méthodes d'essai et fonctions communes d'utilité dans le SDK v9 .

RulesTestEnvironment.clearFirestore() => Promise<void>

Cette méthode efface les données dans la base de données Firestore qui appartient à la projectId configuré pour l'émulateur Firestore.

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

Cette méthode obtient 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 (modulaire v9 ou compatible v9).

Visualiser les évaluations des règles

L'émulateur Cloud Firestore vous permet de visualiser les demandes des clients dans l'interface utilisateur de Emulator Suite, y compris le suivi d'évaluation pour les règles de sécurité Firebase.

Ouvrez le Firestore> Demandes onglet pour afficher la séquence d'évaluation détaillée pour chaque demande.

Firestore Emulator Requests Monitor affichant les évaluations des règles de sécurité

Générer des rapports de tests

Après avoir exécuté une suite de tests, vous pouvez accéder aux rapports de couverture de test 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/<project_id>:ruleCoverage.html

Cela divise vos règles en expressions et sous-expressions sur lesquelles vous pouvez passer 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/<project_id>:ruleCoverage

Différences entre l'émulateur et la production

  1. Vous n'avez pas besoin de créer explicitement un projet Cloud Firestore. L'émulateur crée automatiquement toute instance accessible.
  2. L'émulateur Cloud Firestore ne fonctionne pas avec le flux d'authentification Firebase normal. Au lieu de cela, dans le Firebase SDK test, nous avons fourni la initializeTestApp() méthode dans le rules-unit-testing bibliothèque, qui prend un auth champ. Le descripteur Firebase créé à l'aide de cette méthode se comportera comme s'il s'était authentifié avec succès en tant qu'entité que vous fournissez. Si vous passez null , il se comporte comme un utilisateur non authentifié ( auth != null règles échouent, par exemple).

Résoudre les problèmes connus

Lorsque vous utilisez l'émulateur Cloud Firestore, vous pouvez rencontrer les problèmes connus suivants. Suivez les conseils ci-dessous pour résoudre tout comportement irrégulier que vous rencontrez. Ces notes sont écrites en gardant à l'esprit la bibliothèque de tests unitaires des règles de sécurité, mais les approches générales sont applicables à n'importe quel SDK Firebase.

Le comportement du test est incohérent

Si vos tests réussissent et échouent occasionnellement, même sans aucune modification des tests eux-mêmes, vous devrez peut-être vérifier qu'ils sont correctement séquencés. La plupart des interactions avec l'émulateur sont asynchrones, vérifiez donc que tout le code asynchrone est correctement séquencé. Vous pouvez fixer le séquençage en enchaînant soit des promesses, ou en utilisant await notation libérale.

En particulier, examinez les opérations asynchrones suivantes :

  • Définition de règles de sécurité, avec, par exemple, initializeTestEnvironment .
  • La lecture et l' écriture des données, avec, par exemple, db.collection("users").doc("alice").get() .
  • Assertions opérationnelles, y compris assertSucceeds et assertFails .

Les tests ne réussissent que la première fois que vous chargez l'émulateur

L'émulateur est avec état. Il stocke toutes les données qui y sont écrites en mémoire, de sorte que toutes les données sont perdues à chaque fois que l'émulateur s'arrête. Si vous exécutez plusieurs tests sur le même ID de projet, chaque test peut produire des données susceptibles d'influencer les tests suivants. Vous pouvez utiliser l'une des méthodes suivantes pour contourner ce comportement :

  • Utilisez des ID de projet uniques pour chaque test. Notez que si vous choisissez de faire , vous devrez appeler initializeTestEnvironment dans le cadre de chaque test; les règles ne sont chargées automatiquement que pour l'ID de projet par défaut.
  • Restructurez vos tests afin qu'ils n'interagissent pas avec des données écrites précédemment (par exemple, utilisez une collection différente pour chaque test).
  • Supprimer toutes les données écrites lors d'un test.

La configuration du test est très compliquée

Lors de la configuration de votre test, vous souhaiterez peut-être modifier les données d'une manière que vos règles de sécurité Cloud Firestore ne permettent pas réellement. Si vos règles font complexes de configuration de test, essayez d' utiliser RulesTestEnvironment.withSecurityRulesDisabled dans vos étapes de configuration, donc lit et écrit ne déclenchent pas PERMISSION_DENIED erreurs.

Après cela, votre test peut effectuer des opérations en tant qu'utilisateur authentifié ou non authentifié en utilisant RulesTestEnvironment.authenticatedContext et unauthenticatedContext respectivement. Cela vous permet de valider que vos règles de sécurité Cloud Firestore autorisent/refusent correctement différents cas.