Move from a slow, brittle test suite to a fast, trustworthy one. Master pytest-django fixtures, generate data with factory_boy, find edge cases automatically with property-based testing, and measure real coverage with mutation testing.
A test suite that is slow gets skipped, and one that passes while bugs ship is worse than none — it lulls you into false confidence. Real trust comes from four properties: the suite is fast enough to run constantly, the data it exercises is realistic, it discovers edge cases you never thought of, and you can verify the tests actually catch bugs. This tutorial assembles the modern Django testing stack that delivers all four, from pytest fundamentals to mutation testing.
Test speed is not a vanity metric; it is the single biggest determinant of whether tests get run. A suite that takes twenty minutes runs once a day in CI and never on a developer's machine, so bugs are caught long after the code that caused them is out of mind. A suite that takes thirty seconds runs on every save, catching mistakes while the context is fresh and the fix is cheap. Investing in speed is therefore investing in how often the tests do their job. Everything in this tutorial is shaped by that principle — the goal is a suite fast enough that running it is reflexive, not a chore you postpone.
Django ships with a unittest-based test runner, but pytest is the ecosystem standard for good reason: plain assert statements instead of self.assertEqual ceremony, powerful fixtures for setup, and parametrization to run one test across many inputs. The pytest-django plugin wires it into Django's database and settings:
pip install pytest-django pytest-xdist
# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
addopts = --reuse-db -n auto
python_files = test_*.py
Two flags do most of the speed work. --reuse-db keeps the test database between runs instead of recreating the schema every time, and -n auto (from pytest-xdist) distributes tests across all your CPU cores. Together they routinely cut suite time by five to ten times, turning a coffee-break run into a few seconds.
The flags handle the database and the CPU, but a surprising amount of suite time is spent in places nobody looks. Django's default password hasher is deliberately slow — hundreds of thousands of PBKDF2 iterations per call — so every factory that sets a password and every login in a test pays for it. Swapping in a fast hasher for tests is safe because you are not testing the hashing algorithm, and it commonly shaves double-digit percentages off suites with many authenticated tests:
# conftest.py
import pytest
@pytest.fixture(autouse=True)
def _fast_test_settings(settings):
settings.PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]
settings.CELERY_TASK_ALWAYS_EAGER = True # only if the project uses Celery
settings.CACHES = {
"default": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"}
}
The settings fixture from pytest-django restores the original values after each test, so these overrides never leak. For values that should hold for the whole run, a dedicated myproject/settings/test.py pointed to by DJANGO_SETTINGS_MODULE is cheaper still, because nothing is patched per test. Django's test environment setup already switches the email backend to the in-memory locmem backend, so outgoing mail lands in django.core.mail.outbox rather than a real SMTP server.
Remember that --reuse-db does not notice new migrations on its own. After pulling a branch that changes the schema, run once with --create-db to rebuild. The --nomigrations flag goes further and builds the schema straight from the current models, skipping the migration history entirely; it is much faster on projects with hundreds of migrations, but it means your tests never execute a migration, so keep at least one CI job that runs with migrations enabled.
By default pytest-django blocks database access: a test that touches the ORM without the @pytest.mark.django_db marker (or a fixture that requests db) fails immediately. Treat this as a feature. It makes the slow, database-bound tests explicit, and it nudges pure logic into tests that never need a database at all — the cheapest tests you will ever run.
Fixtures are pytest's dependency-injection mechanism: a function that builds something a test needs, requested simply by naming it as an argument. They compose, they have scopes (per-function, per-module, per-session) so expensive setup can be shared, and they replace the brittle setUp methods of unittest. A well-designed set of fixtures makes tests read like a description of the scenario rather than a pile of boilerplate, and shared session-scoped fixtures for costly resources keep the suite fast. Lean on them to express "given an authenticated user with an active subscription" in one named argument.
Hand-built test objects are tedious and static fixtures rot as your models evolve. factory_boy generates valid, varied objects on demand, declaring only the fields a given test cares about and filling the rest with sensible or random values:
import factory
class OrderFactory(factory.django.DjangoModelFactory):
class Meta:
model = Order
customer = factory.SubFactory(UserFactory)
total = factory.Faker("pydecimal", left_digits=3, positive=True)
@factory.post_generation
def items(self, create, extracted, **kw):
if create:
OrderItemFactory.create_batch(extracted or 3, order=self)
order = OrderFactory() # fully built, with 3 items
big = OrderFactory(total=Decimal("9999")) # override only what matters
Factories keep tests focused on the one thing under test by hiding the irrelevant setup, and because they build real, valid objects they catch model-level issues that hard-coded dictionaries would miss.
Not all tests earn their keep. Focus on your own business logic, the branches and edge cases of code you wrote, and the integration points where things actually break. Do not write tests that merely re-assert Django's own behavior — that a CharField stores a string — because you are testing the framework, not your code. Aim for a healthy pyramid: many fast unit tests around pure logic, fewer integration tests around views and database interactions, and a small number of end-to-end tests for critical user journeys. A suite weighted toward slow end-to-end tests is both fragile and sluggish; one weighted toward fast focused tests is the opposite.
Example-based tests only check the cases you imagined, which means the bug hiding in the case you did not imagine survives. Property-based testing inverts this: you describe the shape of valid inputs and an invariant that must always hold, and Hypothesis generates hundreds of inputs trying to break it:
from hypothesis import given, strategies as st
@given(st.decimals(min_value=0, max_value=10**6, places=2),
st.integers(min_value=0, max_value=100))
def test_discount_never_exceeds_total(price, percent):
result = apply_discount(price, percent)
assert 0 <= result <= price # an invariant, for ALL inputs
You assert a property — "a discount never makes the price negative or larger than the original" — instead of specific numbers, and Hypothesis hunts for a counterexample across the whole input space. This is where the gnarly edge cases surface: the zero, the boundary, the value with too many decimal places.
Hypothesis runs your test body many times inside a single test function, which interacts awkwardly with pytest's function-scoped fixtures: the fixture is set up once, but the body runs a hundred times, so database rows from one example leak into the next. Hypothesis detects this and raises a function_scoped_fixture health-check error rather than silently producing misleading results. For pure functions like apply_discount this never arises. For code that needs the ORM, use hypothesis.extra.django.TestCase, which wraps each generated example in its own transaction (and from_model when you want Hypothesis to derive valid model instances from field definitions):
from decimal import Decimal
from hypothesis import given, example, strategies as st
from hypothesis.extra.django import TestCase
class TestOrderTotals(TestCase):
@given(st.lists(st.decimals(min_value=0, max_value=1000, places=2), max_size=20))
@example([]) # pin the empty-order regression forever
def test_total_equals_sum_of_lines(self, prices):
order = OrderFactory()
OrderItem.objects.filter(order=order).delete() # start from an empty order
for p in prices:
OrderItemFactory(order=order, price=p)
assert order.recalculate_total() == sum(prices, Decimal("0"))
The @example decorator deserves a habit: whenever Hypothesis finds a bug, add the shrunk counterexample as an explicit example so that exact case is checked on every run, not just when the search happens to rediscover it. Hypothesis also stores failing examples in a local .hypothesis/ directory and replays them first on the next run, which is why the directory is worth caching (not committing) in CI.
How hard Hypothesis searches is a dial you control per environment. A developer wants a quick signal; the nightly job can afford a thorough hunt:
# conftest.py
import os
from hypothesis import settings, HealthCheck
settings.register_profile("dev", max_examples=50)
settings.register_profile("ci", max_examples=200, deadline=None)
settings.register_profile("nightly", max_examples=2000, deadline=None,
suppress_health_check=[HealthCheck.too_slow])
settings.load_profile(os.environ.get("HYPOTHESIS_PROFILE", "dev"))
Setting deadline=None on shared CI runners is pragmatic: the default per-example deadline of 200 ms can trip on a noisy machine and produce a flaky failure that has nothing to do with correctness. Keep the deadline locally if you want Hypothesis to flag genuinely slow code paths.
When Hypothesis finds a failing input, it does not just hand you the random monster it stumbled on — it shrinks it to the minimal example that still fails. A bug first triggered by some baroque 14-digit decimal gets reduced to, say, exactly 0.005, which tells you precisely what edge case your code mishandles. This automatic minimization turns "a random input broke something" into "this specific boundary value is the bug," which is the difference between a frustrating mystery and an obvious fix. It is the feature that makes property-based testing practical rather than merely interesting.
Much of a Django app's risk lives at the database boundary — queries, transactions, constraints, migrations. Test that your queries return what you expect with realistic factory data, that unique and check constraints actually reject bad data, and that transactional logic rolls back correctly on failure. Pay special attention to migrations: a migration that works on an empty test database can fail or lock a large production table, so test data migrations against representative data and review schema migrations for locking behavior. The database is where correctness and performance meet, and it deserves focused tests.
Performance regressions are bugs too, and the most common one in Django is the N+1 query that creeps in when someone adds a field to a serializer or template. Catch it in tests by asserting a maximum query count, so the regression fails CI instead of paging you later:
def test_order_list_query_budget(client, django_assert_max_num_queries):
with django_assert_max_num_queries(4):
resp = client.get("/api/v1/orders/")
assert resp.status_code == 200
This turns an invisible, gradual slowdown into a hard, visible failure at the exact commit that introduced it. Add a query budget to every list endpoint and any view that renders collections; it is one of the highest-value tests you can write in Django.
Code coverage measures which lines ran during the tests, and it is useful for finding code that no test touches at all. But it is widely misunderstood: 100% coverage does not mean your code is correct, only that every line executed. A line can run during a test without that test asserting anything about its behavior, so a bug on a fully-covered line can sail through. Coverage tells you what is untested; it does not tell you what is well-tested. Treat it as a floor — find and cover the gaps — not as a goal you optimize to a meaningless 100%.
If coverage cannot tell you whether your tests actually catch bugs, what can? Mutation testing. It deliberately injects small bugs into your code — flipping a < to <=, a + to a -, removing a line — and reruns your tests. If a test fails, it "killed the mutant," proving the test detects that class of bug. If all tests still pass, the mutant survived, which means you have a blind spot: code whose behavior no test actually verifies.
pip install mutmut
mutmut run
mutmut results # surviving mutants = untested behavior to fix
Mutation testing is slower than the rest of your suite, so run it periodically or on critical modules rather than on every commit. But it is the only technique that directly answers the question that matters — do my tests bite? — and it routinely reveals confidently-covered code that is, in truth, untested.
Consider a small function with a boundary and a test that looks thorough:
def shipping_fee(subtotal: Decimal) -> Decimal:
if subtotal >= Decimal("50"):
return Decimal("0")
return Decimal("4.99")
def test_shipping_fee():
assert shipping_fee(Decimal("10")) == Decimal("4.99")
assert shipping_fee(Decimal("100")) == Decimal("0")
Coverage reports 100%: both branches run. mutmut, however, changes >= to >, and the test still passes, because nothing checks a subtotal of exactly 50. The surviving mutant tells you precisely which business rule is unguarded — "is free shipping at 50 or above 50?" — and the fix is one line, assert shipping_fee(Decimal("50")) == Decimal("0"). Use mutmut show with the mutant's identifier to see the diff for each survivor; working through the list this way is usually a series of small, sharp boundary tests rather than a large rewrite.
Not every survivor is a real gap. An equivalent mutant changes the code without changing observable behavior — mutating a log message, or a default value that is always overridden — and no test can kill it. Mark such lines with a # pragma: no mutate comment so they stop appearing in reports, and track the mutation score (killed divided by total) per module over time rather than chasing 100%.
To keep runtime tolerable, restrict mutation to the modules where bugs are expensive — pricing, permissions, billing, state machines — through mutmut's paths_to_mutate setting in setup.cfg or pyproject.toml, and make sure the test command it runs is itself fast: no --create-db, no coverage collection, and ideally only the tests relevant to the mutated module. Mutation testing multiplies every inefficiency in your suite by the number of mutants, which is one more reason the speed work from the start of this tutorial matters.
The stack pays off when it runs automatically on every change. In CI, run the fast pytest suite in parallel on every push, gate merges on it passing, enforce a coverage floor to catch untested new code, and schedule the slower mutation and full property-based runs on a nightly cadence. Cache dependencies and reuse the test database to keep CI fast, because the same speed principle applies — a slow CI pipeline is one developers learn to ignore or route around. The goal is a pipeline that gives a clear, fast green-or-red signal on every change, with the deeper checks running where their cost is affordable.
Every test must be independent — able to run alone, in any order, and in parallel — or you get the worst kind of failure: the flaky test that passes sometimes and fails others. Flakiness usually comes from shared state leaking between tests: a database row not rolled back, a cache not cleared, a global mutated, or a dependence on test execution order. pytest-django wraps each test in a transaction that rolls back automatically, which handles the database, but you must reset caches and other global state yourself. Flaky tests are corrosive because they teach developers to ignore failures, so hunt them down and fix the isolation leak rather than re-running until green.
Order dependence is the most common cause and the easiest to prove. The pytest-randomly plugin shuffles test order on every run and prints the seed it used, so a hidden dependency eventually surfaces as a failure, and pytest -p randomly --randomly-seed=12345 replays the exact order that failed. Once reproducible, bisect: run the failing test alone (if it passes, some earlier test is polluting state), then run it together with halves of the preceding tests until you find the polluter. Common culprits and their remedies:
| Symptom | Likely cause | Remedy |
|---|---|---|
| Passes alone, fails in the full run | Cache, module-level global, or class attribute mutated by another test | Autouse fixture calling cache.clear(); avoid module-level mutable state |
Fails only under -n auto | Shared filesystem path or port between workers | Use the tmp_path fixture; never hard-code file paths |
| Fails around midnight or month end | date.today() or timezone.now() in code and test | Freeze time with a library such as time-machine or freezegun |
| Fails intermittently on ordering | Query without order_by; PostgreSQL row order is not guaranteed | Order explicitly in code, or compare as sets in the test |
on_commit callback never fires | Test transaction never commits | django_capture_on_commit_callbacks(execute=True) fixture |
The last row trips up many teams. Because pytest-django wraps each test in a transaction that is rolled back, callbacks registered with transaction.on_commit() — sending a confirmation email, enqueuing a task — never run. Rather than switching the test to @pytest.mark.django_db(transaction=True), which truncates tables after each test and is dramatically slower, capture and execute the callbacks explicitly:
@pytest.mark.django_db
def test_order_confirmation_sent(django_capture_on_commit_callbacks, mailoutbox):
with django_capture_on_commit_callbacks(execute=True) as callbacks:
place_order(OrderFactory.build())
assert len(callbacks) == 1
assert mailoutbox[0].subject.startswith("Order confirmed")
Reserve transaction=True for code that genuinely depends on real commits or on database-level behavior across connections, such as select_for_update contention tests, and keep those tests in a small, clearly marked group.
Tests must not call real external services — payment providers, email APIs, third-party endpoints — because that makes them slow, unreliable, and dependent on systems you do not control. Mock these boundaries so your tests exercise your code's handling of the responses, including the error and timeout cases that are hard to trigger for real. The discipline is to mock at the edge of your own code, not deep in someone else's library, and to test that your code does the right thing for each response shape. For higher confidence, complement mocks with a small number of contract tests that verify your assumptions about the external API still hold.
When separate teams or services depend on your API, a change that is innocuous to you can break them silently. Contract testing guards that boundary: it pins the agreed shape of requests and responses, so a breaking change fails a test instead of a partner's integration. Snapshot tests of your API responses serve a similar role, catching unintended changes to the payload shape, while a generated OpenAPI schema checked into CI surfaces contract drift as a reviewable diff. These techniques make the implicit contract between producer and consumer explicit and enforced, which is exactly what you want when other people build on your API.
Unit tests confirm correctness; they say nothing about behavior under load. Load testing — with a tool like Locust or k6 — simulates many concurrent users to find where your system degrades, what your real throughput ceiling is, and which endpoint falls over first. Run it against a production-like environment with realistic data volumes, because performance characteristics change dramatically with scale, and a system that is snappy with a hundred rows can crawl with a million. Establish a baseline, then re-run after significant changes to catch performance regressions before your users do. Load testing turns "we think it will handle launch" into a number you can trust.
As a suite grows, test data management becomes its own discipline. Factories should produce the minimal valid object for each test, overriding only the fields under test, so the intent of each test stays legible and changes to a model do not ripple through hundreds of hard-coded fixtures. Avoid large shared fixture files that every test depends on — they become brittle and slow, and a change to satisfy one test breaks others. Keep data setup local and explicit, lean on factories for variation, and your tests stay readable and resilient as the codebase evolves. Good test data hygiene is what keeps a large suite maintainable rather than a liability.
A trustworthy Django suite has four properties, each from a specific tool. It is fast — pytest with --reuse-db and -n auto — because speed determines how often tests run. It uses realistic data from factory_boy so tests exercise real, valid objects without boilerplate. It discovers edge cases automatically through Hypothesis, whose shrinking reduces a failure to its minimal cause. And it is validated by mutation testing, which proves the tests actually catch bugs where coverage only proves lines ran. Around that core, focus tests on your own logic, guard performance with query budgets, treat coverage as a floor not a goal, and wire it all into a fast CI pipeline. Coverage tells you what ran; mutation testing tells you what is protected — build toward the latter.