Install & Compatibility
Where this runs
tested against v2.3.0 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.774s · 70.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.7s · import 0.685s · 71MB
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MockSet
✓ from django_mock_queries.query import MockSet
The primary class for creating mock querysets.
MockModel
✓ from django_mock_queries.query import MockModel
A utility class for creating mock model instances to populate MockSet.
monkey_patch_test_db
✓ from django_mock_queries.mocks import monkey_patch_test_db
Used to replace the real database connection with a mock one for faster tests.
This quickstart demonstrates how to create `MockSet` instances, populate them with `MockModel` objects, and perform common queryset operations like filtering, aggregation, Q-object filtering, and creating new mock objects. It mirrors typical Django ORM interactions in an in-memory test environment.
from django.db.models import Avg, Q
from django_mock_queries.query import MockSet, MockModel
# Example 1: Basic filtering
qs = MockSet(
MockModel(mock_name='john', email='john@gmail.com'),
MockModel(mock_name='jeff', email='jeff@hotmail.com'),
MockModel(mock_name='bill', email='bill@gmail.com'),
)
results = [x for x in qs.all().filter(email__icontains='gmail.com').select_related('address')]
# print(results) # Expected: [<MockModel: john>, <MockModel: bill>]
# Example 2: Aggregation
qs_agg = MockSet(
MockModel(mock_name='model s', msrp=70000),
MockModel(mock_name='model x', msrp=80000),
MockModel(mock_name='model 3', msrp=35000),
)
agg_result = qs_agg.all().aggregate(Avg('msrp'))
# print(agg_result) # Expected: {'msrp__avg': 61666.666...}
# Example 3: Filtering with Q objects
qs_q = MockSet(
MockModel(mock_name='model x', make='tesla', country='usa'),
MockModel(mock_name='s-class', make='mercedes', country='germany'),
MockModel(mock_name='s90', make='volvo', country='sweden'),
)
q_results = [x for x in qs_q.all().filter(Q(make__iexact='tesla') | Q(country__iexact='germany'))]
# print(q_results) # Expected: [<MockModel: model x>, <MockModel: s-class>]
# Example 4: Creating objects
qs_create = MockSet(cls=MockModel)
new_obj = qs_create.create(mock_name='my_object', foo='1', bar='a')
# print(new_obj) # Expected: <MockModel: my_object>
# print([x for x in qs_create]) # Expected: [<MockModel: my_object>]
Debug
Known issues
breakingVersion 2.2.0 dropped support for Python 2.x. Projects still using Python 2 must remain on `django-mock-queries<2.2.0`.fixUpgrade to Python 3.x, or pin `django-mock-queries` to a version older than 2.2.0 (e.g., `~=2.1`).
affects: >=2.2.0
gotchaWhen using `monkey_patch_test_db()` for in-memory tests, any tests that *require* actual database interaction will raise a `NotSupportedError`.fixMark tests that require a real database to skip when the mock database is active. This can often be done with decorators like `@unittest.skipIf(settings.MOCK_DB, 'Requires real DB')` or specific `django-mock-queries` features if available.
affects: All versions using `monkey_patch_test_db`
gotchaChaining mock queryset methods (e.g., `Manager.filter().order_by().exists()`) requires careful handling of `return_value` to ensure each step returns a mock object that supports subsequent method calls, not a plain list.fixEnsure that `return_value` of a chained mock method is another mock queryset (e.g., `MockSet`) or a mock configured to mimic queryset behavior (e.g., `mock_queryset.filter.return_value = mock_queryset`).
affects: All versions
gotchaComplex Q-object filters, custom lookups, or specific field types (like JSONField with list values) may not be fully replicated or might return unexpected results compared to Django's actual ORM.fixIf encountering unexpected behavior with complex filters, simplify the query for testing or manually verify the expected output. Consider testing such complex queries against a real database if fidelity is critical. Check GitHub issues for known limitations or fixes in newer versions.
affects: All versions, especially older ones
Errors
Common errors & fixes
NotSupportedError: Mock database tried to execute SQL for <Model> model.
The `monkey_patch_test_db()` function has replaced Django's database connection with a mock, and a test is attempting a real database operation.
fixIdentify tests that require a live database. Either configure your test runner to use a real database for those specific tests, or mark those tests to be skipped when `monkey_patch_test_db()` is active.
AttributeError: 'list' object has no attribute 'filter'
A mocked queryset method returned a plain Python list, and a subsequent chained queryset method (like `filter()`, `order_by()`, `exists()`) was called on it. This typically happens when `mock_object.some_method.return_value = [...]` instead of another mock queryset.
fixEnsure that any chained mock methods return another `MockSet` instance or a mock object configured to mimic a `QuerySet`'s chainable behavior. For instance, `mock_manager.filter.return_value = MockSet([...])` or if chaining itself is the goal, `mock_queryset.filter.return_value = mock_queryset`.
ModuleNotFoundError: No module named 'django_mock_queries'
The `django-mock-queries` package is not installed in the current Python environment or virtual environment.
fixInstall the library using `pip install django-mock-queries`. Ensure your virtual environment is activated if you are using one.
Upgrade
Version history
2.3.0latest on PyPI · released Sep 27, 2024
Audit
Dependencies
DjangorequiredCore functionality is built on Django's ORM concepts. Compatible with Django 3.2, 4.x, and potentially 5.x based on recent testing.