Pytest Test Data Factories
Purpose
Test data factories eliminate duplication and make tests more maintainable. Instead of recreating Order objects with the same fields in every test, factories provide sensible defaults and allow customization only where needed.
Quick Start
Create simple factory functions in conftest.py:
# tests/unit/conftest.py
import pytest
from datetime import datetime
from app.extraction.domain.entities import Order
from app.extraction.domain.value_objects import OrderId, Money, ProductTitle
@pytest.fixture
def create_test_order():
"""Factory fixture for creating test orders with defaults."""
def _create(
order_id: str = "order_123",
customer_name: str = "Test User",
total: float = 99.99,
) -> Order:
return Order(
order_id=OrderId(order_id),
created_at=datetime.now(),
customer_name=customer_name,
line_items=[create_test_line_item()],
total_price=Money.from_float(total),
)
return _create
# Usage in tests
def test_order_validation(create_test_order):
"""Use factory with defaults."""
order = create_test_order()
assert order.customer_name == "Test User"
def test_order_custom_name(create_test_order):
"""Override specific fields."""
order = create_test_order(customer_name="Jane Doe")
assert order.customer_name == "Jane Doe"Instructions
Step 1: Create Basic Factory Fixtures
# tests/unit/conftest.py
from __future__ import annotations
from datetime import datetime
from decimal import Decimal
from typing import Optional
import pytest
from app.extraction.domain.entities import Order, LineItem
from app.extraction.domain.value_objects import OrderId, ProductId, ProductTitle, Money
@pytest.fixture
def create_test_order():
"""Factory for Order aggregate with sensible defaults."""
def _create(
order_id: str = "order_123",
customer_name: str = "Test User",
line_items: Optional[list[LineItem]] = None,
total: Optional[float] = None,
) -> Order:
if line_items is None:
line_items = [create_test_line_item()]
# Calculate total from line items if not provided
if total is None:
total = sum(
float(item.price.amount) * item.quantity
for item in line_items
)
return Order(
order_id=OrderId(order_id),
created_at=datetime.now(),
customer_name=customer_name,
line_items=line_items,
total_price=Money.from_float(total),
)
return _create
@pytest.fixture
def create_test_line_item():
"""Factory for LineItem entity with defaults."""
def _create(
product_id: str = "prod_1",
product_title: str = "Test Product",
quantity: int = 1,
price: float = 99.99,
) -> LineItem:
return LineItem(
product_id=ProductId(product_id),
product_title=ProductTitle(product_title),
quantity=quantity,
price=Money.from_float(price),
)
return _createStep 2: Use Builder Pattern for Complex Objects
class OrderBuilder:
"""Builder for creating complex Order objects."""
def __init__(self):
self.order_id = "order_123"
self.customer_name = "Test User"
self.line_items: list[LineItem] = []
self.total: Optional[float] = None
def with_order_id(self, order_id: str) -> OrderBuilder:
"""Set order ID."""
self.order_id = order_id
return self
def with_customer_name(self, name: str) -> OrderBuilder:
"""Set customer name."""
self.customer_name = name
return self
def with_line_items(self, items: list[LineItem]) -> OrderBuilder:
"""Set line items."""
self.line_items = items
return self
def add_line_item(self, item: LineItem) -> OrderBuilder:
"""Add a single line item."""
self.line_items.append(item)
return self
def with_total(self, total: float) -> OrderBuilder:
"""Set total price."""
self.total = total
return self
def build(self) -> Order:
"""Build the Order object."""
if not self.line_items:
self.line_items = [
LineItem(
product_id=ProductId("prod_1"),
product_title=ProductTitle("Default Product"),
quantity=1,
price=Money.from_float(99.99),
)
]
# Auto-calculate total if not provided
if self.total is None:
self.total = sum(
float(item.price.amount) * item.quantity
for item in self.line_items
)
return Order(
order_id=OrderId(self.order_id),
created_at=datetime.now(),
customer_name=self.customer_name,
line_items=self.line_items,
total_price=Money.from_float(self.total),
)
# Usage
def test_with_builder():
"""Build complex order with fluent API."""
order = (OrderBuilder()
.with_customer_name("Jane Doe")
.add_line_item(LineItem(...))
.add_line_item(LineItem(...))
.build())
assert order.customer_name == "Jane Doe"
assert len(order.line_items) == 2Step 3: Create Fixture Factories (Fixture Factories)
@pytest.fixture
def order_factory(create_test_order):
"""Fixture factory that returns the create_test_order factory."""
return create_test_order
def test_multiple_orders(order_factory):
"""Create multiple different orders easily."""
order1 = order_factory(order_id="order_1", customer_name="Alice")
order2 = order_factory(order_id="order_2", customer_name="Bob")
order3 = order_factory(order_id="order_3", customer_name="Charlie")
assert order1.order_id.value == "order_1"
assert order2.order_id.value == "order_2"
assert order3.order_id.value == "order_3"Step 4: Parametrize Tests with Factory-Generated Data
import pytest
from decimal import Decimal
# Factory-generated test data
ORDER_TEST_CASES = [
("order_1", "Alice", 100.00, 1),
("order_2", "Bob", 250.50, 2),
("order_3", "Charlie", 999.99, 3),
]
@pytest.mark.parametrize(
"order_id,customer_name,total,item_count",
ORDER_TEST_CASES,
ids=["alice_order", "bob_order", "charlie_order"]
)
def test_order_creation_parametrized(
create_test_order,
order_id: str,
customer_name: str,
total: float,
item_count: int,
) -> None:
"""Test multiple orders with different data."""
order = create_test_order(
order_id=order_id,
customer_name=customer_name,
total=total,
)
assert order.order_id.value == order_id
assert order.customer_name == customer_name
assert float(order.total_price.amount) == totalStep 5: Create Mock Response Templates
# tests/unit/conftest.py or tests/unit/fixtures/responses.py
@pytest.fixture
def shopify_order_response() -> dict:
"""Mock Shopify API order response."""
return {
"id": "12345",
"created_at": "2024-01-01T10:00:00Z",
"customer": {"name": "John Doe"},
"line_items": [
{
"product_id": "prod_1",
"title": "Laptop",
"quantity": 2,
"price": "999.99",
}
],
"total_price": "1999.98",
}
@pytest.fixture
def kafka_message_template() -> dict:
"""Mock Kafka message format."""
return {
"order_id": "12345",
"created_at": "2024-01-01T10:00:00Z",
"customer_name": "John Doe",
"line_items": [
{
"product_id": "prod_1",
"product_title": "Laptop",
"quantity": 2,
"price": 999.99,
}
],
"total_price": 1999.98,
}
@pytest.fixture
def clickhouse_query_result() -> list[tuple]:
"""Mock ClickHouse query result."""
return [
("Laptop", 100),
("Mouse", 50),
("Keyboard", 30),
]
# Usage in tests
async def test_shopify_gateway(shopify_order_response):
"""Use mock response template."""
with aioresponses() as mock_http:
mock_http.get(
"https://test.myshopify.com/admin/api/2024-01/orders.json",
payload=shopify_order_response,
)
# Test code...Step 6: Create Realistic Data with Faker
from faker import Faker
import pytest
@pytest.fixture
def faker_instance():
"""Provide faker instance for generating realistic data."""
return Faker()
@pytest.fixture
def create_realistic_order(faker_instance):
"""Factory creating realistic test orders."""
def _create(count: int = 1) -> list[Order]:
orders = []
for _ in range(count):
orders.append(Order(
order_id=OrderId(faker_instance.uuid4()),
created_at=faker_instance.date_time(),
customer_name=faker_instance.name(),
line_items=[
LineItem(
product_id=ProductId(faker_instance.uuid4()),
product_title=ProductTitle(faker_instance.word()),
quantity=faker_instance.random_int(1, 10),
price=Money.from_float(
float(faker_instance.pricetag())
),
)
],
total_price=Money.from_float(
float(faker_instance.pricetag())
),
))
return orders
return _create
def test_with_realistic_data(create_realistic_order):
"""Create realistic test data."""
orders = create_realistic_order(count=5)
assert len(orders) == 5
assert all(isinstance(order, Order) for order in orders)Step 7: Create Test Data Inheritance
class BaseOrderFactory:
"""Base factory with common defaults."""
def __init__(self):
self.order_id = "order_123"
self.customer_name = "Test User"
class VIPOrderFactory(BaseOrderFactory):
"""Factory for high-value VIP orders."""
def __init__(self):
super().__init__()
self.customer_name = "VIP Customer"
self.total = 50000.00
class DiscountedOrderFactory(BaseOrderFactory):
"""Factory for discounted orders."""
def __init__(self):
super().__init__()
self.customer_name = "Discount Customer"
self.total = 10.00
# Usage
def test_vip_order():
"""Test VIP order type."""
factory = VIPOrderFactory()
assert factory.total == 50000.00
def test_discounted_order():
"""Test discounted order type."""
factory = DiscountedOrderFactory()
assert factory.total == 10.00Step 8: Create Domain-Specific Test Data Builders
class ProductRankingFactory:
"""Factory for creating ProductRanking test data."""
@staticmethod
def create_default() -> ProductRanking:
"""Create with default values."""
return ProductRanking(
title="Test Product",
rank=Rank(1),
cnt_bought=100,
)
@staticmethod
def create_list(count: int, start_rank: int = 1) -> list[ProductRanking]:
"""Create multiple rankings."""
return [
ProductRanking(
title=f"Product {i}",
rank=Rank(i + start_rank),
cnt_bought=100 - (i * 10),
)
for i in range(count)
]
# Usage
def test_product_rankings(mock_query_gateway):
"""Use factory to create multiple rankings."""
rankings = ProductRankingFactory.create_list(count=5)
mock_query_gateway.query_top_products.return_value = rankings
assert len(rankings) == 5
assert rankings[0].rank.value == 1Examples
Example 1: Complete Factory Setup
# tests/unit/conftest.py
from __future__ import annotations
from datetime import datetime
from typing import Optional
import pytest
from app.extraction.domain.entities import Order, LineItem
from app.extraction.domain.value_objects import OrderId, ProductId, ProductTitle, Money
@pytest.fixture
def create_test_line_item():
"""Factory for test line items."""
def _create(
product_id: str = "prod_1",
title: str = "Test Product",
quantity: int = 1,
price: float = 99.99,
) -> LineItem:
return LineItem(
product_id=ProductId(product_id),
product_title=ProductTitle(title),
quantity=quantity,
price=Money.from_float(price),
)
return _create
@pytest.fixture
def create_test_order(create_test_line_item):
"""Factory for test orders."""
def _create(
order_id: str = "order_123",
customer_name: str = "Test User",
items: Optional[list[LineItem]] = None,
) -> Order:
if items is None:
items = [create_test_line_item()]
total = sum(
float(item.price.amount) * item.quantity for item in items
)
return Order(
order_id=OrderId(order_id),
created_at=datetime.now(),
customer_name=customer_name,
line_items=items,
total_price=Money.from_float(total),
)
return _create
# Usage
def test_order_with_defaults(create_test_order):
"""Create order with all defaults."""
order = create_test_order()
assert order.customer_name == "Test User"
assert len(order.line_items) == 1
def test_order_with_multiple_items(create_test_order, create_test_line_item):
"""Create order with custom line items."""
items = [
create_test_line_item(title="Laptop"),
create_test_line_item(title="Mouse"),
create_test_line_item(title="Keyboard"),
]
order = create_test_order(items=items)
assert len(order.line_items) == 3Example 2: Builder Pattern for Complex DTOs
class CreateOrderRequestBuilder:
"""Builder for CreateOrderRequest DTO."""
def __init__(self):
self.data = {
"customer_name": "Test User",
"items": [],
"total": 0.0,
}
def with_customer(self, name: str) -> CreateOrderRequestBuilder:
self.data["customer_name"] = name
return self
def with_item(self, title: str, price: float, qty: int = 1) -> CreateOrderRequestBuilder:
self.data["items"].append({"title": title, "price": price, "qty": qty})
self.data["total"] += price * qty
return self
def build(self) -> dict:
return self.data
# Usage
def test_create_order_request():
request = (CreateOrderRequestBuilder()
.with_customer("Alice")
.with_item("Laptop", 999.99)
.with_item("Mouse", 29.99, qty=2)
.build())
assert request["customer_name"] == "Alice"
assert len(request["items"]) == 2
assert request["total"] == 1059.97Requirements
- Python 3.11+
- pytest >= 7.0
- Optional: faker >= 15.0 (for realistic data)
- Domain models in your application
See Also
- pytest-configuration - Pytest setup and conftest organization
- pytest-domain-model-testing - Testing with these factories
- PROJECT_UNIT_TESTING_STRATEGY.md - Section: "Required Test Infrastructure"