Your Django tests use the wrong media storage

Green tests, broken uploads, untestable code. Test with the backend you ship, even if it’s django-storages’ S3.

You don’t want tests hitting a real S3 bucket. Smart. So you use FileSystemStorage instead, and your settings might look something like this:

ENV = os.environ.get("ENV", "production")

if ENV in {"test", "local"}:
    STORAGES = {
        "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
    }
else:
    STORAGES = {
        "default": {"BACKEND": "storages.backends.s3.S3Storage"},
    }

Look familiar?

Same API, different implementations

FileSystemStorage and S3Storage share Django’s storage API, but they don’t implement it the same way. .path works on disk and raises NotImplementedError on S3. url(name, expire=60) works on S3 and raises TypeError on disk. Code that runs on one backend breaks on the other, in both directions, and bridging the gap means environment checks, mocks and pain you never needed.

Say you write a model that extracts text from uploaded PDFs, and a test for it:

from django.db import models
from pypdf import PdfReader


class Document(models.Model):
    file = models.FileField()
    text = models.TextField(blank=True)

    def save(self, **kwargs):
        super().save(**kwargs)
        self.text = PdfReader(self.file.path).pages[0].extract_text()
        super().save(update_fields=["text"])
def test_extracts_text_on_upload(db) -> None:
    pdf = Path("tests/hello.pdf").read_bytes()
    document = Document.objects.create(file=ContentFile(pdf, name="hello.pdf"))
    assert document.text == "Hello"

It passes. Uploading a PDF in local dev works too, because runserver uses the same FileSystemStorage.

In production, every upload returns a 500:

NotImplementedError: This backend doesn't support absolute paths.

S3 objects have keys, not paths. The test exercised a storage backend you never deploy, so it couldn’t catch this.

This has bitten me more than once, on different projects, and it keeps biting whenever storage backends are mixed. It leads to one of two things: conditionals in the code that branch on the backend (and gaps in code coverage), or tests that patch objects to imitate production, like patching FieldFile.path to raise. Either way, your tests aren’t running the code production runs.

Wouldn’t it be simpler if your tests ran the same code, and got the same behavior, as production?

Now the reverse. A download link that expires after a minute:

# documents/links.py
from django.core.files.storage import default_storage


def get_download_url(name: str) -> str:
    return default_storage.url(name, expire=60)

This works on S3. Under FileSystemStorage, it raises:

TypeError: FileSystemStorage.url() got an unexpected keyword argument 'expire'

So the test reaches for a patch:

from unittest.mock import patch


def test_get_download_url() -> None:
    with patch("documents.links.default_storage") as storage:
        url = get_download_url("report.pdf")
    # A MagicMock, not a URL: nothing was built or signed.
    assert url == storage.url.return_value
    # Proves only that a method was called with these arguments.
    storage.url.assert_called_once_with("report.pdf", expire=60)

It passes, but it’s unreadable and brittle.

The patch target is also a string tied to a module path. Move get_download_url to a different module and the test breaks, even though no behavior changed.

Fake S3, not your code

Both problems have one cause: tests run different storage code than production. Keep the production STORAGES setting in tests, and fake only what sits behind it: S3 itself.

moto does exactly that. It intercepts boto3’s HTTP calls in-process and answers them from an in-memory S3. django-storages, botocore’s request signing and your code all run as they do in production. Nothing is patched in your code.

uv add --dev "moto[s3]"

Then, activate moto using pytest fixtures in conftest.py:

import boto3
import pytest
from moto import mock_aws


@pytest.fixture(scope="session")
def s3_bucket():
    with mock_aws():
        bucket = boto3.resource("s3", region_name="us-east-1").Bucket("test-bucket")
        bucket.create()
        yield bucket


@pytest.fixture(autouse=True)
def _configure_s3_storage(s3_bucket, settings):
    settings.AWS_STORAGE_BUCKET_NAME = s3_bucket.name
    settings.AWS_S3_REGION_NAME = "us-east-1"
    settings.AWS_S3_ACCESS_KEY_ID = "FOOBARKEY"
    settings.AWS_S3_SECRET_ACCESS_KEY = "FOOBARSECRET"
    settings.AWS_SESSION_TOKEN = None
    yield
    s3_bucket.objects.all().delete()

The first fixture is session-scoped: moto starts once, and the bucket lives for the whole run. The second wraps every test. It points Django’s settings at the bucket, then empties it, so each test starts clean, the same way Django rolls back the database between tests.

It’s also pytest-xdist safe: each worker is a separate process with its own in-memory S3, so parallel tests never share a bucket. And because the second fixture pins the bucket, region and keys, nothing in a developer’s local AWS setup can change the result.

The bucket is created in us-east-1 because any other region requires a location constraint. FOOBARKEY and FOOBARSECRET are moto’s own fake keys: setting them overrides any real keys your settings pull from the environment, and clearing the session token keeps an SSO login out of the signed URL.

Both problems, revisited

The upload test now fails at your desk, as production does:

NotImplementedError: This backend doesn't support absolute paths.

You find out before your users do. The fix is to drop .path, since PdfReader accepts the file itself:

self.text = PdfReader(self.file).pages[0].extract_text()

The FieldFile.path patch goes too. Every extraction test now saves through S3, so putting .path back fails all of them, without a patch in sight.

The download link needs no patch. Freeze the clock so botocore builds a deterministic signature, then assert the whole URL:

from freezegun import freeze_time


@freeze_time("2026-01-01T00:00:00Z")
def test_get_download_url() -> None:
    assert get_download_url("report.pdf") == (
        "https://test-bucket.s3.amazonaws.com/report.pdf"
        "?AWSAccessKeyId=FOOBARKEY"
        "&Signature=czVxGgUiu6%2By761DsGaghxpyRrQ%3D"
        "&Expires=1767225660"
    )

That’s the real URL, built and signed by botocore, with an expiry exactly 60 seconds out. Move get_download_url anywhere you like: there’s no module path in the test to go stale.

Conclusion

Replacing storage in tests replaces the code you most need to check. Code that only works on disk passes its tests and fails in production, and vice versa.

Keep the production storage. Fake the underlying server and HTTP layer instead. If it breaks in production, it breaks in your tests first.

Everything in this post runs as a single-file nanodjango project in this gist. Run it with:

uv run https://gist.github.com/marcgibbons/089fbf1518ebbcb700cf2bf6ce8fc5d0
Marc Gibbons

About the author

Marc Gibbons

Marc caught the programming bug as a child when the internet was still text-based and accessed by a 9600 baud modem. His career path is unique; he initially studied music and played the oboe professionally with …

View Marc's profile