How to Use Firebase Emulator for Rules Testing

Use the firebase emulators:start command with your firebase.json configured to include the firestore or database emulator. This lets you test your Firebase security rules locally without affecting live data.

Syntax

The Firebase Emulator Suite runs locally with the command firebase emulators:start. You configure which emulators to run in the firebase.json file under the emulators section.

Example parts:

• firestore or database: specifies which database emulator to run.
• rules: path to your security rules file.
• port: the local port number the emulator listens on.

json

{
  "emulators": {
    "firestore": {
      "port": 8080,
      "rules": "firestore.rules"
    },
    "database": {
      "port": 9000,
      "rules": "database.rules.json"
    }
  }
}

Example

This example shows how to configure and start the Firestore emulator with rules for local testing.

json + shell

{
  "emulators": {
    "firestore": {
      "port": 8080,
      "rules": "firestore.rules"
    }
  }
}

# Command to start the emulator
firebase emulators:start --only firestore

Output

✔  emulators: Starting emulators: firestore
i  firestore: Firestore Emulator logging to firestore-debug.log
✔  firestore: Emulator started at http://localhost:8080

Common Pitfalls

• Not specifying the rules file path in firebase.json causes the emulator to run without your custom rules.
• Forgetting to run firebase emulators:start means your app connects to live Firebase, risking data changes.
• Using the wrong port or conflicting ports can cause the emulator to fail to start.
• Not updating your app's Firebase config to point to the emulator host and port will bypass the emulator.

json

Wrong configuration example:
{
  "emulators": {
    "firestore": {
      "port": 8080
      // Missing rules path
    }
  }
}

Right configuration example:
{
  "emulators": {
    "firestore": {
      "port": 8080,
      "rules": "firestore.rules"
    }
  }
}

Quick Reference

Tips for using Firebase Emulator for rules:

• Always specify your rules file in firebase.json.
• Use firebase emulators:start --only firestore,database to run specific emulators.
• Update your app to connect to localhost and the emulator port during testing.
• Check emulator logs for rule evaluation details.

Key Takeaways

Configure your rules file path in firebase.json under the emulators section.

Run the emulator locally with firebase emulators:start to test rules safely.

Update your app to connect to the emulator host and port during testing.

Check emulator logs to debug and verify rule behavior.

Avoid running tests against live Firebase to prevent unwanted data changes.