Firestore: Emulator

If you are developing with Firestore, thanks to its complex functionalities, its hard to mock for testing. Even there is some existing mock library, they are still missing some apis, such as CollectionGroup.

Fortunately, there is an official emulator that aims to solve the problem.

Although you can use it with gcloud command, I found out that leverraging docker is must faster and cleaner across local and ci environments. There is an existing docker image firestore-emulator, that can spinup the firestore emulator, just run:

docker run \
    -d \
    --rm \
    --name firestore-emulator \
    --env "FIRESTORE_PROJECT_ID=test-project" \
    --env "PORT=8080" \
    mtlynch/firestore-emulator

In case you want a newer version of firestore emulator, you can clone the git repository of this docker image and build with the desired gcloud sdk version. The first line of dockerfile is:

ARG GCLOUD_SDK_VERSION=271.0.0-alpine

Notice that the ARG let you decide your GCLOUD_SDK_VERSION at build time.

To build a desired version is simple as follow:

git clone git@github.com:mtlynch/firestore-emulator-docker.git
cd firestore-emulator-docker

# build with specific gcloud sdk version, e.g. 322.0.0.-alpine
docker build -f Dockerfile . \
    --build-arg GCLOUD_SDK_VERSION=322.0.0-alpine \
    --tag firestore-emulator

In the client side code, you need to initialize Firestore client with different configuration.

• projectId: should match the environment variable FIRESTORE_PROJECT_ID you passed into docker run.
• host: should be the environment variable PORT you passed into docker run.
• ssl: should be false since we are using plain text to communicate with emulator.

The code looks like this:

const client = new Firestore({ projectId: 'test-project', host: 'localhost:8080', ssl: false });
// use it as usual
const snapshot = await client.collection('col').doc('doc').get();
await client.collection('col').doc('doc').set({ field: 'value' });

When you are running multiple transactions on emulator and causing dead lock, firestore emulator needs more time to abort transaction and retry, it could take 30 second or more. For more details, see #2452, #2604.

So if you are running emulator for unittesting, make sure you set the timeout high enough to let the test pass. If you are using mocha, it should look something like this:

mocha \
    --timeout=60000 \
    --exit \
    --require ts-node/register \
    ./test/firestore/*.test.ts