firebase-jest-testing

Tools for testing Firebase backend features, using Jest.

Offers:

• 🥫Emulator detection. The library automatically picks up the configuration when running the tests. Less boilerplate!

• 🪶Light. Uses Firestore REST API so no Firebase client JS SDK is required.

• ⚡️Fast. Optimized for multithreading and Node.js. You'll likely max out your cores.

• ‖‖‖ Security Rules are tested immutably - a passing write or delete operation does not change the data, and cannot disturb other tests. This is why we can parallelize the tests so much. No flaky tests.

• ﹛﹜Help functions for priming Firestore with JSON data.

• + Means for testing callables _{(without a client SDK)}.

Only to be used with Jest 27 and above.

Requires

• Jest 27

  The module is built with ES modules in mind.

Using in your project

In your application project:

$ npm install --save-dev firebase-jest-testing@beta

Add this to the jest.config.js:

// Needed until Jest supports ESM's with multiple entry points (Jest 28?).
//
resolver: "hack-jest/jestResolver.cjs"

Create the custom Jest resolver.

/*
* hack-jest/jestResolver.cjs
*
* Note: It's really CHEAP that we don't use the 'exports' in the package itself, but this works, and eventually
*    Jest will support 'exports' for real. Also, we've narrowed down to only those entries that we need.
*
* References:
*   - Configuring Jest > resolver (Jest docs)
*     -> https://jestjs.io/docs/en/configuration#resolver-string [1]
*/
// Add mappings to any libraries you use which 'export' more than the default ('.') entry point (Jest 27 takes care of that).
//
const entries = Object.entries({
// firebase-jest-testing
"firebase-jest-testing/firestoreAdmin": "./src/firestoreAdmin/index.js",
"firebase-jest-testing/firestoreAdmin/setup": "./src/firestoreAdmin/setup/index.js",
"firebase-jest-testing/firestoreRules": "./src/firestoreRules/index.js",
"firebase-jest-testing/firebaseClientLike": "./src/firebaseClientLike/index.js",
// firebase-admin
"firebase-admin/app": "./lib/esm/app/index.js",
"firebase-admin/firestore": "./lib/esm/firestore/index.js"
}).map( ([k,v]) => {
const arr = k.match(/(.+?)//);   // pick the node_modules name
const name = arr[1] || fail("No '/' in key");
return [
k,
v.replace(/^.//, ${name}/)
]
});
const lookup = new Map(entries);
const res = ( request, options ) => {   // (string, { ..see above.. }) => ...
const hit = lookup.get(request);
if (hit) {
return options.defaultResolver( hit, options );
} else {
return options.defaultResolver( request, options );
}
};
module.exports = res;

Using with Docker Compose

With Docker Compose, your emulators are likely running under another host than the one running the Jest tests.

Set the EMUL_HOST env.var. to indicate the host name.

services:
  emul:
    ...
  sample:
    ...
    environment: ['EMUL_HOST=emul']

Sample project(s)

• GroundLevel-firebase-es packages/backend subpackage is customer #0.

If you find the library useful, you may file a PR for adding a link to your project here. 😊

Reference documentation

Writing tests walks you through the API.

• Testing Security Rules
• Testing Cloud Functions events and callables
• Priming with JSON data
• Why immutability matters ..and a bit about implementation

Support

If you wish to support the development of this software, be in touch with the author. We'll figure out something nice! ;)