How To Use Python factory-boy for Test Fixture Creation

Using factory_boy with Django ORM

When your project uses Django models, swap factory.Factory for factory.django.DjangoModelFactory. This subclass knows how to call Model.objects.create() instead of Model(), so objects are persisted to the test database automatically when you call the factory.

# factories.py  (in your Django app's test directory)
import factory
from factory.django import DjangoModelFactory
from myapp.models import User, Profile

class UserFactory(DjangoModelFactory):
    class Meta:
        model = User

    username = factory.Sequence(lambda n: f"testuser_{n}")
    email = factory.LazyAttribute(lambda obj: f"{obj.username}@example.com")
    first_name = factory.Faker("first_name")
    last_name = factory.Faker("last_name")
    is_active = True

class ProfileFactory(DjangoModelFactory):
    class Meta:
        model = Profile

    user = factory.SubFactory(UserFactory)
    bio = factory.Faker("paragraph", nb_sentences=2)
    location = factory.Faker("city")

# tests.py  -- using the factories in a Django test case
from django.test import TestCase
from .factories import UserFactory, ProfileFactory

class ProfileViewTests(TestCase):

    def test_profile_page_shows_bio(self):
        # One line creates the user AND the profile
        profile = ProfileFactory(bio="Expert Python programmer.")

        response = self.client.get(f"/profile/{profile.user.username}/")
        self.assertEqual(response.status_code, 200)
        self.assertContains(response, "Expert Python programmer.")

    def test_user_listing_shows_all_active_users(self):
        # Create 5 active users and 2 inactive users
        UserFactory.create_batch(5, is_active=True)
        UserFactory.create_batch(2, is_active=False)

        response = self.client.get("/users/")
        self.assertEqual(len(response.context["users"]), 5)

Output (pytest or Django test runner):

..
----------------------------------------------------------------------
Ran 2 tests in 0.342s

OK

The test for the profile page only cares about one thing: whether the bio shows up on the page. With factory_boy, that is the only field we specify. The username, email, and user account are created automatically and the test is completely self-documenting: "create a profile with this bio, then check the page shows it." Without factory_boy, this test would start with 10 lines of User.objects.create(username=..., email=..., password=..., ...) before you even get to the assertion.

Using factory_boy with SQLAlchemy

For SQLAlchemy projects, factory_boy provides factory.alchemy.SQLAlchemyModelFactory. The key difference is that you must supply the SQLAlchemy session so factory_boy knows where to add the created objects.

# sqlalchemy_factories.py
import factory
from factory.alchemy import SQLAlchemyModelFactory
from sqlalchemy import Column, Integer, String, Boolean, ForeignKey, create_engine
from sqlalchemy.orm import relationship, sessionmaker, declarative_base

Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    username = Column(String, unique=True)
    email = Column(String, unique=True)
    is_active = Column(Boolean, default=True)

# Create an in-memory SQLite database for testing
engine = create_engine("sqlite:///:memory:")
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()

class UserFactory(SQLAlchemyModelFactory):
    class Meta:
        model = User
        sqlalchemy_session = session          # the session to use
        sqlalchemy_session_persistence = "commit"   # auto-commit after create

    id = factory.Sequence(lambda n: n + 1)
    username = factory.Sequence(lambda n: f"user_{n}")
    email = factory.LazyAttribute(lambda obj: f"{obj.username}@test.com")
    is_active = True

# Create objects -- they are persisted to the in-memory DB
u1 = UserFactory()
u2 = UserFactory(is_active=False)

# Query them back from the DB to confirm persistence
all_users = session.query(User).all()
active_users = session.query(User).filter_by(is_active=True).all()

print(f"Total users: {len(all_users)}")
print(f"Active users: {len(active_users)}")
for u in all_users:
    print(f"  {u.username}  active={u.is_active}")

Output:

Total users: 2
Active users: 1
  user_1  active=True
  user_2  active=False

The SQLAlchemy integration is straightforward once the session is wired up. A common pattern in real test suites is to configure sqlalchemy_session at the base factory level so all child factories share the same session, and then use a pytest fixture to create a fresh session per test and update the factory's session reference at the start of each test. This ensures clean isolation between tests.

Real-Life Example: E-Commerce Order Test Suite

Let us put everything together with a realistic scenario: an e-commerce application where tests need to verify order total calculations, product inventory checks, and customer history. Without factory_boy, every test would require 30-50 lines of setup. With it, each test is three to five lines.

# ecommerce_factories.py
import factory
from dataclasses import dataclass, field
from typing import List

@dataclass
class Customer:
    id: int
    name: str
    email: str
    is_premium: bool = False

@dataclass
class Product:
    id: int
    name: str
    sku: str
    price: float
    stock: int = 100

@dataclass
class OrderLine:
    product: Product
    quantity: int

    @property
    def subtotal(self):
        return self.product.price * self.quantity

@dataclass
class Order:
    id: int
    customer: Customer
    lines: List[OrderLine] = field(default_factory=list)

    @property
    def total(self):
        return sum(line.subtotal for line in self.lines)

    def add_line(self, product, quantity):
        self.lines.append(OrderLine(product=product, quantity=quantity))

class CustomerFactory(factory.Factory):
    class Meta:
        model = Customer

    id = factory.Sequence(lambda n: n + 1)
    name = factory.Faker("name")
    email = factory.LazyAttribute(lambda obj: f"{obj.name.lower().replace(' ', '.')}@shop.com")
    is_premium = False

