A pytest plugin that provides session-scoped MongoDB fixtures backed by Docker containers.
- Zero configuration — Fixtures work out of the box, no setup required
- Automatic lifecycle management — Pulls images, allocates ports, starts containers, and cleans up after tests
- Fast — Data directory mounted to tmpfs for maximum speed
- Version-specific fixtures — Test against MongoDB 5, 6, 7, 8, or latest
- Replica set fixtures — Drop-in variants with
--replSetenabled for change stream support - Session-scoped — One container per test session, shared across all tests
pip install pytest-mongo-docker- Python 3.10+
- pytest 8.0+
- docker 7.0+
- Docker daemon running locally or accessible via
DOCKER_HOSTenvironment variable
The plugin automatically registers fixtures when installed. Import the Mongo type for type hints:
import pymongo
import pytest_mongo_docker
def test_pymongo(mongo: pytest_mongo_docker.Mongo):
client = pymongo.MongoClient(host=mongo.host, port=mongo.port)
db = client["test_db"]
collection = db["test_collection"]
collection.insert_one({"key": "value"})
doc = collection.find_one({"key": "value"})
assert doc["key"] == "value"
client.close()All fixtures are session-scoped and return a Mongo object with host and port attributes:
Standalone (default):
mongo— Latest MongoDB version (mongo:latest)mongo_5— MongoDB 5.x (mongo:5)mongo_6— MongoDB 6.x (mongo:6)mongo_7— MongoDB 7.x (mongo:7)mongo_8— MongoDB 8.x (mongo:8)
Replica set (required for change streams and transactions):
mongo_rs— Latest MongoDB version (mongo:latest)mongo_5_rs— MongoDB 5.x (mongo:5)mongo_6_rs— MongoDB 6.x (mongo:6)mongo_7_rs— MongoDB 7.x (mongo:7)mongo_8_rs— MongoDB 8.x (mongo:8)
Replica set fixtures require pymongo (pip install pymongo) and start MongoDB with --replSet rs0. When connecting, use directConnection=True to avoid topology-discovery issues from the Docker port mapping:
client = pymongo.MongoClient(
f"mongodb://{mongo_6_rs.host}:{mongo_6_rs.port}/",
directConnection=True,
)Use session-scoped autouse fixtures to configure your application before tests run:
import os
import pytest
import pytest_mongo_docker
@pytest.fixture(scope="session", autouse=True)
def init_env(mongo_6: pytest_mongo_docker.Mongo) -> None:
os.environ["MONGODB_CONNECTION_STRING"] = f"{mongo_6.host}:{mongo_6.port}"
os.environ["MONGODB_DBNAME"] = "myapp"
def test_app():
# Your application reads from environment variables,
# no need to reference the fixture directly
passimport motor.motor_asyncio
import pytest
import pytest_mongo_docker
@pytest.mark.asyncio
async def test_motor(mongo: pytest_mongo_docker.Mongo):
client = motor.motor_asyncio.AsyncIOMotorClient(host=mongo.host, port=mongo.port)
db = client["test_db"]
collection = db["test_collection"]
await collection.insert_one({"key": "value"})
doc = await collection.find_one({"key": "value"})
assert doc["key"] == "value"
client.close()The plugin uses Docker's Python API to:
- Pull the specified MongoDB image (if not already cached)
- Allocate an unused local port
- Create a container with data directory mounted to tmpfs
- Start the container and wait for MongoDB to be ready
- Yield the
Mongoobject with connection details - Kill and remove the container after all tests complete