Skip to main content

Factory Boy support for pytest.

Project description

factory_boy integration with the pytest runner Documentation Status

pytest-factoryboy makes it easy to combine factory approach to the test setup with the dependency injection, heart of the pytest fixtures.

Install pytest-factoryboy

pip install pytest-factoryboy


Library exports a function to register factories as fixtures. Fixtures are contributed to the same module where register function is called.

Factory Fixture

Factory fixtures allow using factories without importing them. The fixture name convention is to use the lowercase-underscore form of the class name.

import factory
from pytest_factoryboy import register

class AuthorFactory(factory.Factory):
    class Meta:
        model = Author

register(AuthorFactory)  # => author_factory

def test_factory_fixture(author_factory):
    author = author_factory(name="Charles Dickens")
    assert == "Charles Dickens"

Model Fixture

Model fixture implements an instance of a model created by the factory. Name convention is model’s lowercase-underscore class name.

import factory
from pytest_factoryboy import register

class AuthorFactory(factory.Factory):
    class Meta:
        model = Author

    name = "Charles Dickens"

def test_model_fixture(author):
    assert == "Charles Dickens"

Model fixtures can be registered with specific names. For example, if you address instances of some collection by the name like “first”, “second” or of another parent as “other”:

register(AuthorFactory)  # author
register(AuthorFactory, "second_author")  # second_author

# `register(...)` can be used as a decorator too
@register  # book
@register(_name="second_book")  # second_book
@register(_name="other_book")  # other_book, book of another author
class BookFactory(factory.Factory):
    class Meta:
        model = Book

def other_book__author(second_author):
    """Make the relation of the second_book to another (second) author."""
    return second_author

Attributes are Fixtures

There are fixtures created for factory attributes. Attribute names are prefixed with the model fixture name and double underscore (similar to the convention used by factory_boy).

@pytest.mark.parametrize("author__name", ["Bill Gates"])
def test_model_fixture(author):
    assert == "Bill Gates"


Sub-factory attribute points to the model fixture of the sub-factory. Attributes of sub-factories are injected as dependencies to the model fixture and can be overridden via the parametrization.


Post-generation attribute fixture implements only the extracted value for the post generation function.


An example of factory_boy and pytest integration.

# factories/

import factory
from faker import Factory as FakerFactory

faker = FakerFactory.create()

class AuthorFactory(factory.django.DjangoModelFactory):
    """Author factory."""

    name = factory.LazyAttribute(lambda x:

    class Meta:
        model = 'app.Author'

class BookFactory(factory.django.DjangoModelFactory):
    """Book factory."""

    title = factory.LazyAttribute(lambda x: faker.sentence(nb_words=4))

    class Meta:
        model = 'app.Book'

    author = factory.SubFactory(AuthorFactory)
# tests/

from pytest_factoryboy import register

from factories import AuthorFactory, BookFactory

# tests/

from app.models import Book
from factories import BookFactory

def test_book_factory(book_factory):
    """Factories become fixtures automatically."""
    assert book_factory is BookFactory

def test_book(book):
    """Instances become fixtures automatically."""
    assert isinstance(book, Book)

@pytest.mark.parametrize("book__title", ["PyTest for Dummies"])
@pytest.mark.parametrize("author__name", ["Bill Gates"])
def test_parametrized(book):
    """You can set any factory attribute as a fixture using naming convention."""
    assert == "PyTest for Dummies"
    assert == "Bill Gates"

Fixture partial specialization

There is a possibility to pass keyword parameters in order to override factory attribute values during fixture registration. This comes in handy when your test case is requesting a lot of fixture flavors. Too much for the regular pytest parametrization. In this case, you can register fixture flavors in the local test module and specify value deviations inside register function calls.

register(AuthorFactory, "male_author", gender="M", name="John Doe")
register(AuthorFactory, "female_author", gender="F")

def female_author__name():
    """Override female author name as a separate fixture."""
    return "Jane Doe"

@pytest.mark.parametrize("male_author__age", [42])  # Override even more
def test_partial(male_author, female_author):
    """Test fixture partial specialization."""
    assert male_author.gender == "M"
    assert == "John Doe"
    assert male_author.age == 42

    assert female_author.gender == "F"
    assert == "Jane Doe"

Fixture attributes

Sometimes it is necessary to pass an instance of another fixture as an attribute value to the factory. It is possible to override the generated attribute fixture where desired values can be requested as fixture dependencies. There is also a lazy wrapper for the fixture that can be used in the parametrization without defining fixtures in a module.

LazyFixture constructor accepts either existing fixture name or callable with dependencies:

import pytest
from pytest_factoryboy import register, LazyFixture

@pytest.mark.parametrize("book__author", [LazyFixture("another_author")])
def test_lazy_fixture_name(book, another_author):
    """Test that book author is replaced with another author by fixture name."""
    assert == another_author

@pytest.mark.parametrize("book__author", [LazyFixture(lambda another_author: another_author)])
def test_lazy_fixture_callable(book, another_author):
    """Test that book author is replaced with another author by callable."""
    assert == another_author

# Can also be used in the partial specialization during the registration.
register(BookFactory, "another_book", author=LazyFixture("another_author"))

Generic container classes as models

It’s often useful to create factories for dict or other common generic container classes. In that case, you should wrap the container class around named_model(...), so that pytest-factoryboy can correctly determine the model name when using it in a SubFactory or RelatedFactory.

Pytest-factoryboy will otherwise raise a warning.

For example:

import factory
from pytest_factoryboy import named_model, register

class JSONPayload(factory.Factory):
    class Meta:
        model = named_model("JSONPayload", dict)

    name = "foo"

def test_foo(json_payload):
    assert == "foo"

As a bonus, factory is automatically registering the json_payload fixture (rather than dict), so there is no need to override @register(_name="json_payload")).

