ExportXMLWordPrintableJSON

    • Type: Improvement
    • Resolution: Won't Do
    • Priority: Major - P3
    • None
    • Affects Version/s: 4.16.0
    • Component/s: None
    • None
    • Python Drivers
    • Hide

      1. What would you like to communicate to the user about this feature?
      2. Would you like the user to see examples of the syntax and/or executable code and its output?
      3. Which versions of the driver/connector does this apply to?

      Show
      1. What would you like to communicate to the user about this feature? 2. Would you like the user to see examples of the syntax and/or executable code and its output? 3. Which versions of the driver/connector does this apply to?
    • 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:

      1. An officially supported, in-memory test double for MongoClient and AsyncMongoClient (either a package maintained by MongoDB, or MongoDB-sponsored async support in mongomock).
      2. 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.
      3. 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

            Assignee:
            Jib Adegunloye
            Reporter:
            Jarmo Nieminen
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: