How to Test Firestore Rules Locally

1# Initialize emulators (select Firestore when prompted)
2firebase init emulators
3
4# Your firebase.json will include:
5# {
6#   "emulators": {
7#     "firestore": { "port": 8080 },
8#     "ui": { "enabled": true, "port": 4000 }
9#   }
10# }

1# Start all emulators
2firebase emulators:start
3
4# Or start only the Firestore emulator
5firebase emulators:start --only firestore
6
7# With data persistence between restarts
8firebase emulators:start --import=./emulator-data --export-on-exit=./emulator-data

1# Install the testing library
2npm install --save-dev @firebase/rules-unit-testing
3
4# Also install a test runner if you don't have one
5npm install --save-dev vitest

1// tests/firestore-rules.test.ts
2import {
3  initializeTestEnvironment,
4  assertSucceeds,
5  assertFails,
6  RulesTestEnvironment
7} from '@firebase/rules-unit-testing';
8import { doc, getDoc, setDoc, deleteDoc } from 'firebase/firestore';
9import { readFileSync } from 'fs';
10
11let testEnv: RulesTestEnvironment;
12
13beforeAll(async () => {
14  testEnv = await initializeTestEnvironment({
15    projectId: 'test-project',
16    firestore: {
17      rules: readFileSync('firestore.rules', 'utf8'),
18      host: '127.0.0.1',
19      port: 8080
20    }
21  });
22});
23
24afterEach(async () => {
25  await testEnv.clearFirestore();
26});
27
28afterAll(async () => {
29  await testEnv.cleanup();
30});
31
32test('authenticated user can read their own profile', async () => {
33  const alice = testEnv.authenticatedContext('alice');
34  const db = alice.firestore();
35  await assertSucceeds(getDoc(doc(db, 'users', 'alice')));
36});
37
38test('user cannot read another user profile', async () => {
39  const alice = testEnv.authenticatedContext('alice');
40  const db = alice.firestore();
41  await assertFails(getDoc(doc(db, 'users', 'bob')));
42});
43
44test('unauthenticated user cannot create a post', async () => {
45  const unauth = testEnv.unauthenticatedContext();
46  const db = unauth.firestore();
47  await assertFails(
48    setDoc(doc(db, 'posts', 'post-1'), { title: 'Test', authorId: 'anon' })
49  );
50});

1import { getFirestore, connectFirestoreEmulator } from 'firebase/firestore';
2import { getAuth, connectAuthEmulator } from 'firebase/auth';
3import { initializeApp } from 'firebase/app';
4
5const app = initializeApp(firebaseConfig);
6const db = getFirestore(app);
7const auth = getAuth(app);
8
9// Connect to emulators in development only
10if (import.meta.env.DEV) {
11  connectFirestoreEmulator(db, '127.0.0.1', 8080);
12  connectAuthEmulator(auth, 'http://127.0.0.1:9099');
13  console.log('Connected to Firebase emulators');
14}