class ProductFactory(factory.Factory):
    class Meta:
        model = Product

    id = factory.Sequence(lambda n: n + 1)
    name = factory.Sequence(lambda n: f"Widget Model {n}")
    sku = factory.Sequence(lambda n: f"WGT-{n:04d}")
    price = factory.Faker("pyfloat", min_value=1.0, max_value=500.0, right_digits=2)
    stock = 100

class OrderFactory(factory.Factory):
    class Meta:
        model = Order

    id = factory.Sequence(lambda n: n + 1)
    customer = factory.SubFactory(CustomerFactory)

# --- Tests using the factories ---
import unittest

class TestOrderTotals(unittest.TestCase):

    def test_single_line_order_total(self):
        product = ProductFactory(price=25.00)
        order = OrderFactory()
        order.add_line(product, quantity=3)
        self.assertAlmostEqual(order.total, 75.00)

    def test_multi_line_order_total(self):
        p1 = ProductFactory(price=10.00)
        p2 = ProductFactory(price=5.50)
        order = OrderFactory()
        order.add_line(p1, quantity=2)
        order.add_line(p2, quantity=4)
        # 20.00 + 22.00 = 42.00
        self.assertAlmostEqual(order.total, 42.00)

    def test_premium_customer_flag(self):
        premium_customer = CustomerFactory(is_premium=True)
        order = OrderFactory(customer=premium_customer)
        self.assertTrue(order.customer.is_premium)

    def test_out_of_stock_product(self):
        out_of_stock = ProductFactory(stock=0)
        self.assertEqual(out_of_stock.stock, 0)

if __name__ == "__main__":
    unittest.main(verbosity=2)

Output:

test_multi_line_order_total (__main__.TestOrderTotals) ... ok
test_out_of_stock_product (__main__.TestOrderTotals) ... ok
test_premium_customer_flag (__main__.TestOrderTotals) ... ok
test_single_line_order_total (__main__.TestOrderTotals) ... ok

----------------------------------------------------------------------
Ran 4 tests in 0.012s

OK

Each test is a focused, self-documenting statement. test_single_line_order_total tells you exactly what it cares about -- a product at $25.00 multiplied by 3 -- and nothing else. The customer, SKU, product name, and every other field that does not matter to this specific calculation are handled automatically. To extend this example in your own projects, try adding a DiscountFactory with a SubFactory(CustomerFactory) to test premium discount logic, or a factory.Trait to define a "digital_product" variant with stock=-1 meaning unlimited.

Frequently Asked Questions

What is the difference between build() and create()?

build() instantiates the Python object in memory without touching any database. create() also persists the object -- by calling Model.objects.create() in Django or adding to the SQLAlchemy session and committing. For unit tests that do not need database access, use build() -- it is faster, requires no database setup, and avoids transaction overhead. Use create() only when a test genuinely needs to query the database or test ORM behavior.

How do I reset the sequence counter between tests?

factory_boy's Sequence counter is global per factory class, so it keeps incrementing across tests in the same run. If you need reproducible IDs, call UserFactory.reset_sequence(0) at the start of a test or in a setUp method. In Django test cases, you can also override _meta.reset_sequence = True at the factory level. For most tests this is unnecessary since you are testing behavior, not specific ID values -- but it matters if you are testing URL routing based on IDs or comparing fixtures against expected output.

Can I use custom Faker providers for domain-specific data?

Yes. Faker has over 100 built-in providers (factory.Faker("ipv4_private"), factory.Faker("isbn13"), factory.Faker("credit_card_number"), etc.) and you can register your own. For domain-specific data like product categories or country codes, factory.Iterator(["Electronics", "Clothing", "Books"]) is often simpler than a custom provider. If a field needs logic that neither Sequence nor LazyAttribute can express cleanly, use factory.LazyFunction(my_custom_function) to call an arbitrary callable with no arguments.

What are Traits and when should I use them?

A Trait is a named bundle of field overrides that you can apply to a factory call with a keyword argument. They are ideal when you find yourself passing the same group of overrides repeatedly. For example, instead of writing UserFactory(is_active=False, verified=False, login_count=0) in every test that needs an inactive user, define a @factory.Trait called inactive that sets all three fields, then call UserFactory(inactive=True). Traits make intent clear and keep override logic in one place.

How do I avoid hitting the database in unit tests when using DjangoModelFactory?

Use UserFactory.build() instead of UserFactory() (which calls create() by default for DjangoModelFactory). build() constructs the object in memory without calling .save(). If your test calls view code or serializers that reference the object but does not query the database, build() gives you a valid Python object at no database cost. For tests that mock the ORM layer entirely (with unittest.mock.patch), build() is always the right choice.

Conclusion

factory_boy eliminates the single most tedious part of writing Python tests: setting up valid, realistic test data. You have seen how factory.Sequence ensures unique field values across every object ever built, how factory.LazyAttribute lets fields depend on each other so overrides cascade correctly, how factory.SubFactory builds related objects automatically, and how build_batch creates lists of objects in one call. The Django and SQLAlchemy integrations wire the same patterns directly to your ORM so created objects land in the test database with no extra code.

The real-life example showed the payoff: four tests, each between three and five lines, each perfectly self-documenting. Every field that a test explicitly sets is a field that matters to that test's assertion. Everything else is handled by the factory. Try taking one of your existing test files, identifying the tests with the most setup code, and replacing that setup with a factory. The reduction in noise is immediate.

For advanced features like post-generation hooks (@factory.post_generation), exclusions, and custom factory inheritance, see the official factory_boy documentation.

Related Articles

• How To Use Python pytest for Unit Testing
• How To Use Python Faker to Generate Realistic Test Data
• How To Use Python unittest.mock for Mocking in Tests