Skip to main content

Test utilities for easily testing Django data migrations

Project description

PyPI version Downloads codecov

Django Data Migration Test

Test utilities for easily testing Django data migrations


pip install django-test-data-migrations


Define the following functions in your migration file

  1. data_forward(*args)
  2. data_backward(*args) (optional)
from django_test_data_migrations import DataMigrationsTestCaseBase

from app_a.models import Animal

class YourDataMigrationTestCase(DataMigrationsTestCaseBase):
    def test__forward_migration__something_important(self):
        # Prepare some data

        # Run
        self.data_forward(some_arg_0, some_arg_1, ...)

        # Some assertions
    def test__backward_migration__something_important(self):
        # Prepare some data

        # Run
        self.data_backward(some_arg_0, some_arg_1, ...)

        # Some assertions


Say you have a simple Django project with following general structure

└── app_a
    ├── migrations
    │   ├──
    │   ├──
    │   └──
    └── tests

with the following model

from django.db import models

class Animal(models.Model):
    species = models.CharField(blank=False, null=False, max_length=50)
    name = models.CharField(blank=False, null=False, max_length=100)

    def __str__(self):
        return f"Animal [name={}, species={self.species}]"

along with the following migration

# app_a/migrations/

from django.db import migrations


def data_forward(Animal):
    for animal in Animal.objects.all(): += SUFFIX

def data_backward(Animal):
    for animal in Animal.objects.filter(name__endswith=SUFFIX): =

def forward(apps, schema_editor):
    Animal = apps.get_model("app_a", "Animal")

def backward(apps, schema_editor):
    Animal = apps.get_model("app_a", "Animal")

class Migration(migrations.Migration):

    dependencies = [
        ('app_a', '0001_initial'),

    operations = [
        migrations.RunPython(forward, backward),

You can test it as the following

from django_test_data_migrations import DataMigrationsTestCaseBase

from app_a.models import Animal

class DataMigrationsTestCase(DataMigrationsTestCaseBase):
    app_name = "app_a"
    migration_name = "0002_datafix_addsuffixtoname"

    def test__data_forward__append_suffix_to_name(self):
        # Prepare data before migration
        dog = Animal.objects.create(name="Dog", species="dog")
        cat = Animal.objects.create(name="Cat", species="cat")

        # Run `data_forward` aka the entry point to your data migration

        # Make your assertions
        self.assertEqual(Animal.objects.get(, "Dog ZZ")
        self.assertEqual(Animal.objects.get(, "Cat ZZ")

    def test__data_backward__append_suffix_to_name(self):
        dog = Animal.objects.create(name="Dog ZZ", species="dog")
        cat = Animal.objects.create(name="Cat zz", species="cat")


        self.assertEqual(Animal.objects.get(, "Dog")
        self.assertEqual(Animal.objects.get(, "Cat zz")

Why would you need this library?

  1. It runs your data migration test very fast.
  2. It encourages developers to write data-related Django migrations separately from model definition related Django migrations
  3. Writing tests for data related migrations is extremely important, but it's either tricky to do or very run-time consuming. This library intends to enable testing data migrations easy and fast



Check requirements

poetry --version

Clone source code repository

git clone

Install dev dependencies

poetry install

Run tests

make test

You should be ready to start development


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-test-data-migrations-0.1.2.tar.gz (4.5 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page