pytest-mongo

What is this?

This is a pytest plugin that helps you test code that relies on a running MongoDB database. It provides fixtures for a MongoDB process and client.

How to use

Runtime requirements are defined in pyproject.toml.

The plugin contains three fixtures:

• mongodb - a function-scoped client fixture that cleans MongoDB at the end of each test.

• mongo_proc - a session-scoped fixture that starts a MongoDB instance on first use and stops it at the end of the test session.

• mongo_noproc - a no-process fixture that connects to an already running MongoDB instance. For example, on dockerized test environments or CI providing MongoDB services.

Simply include one of these fixtures in your test or fixture list.

Both mongo_proc and mongo_noproc support authentication via the username, password, and auth_source arguments. When username is passed to mongo_proc, mongod is started with --auth and the user is created via the MongoDB localhost exception, so subsequent connections authenticate with that account. The mongo_noproc fixture additionally accepts tls and a full uri for connecting to existing servers.

You can also create additional MongoDB client and process fixtures if you need to:

from pytest_mongo import factories

mongo_my_proc = factories.mongo_proc(port=None)
mongo_my = factories.mongodb('mongo_my_proc')

mongo_external = factories.mongodb('mongo_noproc')

mongo_auth_proc = factories.mongo_noproc(
    host="mongo.example.com",
    port=27017,
    username="user",
    password="secret",
    auth_source="admin",
    tls=True,
)
mongo_auth = factories.mongodb("mongo_auth_proc")

mongo_uri_proc = factories.mongo_noproc(
    uri="mongodb://<user>:<password>@mongo.example.com:27017/?authSource=admin"
)

Managed databases

The mongodb fixture manages one database - test by default - and empties it at the end of each test by dropping its non-system.* collections. Nothing else on the instance is touched, so preseeded data survives and tests running in parallel against a shared MongoDB instance do not clear each other’s databases.

Point the fixture at a different database with dbname:

from pytest_mongo import factories

mongo_my = factories.mongodb("mongo_proc", dbname="orders")

A single MongoClient can reach every database on the server, so one test may legitimately use several. Name the further ones in dbs and they are managed alongside dbname:

mongo_my = factories.mongodb("mongo_proc", dbname="orders", dbs=["customers"])

dbs is optional, and dbname on its own is enough for most suites. Collections are what gets dropped, so the fixture needs no privileges beyond the ones it has always needed. admin, config and local are MongoDB’s own databases and cannot be managed.

When several xdist workers share one MongoDB instance, give each worker its own database name so they never clear each other’s data:

import os

from pytest_mongo import factories

worker = os.environ.get("PYTEST_XDIST_WORKER", "master")
mongo_my = factories.mongodb("mongo_noproc", dbname=f"orders-{worker}")

Configuration

You can define settings in three ways: fixture factory argument, command line option, and pytest.ini configuration option. You can pick which you prefer, but remember that these settings are handled in the following order:

• Fixture factory argument

• Command line option

• Configuration option in your pytest.ini file

Example usage:

• pass it as an argument in your own fixture

  mongo_proc = factories.mongo_proc(port=8888)

• pass additional mongod parameters via a single string

  mongo_proc = factories.mongo_proc(
      params="--quiet --setParameter diagnosticDataCollectionEnabled=false"
  )

• use --mongo-port command line option when you run your tests

  pytest tests --mongo-port=8888

• specify your port as mongo_port in your pytest.ini file.

  To do so, put a line like the following under the [pytest] section of your pytest.ini:

  [pytest]
  mongo_port = 8888

Compatibility (tested)

CI covers MongoDB 7.0 and 8.0; other versions may work but aren’t tested.