factory-boy

Warnings

• breaking Major breaking changes occurred in the transition from factory-boy 2.x to 3.x, including dropping support for Python 2, Python 3.4, Django 2.0, and Django 2.1.
  Fix: Upgrade to Python 3.8+ and supported Django versions. Review the official changelog for specific removals and re-implementations.
• breaking For plain `factory.Factory` subclasses, `create()` no longer calls `objects.create()` for ORM models. For Django or SQLAlchemy models, you must now use `DjangoModelFactory` or `SQLAlchemyModelFactory` respectively to ensure persistence to the database when calling `create()`.
  Fix: Migrate your ORM-backed factories to inherit from `factory.django.DjangoModelFactory` or `factory.alchemy.SQLAlchemyModelFactory`.
• deprecated Old class-level attributes like `FACTORY_FOR`, `ABSTRACT_FACTORY`, `FACTORY_STRATEGY` are deprecated. They should now be defined within a nested `Meta` class using `model`, `abstract`, and `strategy` respectively.
  Fix: Refactor factory definitions to use the `Meta` class pattern (e.g., `class Meta: model = MyModel`).
• deprecated The default behavior of `_after_postgeneration` for `DjangoModelFactory` changed. It will no longer automatically save the instance after post-generation hooks in future releases. This often results in `DeprecationWarning` if not handled.
  Fix: If your `post_generation` hooks modify the instance, set `skip_postgeneration_save = True` in `Meta` and explicitly call `instance.save()` within your post-generation hook, typically guarding it with `if create:`.
• gotcha Defining mutable fields (e.g., lists, dictionaries) directly at the factory class level can lead to all generated instances sharing the same mutable object. Changes in one instance will propagate to others.
  Fix: Use `factory.List()`, `factory.Dict()`, or `factory.LazyAttribute` to ensure each instance receives a unique mutable object. Example: `my_list = factory.List([1, 2, 3])` or `my_dict = factory.LazyAttribute(lambda o: {})`.
• gotcha Overriding attributes directly at the class level (e.g., `MyFactory.name = 'Fixed'`) is an anti-pattern and can lead to unpredictable behavior, especially in parallel test runs, as it modifies the default for all future objects.
  Fix: Always specify attribute overrides using keyword arguments in your factory call (e.g., `MyFactory(name='Custom Name')`).

Install

• pip install factory-boy Install stable version

Imports

• Factory

  import factory
  
  class MyFactory(factory.Factory): ...

  The primary `Factory` class is typically imported from the `factory` namespace.
• Faker

  import factory
  
  class MyFactory(factory.Factory):
      name = factory.Faker('name')

  Used for generating realistic, randomized data.
• Sequence

  import factory
  
  class MyFactory(factory.Factory):
      id = factory.Sequence(lambda n: n)

  Generates sequential values, often used for unique IDs.
• LazyAttribute

  import factory
  
  class MyFactory(factory.Factory):
      full_name = factory.LazyAttribute(lambda o: f'{o.first_name} {o.last_name}')

  Evaluates its argument when the object is built, often dependent on other attributes of the generated object.
• SubFactory

  import factory
  
  class UserFactory(factory.Factory): ...
  class ProfileFactory(factory.Factory):
      user = factory.SubFactory(UserFactory)

  Used to create and link related objects, calling another factory.
• DjangoModelFactory

  from factory.django import DjangoModelFactory
  
  class UserFactory(DjangoModelFactory):
      class Meta:
          model = User

  Specific factory for Django ORM models, automatically handling `save()` behavior during `create()`.
• SQLAlchemyModelFactory

  from factory.alchemy import SQLAlchemyModelFactory
  
  class UserFactory(SQLAlchemyModelFactory):
      class Meta:
          model = User
          sqlalchemy_session = db_session

  Specific factory for SQLAlchemy models, requiring a session object in `Meta.sqlalchemy_session`.

Quickstart

Define a simple Python class and then create a `factory.Factory` subclass for it. Use `factory.Faker` for realistic data and `factory.LazyAttribute` for interdependent fields. Instances can be created by calling the factory, with keyword arguments overriding default attributes.

import factory

class User:
    def __init__(self, first_name, last_name, email, is_admin=False):
        self.first_name = first_name
        self.last_name = last_name
        self.email = email
        self.is_admin = is_admin

    def __str__(self):
        return f'{self.first_name} {self.last_name} ({self.email})'

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

    first_name = factory.Faker('first_name')
    last_name = factory.Faker('last_name')
    email = factory.LazyAttribute(lambda o: f'{o.first_name}.{o.last_name}@example.com'.lower())
    is_admin = False

# Create a basic user
user = UserFactory()
print(f"Created user: {user}")

# Create an admin user
admin_user = UserFactory(is_admin=True)
print(f"Created admin user: {admin_user}")

# Create a user with specific name
specific_user = UserFactory(first_name='John', last_name='Doe')
print(f"Created specific user: {specific_user}")