-
Type:
Improvement
-
Resolution: Won't Do
-
Priority:
Major - P3
-
None
-
Affects Version/s: 4.16.0
-
Component/s: None
-
None
-
Python Drivers
-
None
-
None
-
None
-
None
-
None
-
None
Issue type: Improvement Component(s): Async, Docs Affects version(s): PyMongo 4.16 (any version with the GA Async API)
Description
Problem
Motor was deprecated on 14 May 2025 and reached end of life on 14 May 2026, with users directed to migrate to the PyMongo Async API. The migration guide covers the driver API itself, but the de facto unit-testing toolchain used by Motor applications did not come along with it:
- mongomock (the standard pure-Python test double for PyMongo) supports only the synchronous MongoClient. Support for AsyncMongoClient / AsyncDatabase / AsyncCollection has been an open feature request since the Async API was in beta: https://github.com/mongomock/mongomock/issues/916
- mongomock-motor wraps mongomock to emulate AsyncIOMotorClient. It is bound to the Motor API and does not work with AsyncMongoClient.
- The only AsyncMongoClient-compatible alternative is pymongo-async-mock, a community package first published in March 2026 with a single maintainer. Reports in mongomock#916 indicate gaps (e.g. count_documents, cursor iteration) in wrappers of this kind.
- The driver's own MockClient is internal test infrastructure and not intended for application testing.
- MongoDB publishes no guidance on how applications using PyMongo (sync or async) should be unit-tested.
Customer impact
An enterprise customer migrating a large Motor codebase to PyMongo Async reports that roughly 30% of their unit test suite breaks on migration because mongomock-motor has no PyMongo Async equivalent. They have raised this through support channels without receiving a clear answer. The effect is that the recommended migration path has a hidden regression in testability, which is slowing adoption of PyMongo Async.
Ask
Any of the following would close the gap, listed in rough order of preference:
- An officially supported, in-memory test double for MongoClient and AsyncMongoClient (either a package maintained by MongoDB, or MongoDB-sponsored async support in mongomock).
- An officially supported pytest fixture / Testcontainers helper package for PyMongo that spins up a real mongod (and optionally mongodb/mongodb-atlas-local for Search/Vector Search) so that "test against a real server" becomes a one-line dependency rather than per-project plumbing.
- At minimum, a documentation page under the PyMongo docs ("Testing applications that use PyMongo") stating the recommended approach, covering: why mocks are not recommended, how to use Testcontainers / mongodb-atlas-local / CI service containers with both sync and async clients, and how to structure code (e.g. repository pattern) so the driver boundary is easy to isolate. This page should also be linked from the Motor → PyMongo Async migration guide.
Acceptance criteria
- A Motor user following the migration guide has a documented, supported path to keep their unit tests running against AsyncMongoClient.
- The migration guide explicitly addresses testing, including the fact that mongomock-motor does not apply to PyMongo Async.
References
- Motor deprecation notice: [!https://www.google.com/s2/favicons?domain=mongodb.com&sz=64!https://www.mongodb.com/docs/drivers/motor/]
- Migrate to PyMongo Async: !https://www.google.com/s2/favicons?domain=mongodb.com&sz=64!www.mongodb.com/docs/languages/python/p…rent/reference/migration
- mongomock async feature request: https://github.com/mongomock/mongomock/issues/916
- mongomock-motor: [!https://www.google.com/s2/favicons?domain=pypi.org&sz=64!https://pypi.org/project/mongomock-motor/]
- pymongo-async-mock: [!https://www.google.com/s2/favicons?domain=pypi.org&sz=64!https://pypi.org/project/pymongo-async-mock/]
- mongodb-atlas-local image: [!https://www.google.com/s2/favicons?domain=docker.com&sz=64!https://hub.docker.com/r/mongodb/mongodb-atlas-local]