FixtureForge

The problem with test data today

# ❌ Everyone does this. It's brittle and misses real-world edge cases.
user = User(name="Test User", email="test@test.com", bio="Lorem ipsum...")
# ❌ factory_boy is great — but it's static. No surprises, no edge cases.
UserFactory.create(role="admin")
# ❌ Writing 500 of them by hand? Not happening.

Dev mode → AI generates rich, realistic, edge-case-aware fixtures
CI mode → same fixtures, frozen with seed=42, 100% reproducible

Quickstart

pip install fixtureforge

from fixtureforge import Forge
from pydantic import BaseModel
class User(BaseModel):
 id: int
 name: str
 email: str
 bio: str
forge = Forge() # auto-detects AI provider from env vars
users = forge.create_batch(User, count=50, context="SaaS platform users")

forge = Forge(use_ai=False, seed=42) # deterministic, zero network, CI-safe
users = forge.create_batch(User, count=500)

Intelligent Field Routing

CI/CD — zero config changes between environments

# .github/workflows/test.yml
- name: Run tests
 env:
 FORGE_SEED: 42 # identical output every run
 # No AI key needed — FixtureForge auto-detects and falls back to Faker
 run: pytest

export ANTHROPIC_API_KEY=sk-ant-... # → Claude
export OPENAI_API_KEY=sk-... # → GPT
export GOOGLE_API_KEY=... # → Gemini
export GROQ_API_KEY=... # → Groq (fast + cheap)

Foreign Key Relationships — automatic

# Step 1: generate customers
customers = forge.create_batch(Customer, count=10)
# Step 2: Order.customer_id auto-resolves to a real customer.id
orders = forge.create_batch(Order, count=100)
# → every order.customer_id is valid. No manual wiring.

DataSwarms — bulk generation, shared cache

results = forge.swarm(
 models=[User, Order, Product, Payment],
 counts=[10, 50, 100, 30],
 contexts=["SaaS users", "E-commerce orders", None, None],
)
# {
# "User": [...10 users...],
# "Order": [...50 orders...],
# "Product": [...100 products...],
# "Payment": [...30 payments...],
# }

ForgeMemory — fixtures that remember your domain

forge.memory.add_rule("financial", "Users under 18 get restricted account type")
forge.memory.add_rule("user", "Israeli phone numbers use format 05x-xxx-xxxx")
forge.memory.add_rule("orders", "Max 3 active loans per customer at any time")
# Rules inject into AI prompts automatically on every generation call
users = forge.create_batch(User, count=50, context="Israeli SaaS platform")

pytest plugin — one line per fixture

# conftest.py
from fixtureforge.pytest_plugin import forge_fixture, forge_swarm_fixture
from pydantic import BaseModel
class User(BaseModel):
 id: int; name: str; email: str
forge_fixture(User, count=10, seed=42) # → fixture: "users"
forge_swarm_fixture([User, Order], counts=[5, 20], seed=42) # → "swarm_data"

# test_users.py
def test_signup(users):
 for user in users:
 assert "@" in user.email
def test_full_flow(swarm_data):
 users = swarm_data["User"]
 orders = swarm_data["Order"]

Multi-provider support

# Be explicit
forge = Forge(provider_name="anthropic", model="claude-haiku-4-5-20251001")
forge = Forge(provider_name="openai", model="gpt-4o-mini")
forge = Forge(provider_name="gemini", model="gemini-2.0-flash")
forge = Forge(provider_name="groq", model="llama-3.3-70b-versatile")
forge = Forge(provider_name="ollama", model="llama3.2") # local, zero cost
forge = Forge(use_ai=False) # pure Faker

Large datasets — constant AI cost regardless of count

# Seed + Interpolation: generates ~1 000 unique AI values, tiles to 100 000
dataset = forge.create_large(Order, count=100_000, seed_ratio=0.01)
# Streaming — one record at a time, never loads all into memory
for user in forge.create_stream(User, count=1_000_000, filename="users.json"):
 process(user)

Export

from fixtureforge.core.exporter import DataExporter
users = forge.create_batch(User, count=100)
DataExporter.to_json(users, "users.json")
DataExporter.to_csv(users, "users.csv")
DataExporter.to_sql(users, "users.sql", table_name="users")

FixtureForge vs alternatives

Installation

# Core (deterministic mode, no AI)
pip install fixtureforge
# With your preferred provider
pip install "fixtureforge[anthropic]" # Claude
pip install "fixtureforge[openai]" # GPT
pip install "fixtureforge[gemini]" # Gemini
pip install "fixtureforge[all]" # All providers

Enterprise Edition

from fixtureforge.enterprise import ForgeEnterprise
forge = ForgeEnterprise(use_ai=False)
users = forge.create_batch(User, count=10)
users[0].model_dump()
# { "id": 1, "name": "...", "bio": "...",
# "forge_metadata": {
# "forge_id": "abc-123",
# "provenance_hash": "sha256:029773ed...", ← immutable audit stamp
# "tenant_id": "tenant-acme",
# "source": "faker",
# ...
# }
# }
with forge.isolate_tenant("tenant-acme"):
 acme_users = forge.create_batch(User, count=5)
 # FK references from tenant-acme can NEVER resolve to tenant-xyz records

Project status

Links

Contributing

git clone https://github.com/Yaniv2809/fixtureforge
cd fixtureforge
pip install -e ".[dev]"
PYTHONPATH=src python -m pytest tests/

License