{"id":5327,"library":"mongomock-motor","title":"mongomock-motor","description":"mongomock-motor is a Python library that provides a best-effort mock for the AsyncIOMotorClient, built on top of the `mongomock` library. It enables developers to test asynchronous MongoDB applications that use `motor` without requiring a running MongoDB instance. The library is currently active, with frequent patch and minor feature releases.","status":"active","version":"0.0.36","language":"en","source_language":"en","source_url":"https://github.com/michaelkryukov/mongomock_motor","tags":["mongodb","mocking","testing","asyncio","motor","database"],"install":[{"cmd":"pip install mongomock-motor","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core library providing MongoDB mocking functionality.","package":"mongomock","optional":false},{"reason":"The library that mongomock-motor mocks. While not a direct runtime dependency for `mongomock-motor` itself, it is implicitly required by the user's application code that is being tested.","package":"motor","optional":true}],"imports":[{"symbol":"AsyncMongoMockClient","correct":"from mongomock_motor import AsyncMongoMockClient"},{"note":"AsyncIOMotorClient is the actual class from the 'motor' library that is being mocked, not a direct export from 'mongomock_motor'.","wrong":"from mongomock_motor import AsyncIOMotorClient","symbol":"AsyncIOMotorClient","correct":"from motor.motor_asyncio import AsyncIOMotorClient"}],"quickstart":{"code":"import asyncio\nfrom mongomock_motor import AsyncMongoMockClient\n\nasync def main():\n    client = AsyncMongoMockClient() # Create a mock client\n    db = client['mydatabase']\n    collection = db['mycollection']\n\n    # Insert a document\n    insert_result = await collection.insert_one({\"name\": \"Test Document\", \"value\": 123})\n    print(f\"Inserted document with ID: {insert_result.inserted_id}\")\n\n    # Find a document\n    found_doc = await collection.find_one({\"name\": \"Test Document\"})\n    print(f\"Found document: {found_doc}\")\n    assert found_doc['value'] == 123\n\n    # Update a document\n    update_result = await collection.update_one(\n        {\"name\": \"Test Document\"},\n        {\"$set\": {\"value\": 456}}\n    )\n    print(f\"Modified {update_result.modified_count} document(s).\")\n    updated_doc = await collection.find_one({\"name\": \"Test Document\"})\n    print(f\"Updated document: {updated_doc}\")\n    assert updated_doc['value'] == 456\n    \n    # Close the mock client (good practice, though not strictly necessary for mock)\n    await client.close()\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to initialize `AsyncMongoMockClient` and perform basic asynchronous MongoDB operations (insert, find, update) against it, mimicking the API of `motor.motor_asyncio.AsyncIOMotorClient`."},"warnings":[{"fix":"Thoroughly test critical code paths with both the mock and a real MongoDB instance (e.g., via Docker) to ensure identical behavior. Consult `mongomock` documentation for known limitations.","message":"mongomock-motor provides a 'best effort mock' and may not perfectly replicate all corner cases, complex query behaviors, or newer features of a real MongoDB instance or the `motor` driver. Discrepancies may arise in highly specific scenarios.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Plan for migration of your application code to the `PyMongo Async driver` and explore potential mocking solutions for that driver once `motor` is fully deprecated.","message":"The underlying `motor` library is scheduled for deprecation on May 14, 2026, with critical bug fixes ending May 14, 2027. Users are recommended to migrate to the `PyMongo Async driver`. This will affect the long-term relevance and maintenance of `mongomock-motor` as `motor` itself is phased out.","severity":"deprecated","affected_versions":"All versions"},{"fix":"Explicitly test BSON type handling in your application when using `mongomock-motor`. If issues arise, consider manual type conversion or reporting the inconsistency to the library maintainers.","message":"Specific BSON type handling, such as `uuidRepresentation` settings, might not behave identically in `mongomock-motor` compared to a real `motor` connection. This can lead to unexpected errors or data mismatches when dealing with UUIDs or other complex BSON types.","severity":"gotcha","affected_versions":"<=0.0.36"},{"fix":"Pin exact versions of `mongomock-motor`, `mongomock`, `motor`, and `pymongo` in your `requirements.txt` or `pyproject.toml`. Regularly review changelogs for all related libraries before upgrading.","message":"Compatibility with `mongomock`, `motor`, and `pymongo` versions is crucial. Upgrades in any of these underlying libraries (e.g., `mongomock` dropping Python 2 support or `motor` requiring `PyMongo 4.0+`) can introduce breaking changes that might not be immediately reflected or supported by `mongomock-motor`.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure `mongomock-motor` is only used within test suites and development environments, never deployed to production.","message":"This library is intended for unit and integration testing purposes only. It should never be used as a substitute for a real MongoDB connection in production environments.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}