builders

Test Data Builders Guide

When to Create Builders

Create test data builders when:

• Verbose setup code - Tests have multi-line object construction that obscures intent
• Nested hierarchies - Objects contain other objects several levels deep
• Repeated boilerplate - Same structure appears across many tests with small variations

Don't create builders for simple dataclasses with 2-3 fields.

Spotting Opportunities

Test smell: Deeply nested construction that buries the test's intent:

# Before - 12 lines to set up one task
mm = MindMap(root=Node(
    id="ID_ROOT", title="Project",
    children=[Node(id="ID_TASKS", title="tasks", children=[
        Node(id="ID_LANE", title="Team", children=[
            Node(id="ID_1", title="Task A"),
        ])
    ])]
))

# After - intent is clear
mm = simple_mindmap(task("ID_1", "Task A"))

The Pattern

1. Builder Class with Fluent API

class NodeBuilder:
    """Fluent builder for Node objects."""

    def __init__(self, id: str, title: str):
        self._id = id
        self._title = title
        self._description: str | None = None
        self._children: list[Node] = []

    def with_description(self, description: str) -> "NodeBuilder":
        self._description = description
        return self

    def with_children(self, *children: "NodeBuilder | Node") -> "NodeBuilder":
        for child in children:
            if isinstance(child, NodeBuilder):
                self._children.append(child.build())
            else:
                self._children.append(child)
        return self

    def build(self) -> Node:
        return Node(
            id=self._id,
            title=self._title,
            description=self._description,
            children=self._children,
        )

2. Factory Function (Entry Point)

def task(id: str, title: str) -> NodeBuilder:
    """Factory to start building a task node."""
    return NodeBuilder(id, title)

3. Convenience Function for Common Cases