Test Django Apps with factory_boy and pytest (2026)

factory_boy and pytest are your go-to combo for writing robust tests for Django applications, but getting them to play nice requires a few specific configurations.

Here’s a look at how to set them up and use them effectively:

First, let’s see factory_boy in action. Imagine you have a simple Django model:

# myapp/models.py
from django.db import models

class Project(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField(blank=True)
    is_active = models.BooleanField(default=True)

    def __str__(self):
        return self.name

Now, let’s create a factory for this Project model:

# myapp/factories.py
import factory
from .models import Project

class ProjectFactory(factory.Factory):
    class Meta:
        model = Project

    name = factory.Sequence(lambda n: f"Project {n}")
    description = "A default project description."
    is_active = True

This ProjectFactory will generate Project objects. factory.Sequence is handy for ensuring uniqueness in fields like names, automatically incrementing n for each new object created.

With pytest and pytest-django, you can easily use these factories in your tests. Make sure you have pytest and pytest-django installed:

pip install pytest pytest-django factory-boy

And configure pytest-django in your pytest.ini or pyproject.toml:

# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = your_project.settings

Here’s a basic test using the factory:

# myapp/tests/test_projects.py
import pytest
from myapp.models import Project
from myapp.factories import ProjectFactory

def test_project_creation():
    project = ProjectFactory()
    assert isinstance(project, Project)
    assert project.name.startswith("Project ")
    assert project.description == "A default project description."
    assert project.is_active is True

def test_project_with_custom_attributes():
    custom_project = ProjectFactory(name="Specific Project", is_active=False)
    assert custom_project.name == "Specific Project"
    assert custom_project.is_active is False

def test_multiple_projects_creation():
    projects = ProjectFactory.create_batch(5)
    assert len(projects) == 5
    for i, project in enumerate(projects):
        assert project.name == f"Project {i}"

The ProjectFactory() call creates a single instance of your Project model, populating it with default values from the factory. You can override these defaults by passing keyword arguments, as shown in test_project_with_custom_attributes. create_batch(n) is a convenient way to generate n instances.

The core problem factory_boy solves is the tediousness of creating realistic test data. Manually instantiating Django models with all their required fields (and potentially related objects) for every test case is repetitive and error-prone. factory_boy abstracts this away. When you call ProjectFactory(), it instantiates the Project model and sets its attributes according to the factory definition. If your model had foreign keys or many-to-many fields, factory_boy could also automatically create or associate related objects, simplifying complex data setup.

Internally, factory_boy uses a declarative syntax to define factories. The class Meta inner class links the factory to a specific Django model. Attributes of the factory correspond directly to model fields. factory.Sequence, factory.Faker (for generating realistic fake data), and factory.LazyAttribute (for attributes that depend on other attributes within the same factory) are powerful tools for generating dynamic and varied test data.

pytest-django provides fixtures and integration that make factory_boy work seamlessly within the pytest ecosystem. Crucially, pytest-django manages database transactions for your tests. By default, each test function runs in its own transaction, which is rolled back afterward. This means factory_boy creations are isolated to a single test, preventing test pollution and ensuring that tests don’t interfere with each other. You don’t need to explicitly clean up the database after each test when using pytest-django with factories.

When using factory_boy, the most common point of confusion is how to handle related objects, especially when setting up complex test scenarios. For instance, if Project had a ForeignKey to a User model:

# myapp/models.py (updated)
class Project(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField(blank=True)
    is_active = models.BooleanField(default=True)
    owner = models.ForeignKey('auth.User', on_delete=models.CASCADE)

    def __str__(self):
        return self.name

You’d update the factory like this:

# myapp/factories.py (updated)
import factory
from django.contrib.auth.models import User
from .models import Project

class UserFactory(factory.Factory):
    class Meta:
        model = User

    username = factory.Sequence(lambda n: f"user{n}")
    email = factory.Sequence(lambda n: f"user{n}@example.com")

class ProjectFactory(factory.Factory):
    class Meta:
        model = Project

    name = factory.Sequence(lambda n: f"Project {n}")
    description = "A default project description."
    is_active = True
    owner = factory.SubFactory(UserFactory) # This is key!

The factory.SubFactory(UserFactory) tells factory_boy to create a User using UserFactory whenever a Project is created and assign it to the owner field. This automatically handles the creation of dependent objects without you needing to explicitly call UserFactory() in your test.

The next concept to explore is using factory.Faker for generating more realistic and varied data, moving beyond simple sequences.