Search Lessons, Code Snippets, and Videos
search by algolia

You have unlimited access as a PRO member

You are receiving a free preview of 3 lessons

Your free preview as expired - please upgrade to PRO

Contents

  1. Project Setup
  2. Testing Helpers
    1. Setup the Database with Auth and Mock Data
    2. Teardown
    3. Custom Async Jest Matchers
  3. Testing Firestore Rules
    1. Ensure Rules are Secure by Default
    2. Seeding the Database with Mock Data
  4. The End

Recent Posts

X
#native_cta# #native_desc# Sponsored by #native_company#

Testing Firestore Security Rules With the Emulator

Episode 147 written by Jeff Delaney
full courses and content on fireship.io

Source code for Testing Firestore Security Rules With the Emulator on Github

The most exciting announcement (in my opinion) at Firebase Summit 2018 was the local emulator for Firestore and RTDB, making it possible to test security rules locally or on a CI server. If you’re brand new to Firebase security, make sure to watch the Firestore Security Rules Guide.

Project Setup

The following lesson creates an isolated testing environment solely for testing rules logic. It does not need to be directly coupled your frontend code, which is a useful if your database spans across multiple frontend clients (ie Web, iOS, and Android).

To keep our code as simple as possible, this lesson uses Jest with vanilla JS.

mkdir rules && cd rules
npm init -y

npm i -D jest @firebase-testing

Now that we have a testing environment in place, let’s link our project and opt-in to the emulator. 

firebase init firestore

firebase --open-sesame emulators
firebase setup:emulators:firestore

firebase serve --only firestore

You must have Java installed on your local machine to work with the emulator

Testing Helpers

Like most test suites, it’s useful to start with a few helpers to keep the code succinct and readable. Below are several helpers I have developed for working with the emulator in Jest.

Setup the Database with Auth and Mock Data

The setup method is the most important helper. It initializes the database with a unique projectId, then optionally seeds it with a mock user and mock data. 

const firebase = require('@firebase/testing');
const fs = require('fs');

module.exports.setup = async (auth, data) => {
  const projectId = `rules-spec-${Date.now()}`;
  const app = await firebase.initializeTestApp({
    projectId,
    auth
  });

  const db = app.firestore();

  // Write mock documents before rules
  if (data) {
    for (const key in data) {
      const ref = db.doc(key);
      await ref.set(data[key]);
    }
  }



  // Apply rules
  await firebase.loadFirestoreRules({
    projectId,
    rules: fs.readFileSync('firestore.rules', 'utf8')
  });

  return db;
};

Usage of the setup method looks like this: 

const mockUser = { 
  uid: 'jeffd23'
}

const mockData = {
  'users/jeffd23': {
    foo: 'bar'
  },
  'tasks/testTask': {
    hello: 'world'
  }
};

//...

const db = await setup(mockUser, mockData)

Teardown

It’s a good practice to delete your app instances after the test run, otherwise Jest might complain about hanging async operations. 

module.exports.teardown = async () => {
  Promise.all(firebase.apps().map(app => app.delete()));
};

Custom Async Jest Matchers

As a final touch, we will also implement custom matchers improve readability. Every Firestore rule test will be verifying that an operation was either (1) allowed or (2) denied. The matchers below make it possible to write tests that look like expect(read).toAllow(). This part is optional, but will make life easier if you have a large test suite. 

expect.extend({
  async toAllow(x) {
    let pass = false;
    try {
      await firebase.assertSucceeds(x);
      pass = true;
    } catch (err) {}

    return {
      pass,
      message: () => 'Expected Firebase operation to be allowed, but it was denied'
    };
  }
});

expect.extend({
  async toDeny(x) {
    let pass = false;
    try {
      await firebase.assertFails(x);
      pass = true;
    } catch (err) {}
    return {
      pass,
      message: () =>
        'Expected Firebase operation to be denied, but it was allowed'
    };
  }
});

Testing Firestore Rules

Let’s now take a look at several practical testing scenarios.

Ensure Rules are Secure by Default

First, let validate that database rules are secure by default - meaning a read to any random collection should be denied.

service cloud.firestore {
  match /databases/{database}/documents {

    match /{document=**} {
      allow read: if false;
      allow write: if false;
    }
  }
}

Below I offer several different ways to write your rules, both with the built-in Firebase testing helpers and our custom Jest matchers. 

const { setup, teardown } = require('./helpers');
const { assertFails, assertSucceeds } = require('@firebase/testing');

describe('Database rules', () => {
  let db;
  let ref;

  // Applies only to tests in this describe block
  beforeAll(async () => {
    db = await setup();

    // All paths are secure by default
    ref = db.collection('some-nonexistent-collection');
  });

  afterAll(async () => {
    await teardown();
  });

  test('fail when reading/writing an unauthorized collection', async () => {
    const failedRead = await assertFails(ref.get());
    expect(failedRead);

    // One-line await
    expect(await assertFails(ref.add({})));

    // Custom Matchers
    await expect(ref.get()).toDeny();
    await expect(ref.get()).toAllow(); // should fail
  });
});

Seeding the Database with Mock Data

Many rules require checks on related documents, for example, checking if a user has a specific access role before they can read/write to a collection. Rules like this require mock data to be present in the database before the rules are evaluated. Let’s write a test that requires an authenticated user and that seeds Firestore with mock data .

Let’s imagine we have a project management app that allows read/write for admin users OR users contained in an members access control list. 

// Role-based authorization
function getUserData() {
  return get(/databases/$(database)/documents/users/$(request.auth.uid)).data
}

match /projects/{docId} {
  allow read, write: if getUserData().roles['admin'] == true 
  || resource.data.members.hasAny([request.auth.uid])
}

Notice how each test in this suite initializes a fresh database instance with a different authenticated user, but maintains the same mock data state. 

const { setup, teardown } = require('./helpers');

const mockData = {
  'users/jeffd23': {
    roles: {
      admin: true
    }
  },
  'projects/testId': {
    members: ['bob']
  }
};

describe('Project rules', () => {
  let db;
  let projectsRef;

  afterAll(async () => {
    await teardown();
  });

  test('deny a user that does NOT have the admin role', async () => {
    const db = await setup({ uid: null }, mockData);

    // Allow rules in place for this collection
    projRef = db.doc('projects/testId');
    await expect(projRef.get()).toDeny();
  });

  test('allow a user with the admin role', async () => {
    const db = await setup({ uid: 'jeffd23' }, mockData);

    projRef = db.doc('projects/testId');
    await expect(projRef.get()).toAllow();
  });

  test('deny a user if they are NOT in the Access Control List', async () => {
    const db = await setup({ uid: 'frank' }, mockData);

    projRef = db.doc('projects/testId');
    await expect(projRef.get()).toDeny();
  });

  test('allow a user if they are in the Access Control List', async () => {
    const db = await setup({ uid: 'bob' }, mockData);

    projRef = db.doc('projects/testId');
    await expect(projRef.get()).toAllow();
  });
});

The End

The Firestore emulator will deliver a huge boost of confidence to your backend security logic and prevent regressions that lead to catastrophic data breaches. Although the emulator is still in beta, it has already become an important tool in my workflow and I’m looking forward to experimenting with other use-cases.