@endran/firebridge

firebridge

A Node.js HTTP or CLI bridge for Firebase Admin, during testing and development.
Gives access to Firebase via CLI or HTTP, opening up Admin power from anywhere.
Can also be used with the Firebase emulator suite.

Installation

npm install @endran/firebridge --save

or

yarn add @endran/firebridge

Usage

You can use Firebridge as a HTTP service, or as a CLI tool. Both have their own use case.

Use the CLI in build scripts, for example in your package.json.

firebridge --serviceAccount firebase-admin.json --commandPath 'export.command.json'

Use the HTTP server in your end to end tests, we use it in combination with Cypress, since it circumvents Firebase Admin SDK compatibility.

firebridge --serviceAccount firebase-admin.json --open 4201

Commands

The CLI requires a path to a command file relative from the working directory of Firebridge. The Server accepts POST requests. The content of command file, or POST body is identical.

In the examples below we use "ref":"__ROOT__", but instead we could also use "ref":"col1/doc2" to indicate a specific document or collection. __ROOT__ is the keyword used for the root of Firestore.

Export

The easiest way to get started is to first export a database that you have crafted manually.

{
    "action": "FIRESTORE.EXPORT",
    "ref": "__ROOT__",
    "file": "export.json"
}

Import

Now that we have a data set, let's import it.

{
    "action": "FIRESTORE.IMPORT",
    "file": "export.json"
}

Clear

Or even better, first wipe all data, so that we can prove import works.

{
    "action": "FIRESTORE.CLEAR",
    "ref": "__ROOT__"
}

Add Users

You'll need to create test accounts, let's automate this as well.

{
    "action": "AUTH.ADD",
    "uid": "TEST_USER_ID_1",
    "email": "[e-mail]",
    "password": "123456"
}

Instead of having the uid, email and password details in json command, you can also have a field "file": "users.json" which can hold an array of users.

Remove Users

Every once in a while you might need to remove users, because of reasons like automated testing, this is possible via below command, keep in mind that either keep or remove regex must be set, or both. When both are set, first remove is applied, and then on that set keep is applied.

{
    "action": "AUTH.DELETE",
    "remove": ".*@remove.com",
    "keep": ".*@keep.com"
}

Get

All commands until now are using mostly config files as source data, however often you need to be able to dynamically access your data, especially during E2E tests.

{
    "action": "FIRESTORE.GET",
    "ref": "some/document"
}

This will yield a response with a data field, which has the same structure as before with FIRESTORE.EXPORT. This means that also any collections of this document will be returned provided as seperate keys in the data object. You can use this result to assert the state of the database in respect to the state of the application in your test.

Set

To make sure the application is in a certain state you must make sure Firestore is correct. For this you can use FIRESTORE.IMPORT, but often you need to add more data dynamically from your test.

{
    "action": "FIRESTORE.SET",
    "ref": "",
    "data": {
        "some/document": {"someKey": "someValue"}
    }
}

This will set the provided data at ref.

Help

Usage: index [options]

Options:
  -V, --version                 output the version number
  -S, --serviceAccount <path>   Required. Location of service account JSON file.
  -E, --emulator                Use the Firebase emulator on the default ports.
  --emulatorFirestore <number>  Use the Firebase Firestore emulator on the provided port.
  --emulatorAuth <number>       Use the FireBase Auth on the provided port.
  -O, --open <number>           Starts applicants as server on the given port. Prevents --commandPath.
  -J, --commandJson <json>      Executes a single command from json. Is ignored when --open is used.
  -P, --commandPath <path>      Executes a single command from path. Is ignored when --open or --commandJson is used.
  --verbose                     Enable verbose logging.
  -h, --help                    output usage information


Examples:
  $ firebridge -S firebase-admin.json --open 4201
  $ firebridge -S firebase-admin.json --commandPath examples/simpleSetCommand.json
  $ firebridge -S firebase-admin.json --commandJson '{"action":"FIRESTORE.IMPORT","file":"examples/data.json"}'

Expected data format per command
AUTH.DELETE:       { "action":"AUTH.DELETE", "remove?": ".*@remove.com", "keep?": ".*@keep.com" }
AUTH.ADD:          { "action":"AUTH.ADD", "file?": "users.json", "uid?": "USER_ID_1", "email?": "[e-mail]", "password?": "atLeastSixChars" }
FIRESTORE.GET:     { "action":"FIRESTORE.GET", "ref": "__ROOT__" | "colA" | "colA/docB" }
FIRESTORE.SET:     { "action":"FIRESTORE.SET", "data": {"colA/docB": {}} }
FIRESTORE.CLEAR:   { "action":"FIRESTORE.CLEAR", "ref": "__ROOT__" | "colA" | "colA/docB" }
FIRESTORE.IMPORT:  { "action":"FIRESTORE.IMPORT", "ref": "__ROOT__" | "colA" | "colA/docB", "file": "export.json" }
FIRESTORE.EXPORT:  { "action":"FIRESTORE.EXPORT", "ref": "__ROOT__" | "colA" | "colA/docB", "file": "export.json" }

Notes

File format:
Firebridge uses node-firestore-import-export, this library has support for complex data types like Timestamp and Geopoint.

Service Account:
You can get the firebase-admin.json file from the Firebase Console. Select , click the cog, go to User and Permission, then Service Accounts, tick Node.js, and hit Generate.

Known issues

Unresponsive after system sleep:

• For Mac users, when you close your MacBook, Firebridge may need a restart to work properly again.
• The datatypes timestamp and geopoint can be imported without any problem, by reference is broken.

Keywords

Firebase, Cloud Firestore, Firebase Authentication, Cypress, E2E Testing, CI/CD

License

The MIT License

Copyright (c) 2022 David Hardy
Copyright (c) 2022 codecentric nl

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.