Testing rules with emulator in Firebase - Commands & Configuration

Introduction

When you build apps that store data in Firebase, you need to protect that data with rules. Testing these rules before going live helps avoid mistakes that could let anyone read or change your data. The Firebase emulator lets you safely test your rules on your computer without affecting real data.

When you want to check if your Firebase security rules allow only the right users to read or write data.

When you want to try changes to your rules without risking your live database.

When you want to simulate different user roles and see how rules behave for each.

When you want to run automated tests on your rules as part of your development process.

When you want to debug why a certain read or write is blocked or allowed.

Config File - firestore.rules

firestore.rules

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

This file defines Firestore security rules.

rules_version sets the version of rules syntax.

service cloud.firestore means these rules apply to Firestore.

The match /users/{userId} block controls access to user documents.

It allows read and write only if the user is logged in and their ID matches the document ID.

Commands

Starts the Firestore emulator locally so you can test your rules without touching live data.

Terminal

firebase emulators:start --only firestore

Expected Output

i  emulators: Starting emulators: firestore

✔  firestore: Emulator started at http://localhost:8080



⚠  emulators: The UI is not running because it is not enabled in firebase.json



✔  All emulators started, it is now safe to connect.

→

--only firestore - Starts only the Firestore emulator without other Firebase emulators.

Runs tests against your Firestore rules using the emulator to check if your rules work as expected.

Terminal

firebase emulators:exec "firebase firestore:rules:test --rules firestore.rules --project demo-project --test-file firestore.test.json"

Expected Output

✔  Running Firestore rules tests from firestore.test.json...

Tests completed: 5

Passed: 5

Failed: 0

→

--rules - Specifies the rules file to test.

→

--project - Specifies the Firebase project ID for the test context.

Runs a set of predefined tests from a JSON file against your Firestore rules to verify access control.

Terminal

firebase firestore:rules:test --rules firestore.rules --project demo-project --test-file firestore.test.json

Expected Output

✔  Running Firestore rules tests from firestore.test.json...

Tests completed: 5

Passed: 5

Failed: 0

→

--test-file - Specifies the JSON file containing test cases.

Key Concept

If you remember nothing else from this pattern, remember: always test your Firebase security rules locally with the emulator before deploying to protect your data.

Common Mistakes

Running tests without starting the emulator first

The tests need the emulator running to simulate the database environment; otherwise, they fail or give wrong results.

Always start the Firestore emulator with 'firebase emulators:start --only firestore' before running rule tests.

Using incorrect project ID in test commands

The emulator uses the project ID to simulate the environment; a wrong ID can cause tests to run against wrong settings or fail.

Use the correct Firebase project ID in the '--project' flag matching your local setup.

Not specifying the rules file in test commands

Without specifying the rules file, tests run against default or old rules, missing your latest changes.

Always use the '--rules' flag to point to your current rules file.

Summary

Start the Firestore emulator locally to safely test your security rules.

Run rule tests using the emulator to verify who can read or write data.

Use the correct project ID and rules file when running tests to ensure accuracy.