mock-firestore

0.11.0 verified Fri May 01 auth: no python

In-memory implementation of Google Cloud Firestore for use in tests. Currently at version 0.11.0. Release cadence is irregular; last update was a while ago but library is stable.

pip install mock-firestore

Common errors

error ImportError: cannot import name 'MockFirestore' from 'mockfirestore' ↓

cause Using incorrect import path with hyphen instead of underscore.

fix

Use: from mock_firestore import MockFirestore

error TypeError: __init__() got an unexpected keyword argument 'project' ↓

cause Using deprecated constructor argument in newer versions.

fix

Remove the 'project' argument: MockFirestore()

error AttributeError: 'MockFirestore' object has no attribute 'collection' ↓

cause Possibly mocking the wrong class or not importing from the correct module.

fix

Ensure you are using from mock_firestore import MockFirestore and not from google.cloud import firestore

Warnings

gotcha MockFirestore does not enforce real Firestore constraints like unique document IDs within a collection (auto-ID generation) or transactional isolation. Do not assume identical behavior to production Firestore. ↓

fix Only use for unit tests where exact constraint emulation is not required.

deprecated The `MockFirestore` constructor no longer accepts `project` or `credentials` arguments in recent versions (0.11.0). Previously you could pass a project ID. ↓

fix Simply instantiate without arguments: `MockFirestore()`

gotcha The `collection()` and `document()` methods return references but do not actually create the underlying data until a write operation (like `.set()` or `.add()`) is performed. Methods like `.get()` on a non-existent document will raise an exception (simulating real Firestore). ↓

fix Always perform a write before reading a document that may not exist, or use `document_ref.get().exists` to check.

Imports

MockFirestore

wrong

from mockfirestore import MockFirestore

correct

from mock_firestore import MockFirestore

Module name uses underscore, not hyphen.

Quickstart

Create a MockFirestore instance and use it like the real Firestore client.

from mock_firestore import MockFirestore

firestore = MockFirestore()
# Add a document
doc_ref = firestore.collection('users').document('user1')
doc_ref.set({'name': 'Alice', 'email': 'alice@example.com'})
# Query
docs = firestore.collection('users').where('name', '==', 'Alice').stream()
for doc in docs:
    print(doc.id, doc.to_dict())
# Output: user1 {'name': 'Alice', 'email': 'alice@example.com'}