How to test Firestore rules locally?

 

Step 1: Set Up Your Firebase Project Locally

 

To start testing Firestore rules locally, ensure you have the Firebase CLI installed. If not, install it using npm:

npm install -g firebase-tools

Log in to your Firebase account:

firebase login

Initialize your Firebase project in the local directory:

firebase init

During initialization, choose Firestore and Functions (if needed) and configure them.

 

Step 2: Install Firebase Emulator

 

In the root of your project directory, ensure you have a package.json file. If not, create one using:

npm init -y

Install the Firebase Emulator Suite:

npm install --save-dev firebase-tools

 

Step 3: Configure Firestore Emulator

 

Modify the firebase.json file to include Firestore in the emulators section:

{
  "emulators": {
    "firestore": {
      "port": 8080
    }
  }
}

 

Step 4: Define Your Firestore Security Rules

 

Create a file named firestore.rules or use the one generated during Firebase initialization. Define your security rules in this file, such as:

service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

 

Step 5: Write Your Tests

 

Create a test file, for instance, firestore.test.js. To run tests against your Firestore rules, use a testing framework like Mocha or Jest. Install the dependencies in your project:

npm install --save-dev mocha chai @firebase/testing

Write the test cases in your test file:

const firebase = require("@firebase/testing");
const MY_PROJECT_ID = "your-project-id";

describe("Firestore security rules", () => {
  it("should allow a user to read their own document", async () => {
    const db = firebase.initializeTestApp({
      projectId: MY_PROJECT_ID,
      auth: { uid: "user\_abc" }
    }).firestore();

    const testDoc = db.collection("users").doc("user\_abc");
    await firebase.assertSucceeds(testDoc.get());
  });

  it("should deny a user to read another user's document", async () => {
    const db = firebase.initializeTestApp({
      projectId: MY_PROJECT_ID,
      auth: { uid: "user\_xyz" }
    }).firestore();

    const testDoc = db.collection("users").doc("user\_abc");
    await firebase.assertFails(testDoc.get());
  });
});

 

Step 6: Run the Firebase Emulator and Tests

 

Start the emulators:

firebase emulators:start

In a separate terminal, run your tests using Mocha (or another testing framework of your choice):

npx mocha firestore.test.js

Ensure that all your test cases pass, which signifies that your Firestore rules are working as expected.

 

Step 7: Tear Down After Tests

 

Optionally, clean up the Firebase Emulator environment by shutting down the emulator processes. You can do this by stopping the terminal process running the emulators.

This procedure ensures that you can locally test Firestore security rules reliably before deploying them to production.