Skip to main content

Factories for your Django models that can be used as Pytest fixtures.

Project description


Python package

Factories for your Django models that can be used as Pytest fixtures. Re-use them implicitly for instantiating related objects without much boilerplate code.

>>> book = book_factory(title="Calvin & Hobbes", author__name="Bill Watterson")
>>> book
<Book: Calvin & Hobbes>
<Author: Bill Watterson>


Write a fixture for your Django model by using the Factory class:

import pytest
from django_factories import Factory
from .models import Author

def author_factory(request):
    factory = Factory(Author)
    return factory(request)
def test_function(author_factory):
    author = author_factory(name="Bill Watterson")

:notebook: Note The request passed to the fixture function is a pytest fixture itself and provides information about the test function requesting the fixture. See pytest documentation.

Default values

A plain Factory will, of course, instantiate the object with the defaults given at the model definition. If you want to set defaults for the factory specifically, you can pass them to the Factory as additional keyword arguments:

def author_factory(request):
    defaults = {
        "first_name": "William",
        "last_name": "Watterson",
        "birthdate": "1958-07-05",
    return Factory(Author, **defaults)(request)

Related objects

If you want to test a model which depends on another object being present, the Factory class will try to look up a matching factory fixture for that ForeignKey field and create the related object automatically for you. Attributes for the related object can be specified in the same double-underscore syntax that you're familiar with from Django's queryset lookups:

def author_factory(request):
    return Factory(Author)(request)

def book_factory(request):
    return Factory(Book)(request)

def test(book_factory):
    book = book_factory(

This only works if there is a factory fixture available to create the related object. Factory will look for a fixture named <field>_factory. If you have a fixture that you named differently (or you have multiple fixtures for that particular model), you can specify a custom fixture name:

def book_factory(request):
    return Factory(

Passing object instances as keyword arguments instead works as well, of course:

book = book_factory(

Database usage

You can use Factory to instantiate objects in memory and also to create them in the database directly via Model.objects.create(). If your test function is marked to use the database, the objects will be saved to the database. Unmarked tests will only create objects in memory.

Customizing a factory

The Factory can be subclassed and you can override its create(**kwargs) method to customize how objects are instantiated. Here's an example of an auto-enumerating factory for a Book model:

from itertools import count

def book_factory(request):
    counter = count(1)

    class BookFactory(Factory):
        model = Book

        def create(self, **kwargs):
            return super().create(**kwargs, title=f"Book {next(counter)}")

    return BookFactory()(request)


pip install pytest-django-factories


All contributions are welcome. To check out the development version and run the tests, follow these steps:

git clone
cd pytest-django-factories
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Similar projects

When I wrote this library, I needed a quick and easy way to create related objects using Pytest fixtures. I didn't know about pytest-factoryboy, which allows registering the powerful factories from factory_boy for Pytest's fixture dependency injection.

Basically, pytest-django-factories is a less-feature-packed combination of both factory_boy and pytest-factoryboy that will hopefully help you get going quickly.

Project details

Download files

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

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

Supported by

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