Post-generation dependencies

Unlike factory_boy which binds related objects using an internal container to store results of lazy evaluations, pytest-factoryboy relies on the PyTest request.

Circular dependencies between objects can be resolved using post-generation hooks/related factories in combination with passing the SelfAttribute, but in the case of PyTest request fixture functions have to return values in order to be cached in the request and to become available to other fixtures.

That’s why evaluation of the post-generation declaration in pytest-factoryboy is deferred until calling the test function. This solves circular dependency resolution for situations like:

o->[ A ]-->[ B ]<--[ C ]-o
|                        |
o----(C depends on A)----o

On the other hand, deferring the evaluation of post-generation declarations evaluation makes their result unavailable during the generation of objects that are not in the circular dependency, but they rely on the post-generation action.

pytest-factoryboy is trying to detect cycles and resolve post-generation dependencies automatically.

from pytest_factoryboy import register

class Foo(object):
    def __init__(self, value):
        self.value = value

class Bar(object):
    def __init__(self, foo): = foo

class FooFactory(factory.Factory):
    """Foo factory."""

    class Meta:
        model = Foo

    value = 0

    def set1(foo, create, value, **kwargs):
        foo.value = 1

class BarFactory(factory.Factory):
    """Bar factory."""

    foo = factory.SubFactory(FooFactory)

    def _create(cls, model_class, foo):
        assert foo.value == 1  # Assert that set1 is evaluated before object generation
        return super(BarFactory, cls)._create(model_class, foo=foo)

    class Meta:
        model = Bar

register(BarFactory, "bar")
"""Forces 'set1' to be evaluated first."""

def test_depends_on_set1(bar):
    """Test that post-generation hooks are done and the value is 2."""
    assert == 1


pytest-factoryboy exposes several pytest hooks which might be helpful for e.g. controlling database transaction, for reporting etc:

  • pytest_factoryboy_done(request) - Called after all factory-based fixtures and their post-generation actions have been evaluated.


This software is licensed under the MIT license.

© 2015 Oleg Pidsadnyi, Anatoly Bubenkov and others

Download files

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

Source Distribution

pytest_factoryboy-2.5.1.tar.gz (18.3 kB view hashes)

Uploaded source

Built Distribution

pytest_factoryboy-2.5.1-py3-none-any.whl (15.5 kB view hashes)

Uploaded py3

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