Install & Compatibility
Where this runs
tested against v2.12.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_postgres_fixture
✓ from pytest_mock_resources import create_postgres_fixture
Used to create a pytest fixture for a PostgreSQL database.
PostgresConfig
✓ from pytest_mock_resources import PostgresConfig
Used to customize the configuration for PostgreSQL fixtures.
create_mongo_fixture
✓ from pytest_mock_resources import create_mongo_fixture
Used to create a pytest fixture for a MongoDB database.
create_redis_fixture
✓ from pytest_mock_resources import create_redis_fixture
Used to create a pytest fixture for a Redis instance.
This quickstart demonstrates how to use `pytest-mock-resources` to create a mock PostgreSQL database. It defines a simple SQLAlchemy model, sets up a `create_postgres_fixture` that yields a SQLAlchemy session, and then shows two isolated tests creating users.
import pytest
from sqlalchemy import create_engine, text
from sqlalchemy.orm import declarative_base, sessionmaker
# Define a simple SQLAlchemy model (if using ORM)
Base = declarative_base()
class User(Base):
__tablename__ = 'users'
id = Column(Integer, primary_key=True)
name = Column(String)
def __repr__(self):
return f"<User(id={self.id}, name='{self.name}')>"
from sqlalchemy import Column, Integer, String
from pytest_mock_resources import create_postgres_fixture
# Create a PostgreSQL fixture, providing the SQLAlchemy Base and enabling session
# This fixture will provide a SQLAlchemy session object to tests that request 'pg'
pg = create_postgres_fixture(Base, session=True)
def test_user_creation(pg):
"""Test creating a user in the mock PostgreSQL database."""
# 'pg' is a SQLAlchemy session provided by the fixture
new_user = User(name='Alice')
pg.add(new_user)
pg.commit()
pg.refresh(new_user)
result = pg.execute(text("SELECT name FROM users WHERE id = :id"), {'id': new_user.id}).scalar_one()
assert result == 'Alice'
def test_another_user_creation(pg):
"""Another test, ensuring isolation between tests (new empty database)."""
# This test gets a fresh, empty database instance
assert pg.query(User).count() == 0
new_user = User(name='Bob')
pg.add(new_user)
pg.commit()
assert pg.query(User).count() == 1
Debug
Known issues
gotchaMost `pytest-mock-resources` fixtures (PostgreSQL, MongoDB, Redis, MySQL, Redshift) require Docker to be installed and running on the test environment. SQLite is a notable exception.fixEnsure Docker Desktop or a Docker daemon is active before running tests that rely on these fixtures. Refer to the official Docker documentation for installation and setup.
affects: All versions
gotchaWhile `pytest-mock-resources` provides 'extras' for installing database drivers (e.g., `[postgres]` for `psycopg2-binary`), the maintainers recommend explicitly installing these client libraries (e.g., `psycopg2-binary`, `pymongo`, `redis`) as first-party dependencies in your project. This avoids potential version conflicts or unexpected behavior.fixAlways add specific database client libraries (e.g., `pip install psycopg2-binary`) directly to your project's `requirements.txt` or `pyproject.toml` instead of relying on `pytest-mock-resources` extras.
affects: All versions
gotchaWhen using asynchronous database fixtures, you will generally need to install `pytest-asyncio` for proper fixture handling and test execution.fixInstall `pytest-asyncio` (`pip install pytest-asyncio`) and mark your async test functions with `@pytest.mark.asyncio`.
affects: All versions supporting async fixtures (>=2.0)
gotchaRunning `Redis` tests in parallel (e.g., with `pytest-xdist`) can lead to cross-test state issues if operations like `flushall` are used, as internal Redis database selection mechanisms might not fully isolate tests. The default Redis container limit also restricts simultaneous tests to 16.fixAvoid `flushall` or other global state-modifying commands in parallel Redis tests. Consider `scope='session'` for Redis if global setup is acceptable, or use distinct keyspacing for each test to prevent clashes. Be aware of the 16-test parallel limit for Redis.
affects: All versions
breakingFor PostgreSQL drivers, `pytest-mock-resources` versions 2.10.3 and 2.12.3 included fixes for improved default driver selection heuristics and compatibility with `psycopg` (specifically `psycopg2-binary` and async use with the dynamic `psycopg` drivername). If you were relying on older driver auto-detection or using `psycopg` for async, these versions might alter behavior.fixIf experiencing issues, ensure your specific PostgreSQL driver is explicitly configured using `PostgresConfig(drivername='...')` within a `pmr_postgres_config` fixture to match your setup. For `psycopg` (v3), be aware of the new installation `psycopg[binary]` vs. `psycopg2-binary`.
affects: >=2.10.3, >=2.12.3
gotchaRunning tests with `pytest-mock-resources` in CI/CD environments (e.g., CircleCI, GitLab) often requires specific Docker service configurations and environment variables to ensure the test containers are accessible.fixRefer to the `pytest-mock-resources` documentation on 'CI Support' for detailed configuration examples, including `setup_remote_docker` for CircleCI or `services: - docker:dind` and `DOCKER_HOST`, `PYTEST_MOCK_RESOURCES_HOST` environment variables for GitLab.
affects: All versions
Upgrade
Version history
2.12.4latest on PyPI · released Sep 17, 2025
Audit
Dependencies
pytestrequiredCore testing framework, as this is a pytest plugin.
DockerrequiredRequired for most container-based mock resources (PostgreSQL, MongoDB, Redis, MySQL, Redshift). SQLite is an exception.
psycopg2-binaryoptionalPostgreSQL driver. The library recommends users explicitly install database drivers for their chosen resources.
asyncpgoptionalAsynchronous PostgreSQL driver, typically used with async fixtures and sqlalchemy.ext.asyncio.
pymongooptionalMongoDB driver for the MongoDB mock resource.
redisoptionalRedis client for the Redis mock resource.
pytest-asynciooptionalGenerally recommended for testing with asynchronous fixtures.