The Auto sentinel

A number of places here we used a default value of Auto, which is a custom object defined as follows:

class _Auto:
    """
    Sentinel value indicating an automatic default will be used.
    """

    def __bool__(self):
        # Allow `Auto` to be used like `None` or `False` in boolean expressions
        return False


Auto: Any = _Auto()

We use Auto instead of None or something else, because:

• Sometimes you need to specify None as an actual value (for nullable DB fields), but not want it as a default.

• Often the correct default needs to be defined dynamically:

  • you need to create another object at runtime, as in the account: BookingAccount = Auto line above

  • a sensible and correct default depends on some other argument, so requires some logic in the body of the function.

We create a singleton value Auto so we can do if foo is Auto checks.

We also give it a type Any so that type checkers don’t complain about using it as a default value. It doesn’t break type checking for the functions calling our factory functions.

Constraints and sequences

Often you have the problem that a unique constraint on a field makes it difficult to provide a static default. As in the example above, I’m using a really simple technique to deal with this – generate a sequence of values that are unlikely to be specified manually in a test. In the above code, you can see BOOKING_ACCOUNT_EMAIL_SEQUENCE which is defined like this at the module level:

BOOKING_ACCOUNT_EMAIL_SEQUENCE = sequence(lambda n: f"booker_{n}@example.com")

Every time we call next() on this object, we get a distinct value, so we avoid issues with constraints.

The sequence utility is actually super simple, but presented here in all it’s type-hinted glory:

import itertools
from typing import Any, Callable, Generator, TypeVar

T = TypeVar("T")


def sequence(func: Callable[[int], T]) -> Generator[T, None, None]:
    """
    Generates a sequence of values from a sequence of integers starting at zero,
    passed through the callable, which must take an integer argument.
    """
    return (func(n) for n in itertools.count())

You could do something even simpler though – just use a generator expression at the top level:

BOOKING_ACCOUNT_EMAIL_SEQUENCE = (f"booker_{n}@example.com" for n in itertools.count())

There can be some cases where you need something more complicated than this (for example to be able to reset sequences) but they are rare in my experience and fairly easy to write [1].

Delegation and sub-objects

Factory functions often delegate to other factory functions, as in the examples above.

It’s also quite common to want to specify something about a sub-object. Rather than build up a tree of objects as the caller, I often add a parameter to the top-level factory itself. This gives you some independence from the actual schema.

Special purpose factories

You aren’t limited to one factory function per model, you can have as many as you like. For example you might have create_staff_user and create_customer which take different parameters, but both happen to return the same User model.

Sensible and minimal defaults

As far as possible, the factory function should pick sensible defaults, based on what parameters were passed in if any. If it can’t because the caller contradicted themselves, it should raise an exception.

I normally take the approach that the defaults should produce minimal and pristine objects, while being complete and usable.

For example, if your model supports soft-delete via deactivation, active=False would be a bad default. On the other hand, creating lots of related objects in order to be “realistic” would not be a good idea.

You should be pragmatic. For example, for a User object, if a brand new, “pristine” user is always forced to go through an on-boarding flow on your website, meaning that every single page but the on-boarding page is blocked until they complete it, then has_onboarded=True is probably a more sensible default – only a few of your tests will want has_onboarded=False.

In many cases, your main business logic may already have functions that initialise database objects into sensible states when creating them, or when changing their states. Test factory functions will often delegate to them, so that things are set up as close as possible to how they would be normally.

Simplified interface

A good factory function will often simplify things for the caller.

For example, in the CCiW project mentioned, the Camp model has a leaders relationship, which is a many-to-many. For several good reasons, the leaders are not User objects, but Person objects, where Person has some metadata and another many-to-many (!) with User objects. However, when I’m writing a test, I might want to be able to say something like:

user = create_user()
camp = create_camp(leader=user)
login(user)

Here, I just care that the user is conceptually the leader of the camp. I don’t care:

• that a camp can have more than one leader

• that the Camp is actually related to the User object via a Person object.

Sometimes I don’t care about specifying who the leader actually is, just that there is one, so I might want to pass leader=True.

My factory function ends up looking like this:

def create_camp(
    *,
    leader: Person | User | bool = Auto,
    leaders: list[Person | User] = Auto,
) -> Camp:
    ...

