Mongomock

Warnings

• breaking Mongomock v4.0.0 dropped support for Python 2. Additionally, its behavior adapted to align with PyMongo v4's API changes. If your project uses PyMongo v3 or Python 2, you may encounter compatibility issues or changed behavior.
  Fix: Ensure your project runs on Python 3 and, if using PyMongo, upgrade to PyMongo v4 or newer if possible. If not, use an older version of mongomock compatible with your PyMongo version (e.g., mongomock < 4.0.0 for PyMongo v3).
• gotcha Mongomock is a mock library, not a full MongoDB server. It aims for reasonable completeness but does not implement all MongoDB features or edge-case behaviors perfectly. Unsupported operations may raise `NotImplementedError` or behave differently than a real MongoDB instance. Advanced aggregation pipelines, geospatial queries, or complex indexing behaviors might not be fully replicated.
  Fix: Always check for `NotImplementedError` during testing if using advanced MongoDB features. For critical functionality, consider integration tests against a real MongoDB instance. Review mongomock's documentation or source for supported features.
• gotcha Performance of `mongomock` can be significantly slower than a real MongoDB, especially for bulk write operations or operations involving unique constraints on large datasets. This is due to its in-memory, Pythonic implementation of database logic.
  Fix: When testing performance-critical code paths, be aware that `mongomock` might introduce artificial bottlenecks. Optimize test data size where possible. For actual performance benchmarking, use a real MongoDB instance.
• gotcha When dynamically patching `pymongo.MongoClient` in complex applications (e.g., Flask), ensure you patch the `MongoClient` class in the module where it is actually imported and used by your application logic, rather than just where it's defined. Python's import caching can lead to the original object still being referenced elsewhere.
  Fix: Use `mongomock.patch` decorator or `unittest.mock.patch.object` on the `MongoClient` instance or the module that imports it within your tests. Verify that the patched client is indeed being used by your application code during testing.

Install

• pip install mongomock Install with pip

Imports

• MongoClient

  import mongomock
  client = mongomock.MongoClient()

  The primary way to instantiate a mock MongoDB client.
• patch

  from mongomock import patch
  @patch(servers=(('server.example.com', 27017),))

  A decorator for patching `pymongo.MongoClient` calls within a test function, redirecting them to a mongomock client. It's crucial to patch at the point where `pymongo.MongoClient` is looked up, not necessarily defined, due to Python's import mechanisms.

Quickstart

This quickstart demonstrates how to initialize a `mongomock.MongoClient`, interact with a database and collection, and perform basic CRUD (Create, Read, Update, Delete) operations, mimicking the PyMongo API. The data is stored entirely in memory and is transient for each client instance.

import mongomock

# 1. Create a mock client instance
client = mongomock.MongoClient()

# 2. Access a database (it's created on first access)
db = client.mydatabase

# 3. Access a collection
collection = db.mycollection

# 4. Perform common MongoDB operations
# Insert documents
insert_result_one = collection.insert_one({"name": "Alice", "age": 30})
print(f"Inserted one: {insert_result_one.inserted_id}")

insert_result_many = collection.insert_many([{"name": "Bob", "age": 25}, {"name": "Charlie", "age": 35}])
print(f"Inserted many IDs: {insert_result_many.inserted_ids}")

# Find documents
alice = collection.find_one({"name": "Alice"})
print(f"Found Alice: {alice}")

all_docs = list(collection.find({}))
print(f"All documents: {all_docs}")

# Update documents
update_result = collection.update_one({"name": "Bob"}, {"$set": {"age": 26, "city": "New York"}})
print(f"Matched {update_result.matched_count}, modified {update_result.modified_count} for Bob")

bob = collection.find_one({"name": "Bob"})
print(f"Updated Bob: {bob}")

# Delete documents
delete_result = collection.delete_one({"name": "Charlie"})
print(f"Deleted count for Charlie: {delete_result.deleted_count}")

charlie = collection.find_one({"name": "Charlie"})
print(f"Found Charlie (should be None): {charlie}") # Output: Found Charlie (should be None): None

# The database and its collections are in-memory and reset with a new MongoClient instance.