Skip to content

Django Testcontainers Plus

A plug-and-play testcontainers integration for Django

PyPI version License: MIT CI

Installation

pip install django-testcontainers-plus

See the full Installation Guide for extras and options.

Django Testcontainers Plus makes integration testing with real services effortless. It automatically detects the databases and services your Django project uses and spins up the right Docker containers - no manual configuration required.

Why Django Testcontainers Plus?

Testing Django applications often requires real external services like PostgreSQL, Redis, or MySQL. Mocking them is fragile. Running them manually is tedious. Django Testcontainers Plus solves this by:

  • Zero Configuration

    Automatically detects your database and service needs from Django settings - no extra setup required.

  • Plug and Play

    Install, add one line to settings, and go. No manual container management ever.

  • Multi-Database

    Full support for PostgreSQL, MySQL, and MariaDB. MongoDB and SQL Server coming soon.

  • Dual Test Runner Support

    Works with both Django's built-in test runner and pytest out of the box.

Quick Look

settings.py
TEST_RUNNER = 'django_testcontainers_plus.runner.TestcontainersRunner'

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'myapp',
    }
}

python manage.py test
conftest.py
pytest_plugins = ['django_testcontainers_plus.pytest_plugin']
settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'test',
    }
}

pytest

Supported Services

Service Auto-Detection Extra Required
PostgreSQL DATABASES engine None
MySQL / MariaDB DATABASES engine [mysql]
Redis CACHES, CELERY_BROKER_URL, SESSION_ENGINE [redis]
MongoDB Coming soon -
S3 (RustFS) STORAGES, DEFAULT_FILE_STORAGE, AWS_STORAGE_BUCKET_NAME [s3]
Elasticsearch Coming soon -

Next Steps