It’s redundant, but it’s easy to use, and this approach means you isolate many of your tests from needing changing. Sometimes my factory functions end up having a lot of parameters, and they’re unlikely to win any beauty contests — but who really cares? They are easy to understand and modify.

Type hints

Type hints are great for getting good help in your editor when writing tests. Use them!

Don’t depend on defaults

If a test requires a certain value, and it happens to be the default that the factory will use, the test should still specify it. This makes the test more robust, and allows the factory to change the defaults. If a test doesn’t specify it, it means it doesn’t care, and it should work with any value the factory happens to choose.

Enhancements

If you are using pytest (which I recommend, along with pytest-django), Haki Benita has nice post that explains how to use factory functions as pytest fixtures.

JSON/YAML fixtures

Django docs used to encourage you to define models in JSON/YAML fixtures for use in tests. Don’t do that! I’ll let Carl Meyer tell you why.

There are some legitimate cases for using these kinds of fixtures in tests – in particular, where you might use the same/similar fixture files for loading data in a production environment. This is typically when you have essentially static data that is defined by some external reality, which happens to be stored in a database table in your app – such as a list of countries and their ISO codes.

**kwargs

When writing factory functions, rather than adding loads of parameters, it may be tempting to just let them accept **kwargs and pass those on to the underlying model. I usually prefer not to do that, because:

• you get much less help when writing tests

• you tend to end up overly tied to the actual schema

django-dynamic-fixture

I used to use django-dynamic-fixture to avoid the tedium of manual factory functions, but have since moved away from that. You are just introducing a layer between yourself and the code that you actually need to write, and have to stop it from doing things you don’t want etc. It also doesn’t understand the “business logic” needed to come up with sensible defaults.

factory_boy

OK, factory_boy, this is like my comments for django-dynamic-fixture, only more so.

Let me put it this way:

You’ve been tasked with providing a procedure for creating model instances, where that procedure will have sensible defaults, but will allow the caller to override them. You have to decide what are the appropriate language features of Python to use. Do you:

1. Create a function or a method, with parameters for overriding defaults, or,

2. Define a new class that inherits from Factory, and use the body of the class statement to define a procedure?

If you chose A), congratulations, you got the right answer! You will be rewarded for using the language as it was meant to be used, by things like:

• Automatic help inside your editor, both for the parameters and the returned value.

• Static type checking if you want it.

• Everyone being able to modify your code without looking up some documentation.

If you chose B), you get points for novelty. But you will be punished as follows:

• You will have to invent things like:

  • nested class Meta for essential configuration of FactoryOptions

  • nested class Params

  • Trait

  • PostGeneration

  • @post_generation

  • LazyAttribute

  • @lazy_attribute

  • @lazy_attribute_sequence

  • LazyFunction

  • SubFactory

  • RelatedFactory

  • SelfAttribute

  • a debug mode (of course)

  • and much, much more!

• You will have to write thousands of lines of code (1700+), thousands more of tests (5000+), and page after page of documentation (16,000+ words) to support all this.

• You will have to get people to read that documentation. Instead of which, they will spend their evenings writing snarky blog posts complaining about all your hard work!

• You will have an Open Source side project with hundreds of open issues, fun!

• You will get less than zero help from your editor when using these factories – not only will it just display **kwargs for inputs, it will think the output is a Factory instance, which it is not.

• For people to find what parameters they can pass to a Factory, they will have to look up the model, and inspect the Factory definition and decipher its “traits” etc.

I don’t want to add any further to the burden of the authors – they have suffered enough already! But I do want to deal with a few objections:

def test_address_formatted():
    address = Address(line1="123 Main St", line2="London")
    assert address.formatted() == "123 Main St\nLondon\n")

order = OrderFactory(
    amount=200,
    status='PAID',
    customer__is_vip=True,
    address__country='AU',
 )

from faker import Faker

faker = Faker()

def create_user():
    return User.objects.create(
        name=faker.name(),
    )

payments = [create_manual_payment() for i in range(0, 100)]

from typing import Callable, TypeVar

T = TypeVar("T")


def create_batch(factory: Callable[..., T], count, /, **kwargs) -> list[T]:
    """
    Use `factory` callable to create `count` objects, passing along kwargs
    """
    return [factory(**kwargs) for i in range(0, count)]

payment_1, payment_2 = create_batch(create_manual_payment, 2, amount=10)