factory_boy: A Python Test Fixtures Replacement

Introduction

factory_boy is a popular Python library that serves as a robust replacement for traditional test fixtures. Inspired by thoughtbot's factory_bot, it aims to simplify the creation of complex objects for testing purposes. Instead of relying on static, often hard-to-maintain fixtures, factory_boy allows you to define flexible factories that generate customized objects on demand, making your test setups cleaner and more adaptable. It integrates seamlessly with various ORMs like Django, SQLAlchemy, and MongoEngine, and supports features such as declarative syntax, multiple build strategies, and realistic data generation.

Installation

Installing factory_boy is straightforward using pip:

pip install factory_boy

For development or to install from source, you can clone the repository:

git clone git://github.com/FactoryBoy/factory_boy/
python setup.py install

Examples

factory_boy provides a powerful and flexible way to define and use test data.

Defining Factories
Factories declare attributes used to instantiate a Python object. The model class is specified within a Meta class:

import factory
from . import models

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

    first_name = 'John'
    last_name = 'Doe'
    admin = False

# Another factory for the same object
class AdminFactory(factory.Factory):
    class Meta:
        model = models.User

    first_name = 'Admin'
    last_name = 'User'
    admin = True

ORM Integration
factory_boy offers specific factory subclasses for popular ORMs:

• Django: factory.django.DjangoModelFactory
• Mogo: factory.mogo.MogoFactory
• MongoEngine: factory.mongoengine.MongoEngineFactory
• SQLAlchemy: factory.alchemy.SQLAlchemyModelFactory

Using Factories
You can instantiate objects using different strategies:

# Returns a User instance that's not saved
user = UserFactory.build()

# Returns a saved User instance (requires an ORM base class)
user = UserFactory.create()

# Returns a stub object (just attributes)
obj = UserFactory.stub()

# The Factory class acts as a shortcut for the default strategy (create)
user = UserFactory()

# Override attributes by passing keyword arguments
user = UserFactory.build(first_name='Joe')

# Create multiple objects in a single call
users = UserFactory.build_batch(10, first_name="Joe")

Realistic, Random Values with Faker
Integrate with the faker library to generate realistic, random data for your tests:

class RandomUserFactory(factory.Factory):
    class Meta:
        model = models.User

    first_name = factory.Faker('first_name')
    last_name = factory.Faker('last_name')

Lazy Attributes
For attributes whose values depend on other fields or require dynamic computation, use LazyAttribute or LazyFunction:

import factory
from datetime import datetime

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

    first_name = 'Joe'
    last_name = 'Blow'
    email = factory.LazyAttribute(lambda a: '{}.{}@example.com'.format(a.first_name, a.last_name).lower())
    date_joined = factory.LazyFunction(datetime.now)

Sequences
Generate unique, sequential values for fields like email addresses:

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

    email = factory.Sequence(lambda n: 'person{}@example.com'.format(n))

Associations
Define relationships between objects using SubFactory:

class PostFactory(factory.Factory):
    class Meta:
        model = models.Post

    author = factory.SubFactory(UserFactory)

Why Use It

factory_boy significantly enhances test development by:

• Simplifying Test Setup: Reduces the boilerplate code needed to set up complex test data.
• Improving Readability: Factories clearly define how objects are constructed, making tests easier to understand.
• Increasing Maintainability: Centralizes object creation logic, so changes to models only require updates in one place.
• Flexibility: Supports various ORMs and allows for dynamic attribute generation, including realistic data.
• Reproducibility: Offers tools to reseed random values, ensuring tests remain consistent.

Links

• Documentation: https://factoryboy.readthedocs.io/
• Repository: https://github.com/FactoryBoy/factory_boy
• Package (PyPI): https://pypi.org/project/factory-boy/
• Mailing List: factoryboy@googlegroups.com | https://groups.google.com/forum/#!forum/factoryboy