Seed Data And Fixtures

Seed Data and Fixtures

Overview

Produce realistic data for demos, dev environments, and tests — before lorem ipsum makes it to a screenshot. Output is .forge/seed-data.md (the entity inventory, distributions, demo scenarios, and the factory contract) plus the seed scripts themselves. Seeds must be realistic (real-feeling names, plausible timestamps, domain-appropriate content), comprehensive (edge cases included), reproducible (seeded RNG), and idempotent (re-runnable without dupes). Consumed by incremental-implementation (factories for tests), demo-narrative (demo scenes), and testing-strategy (golden-test fixtures).

When to Use

• A new dev environment is being set up and there's no seed data
• A demo is coming up and the screenshots have lorem ipsum or "Test User"
• Test fixtures are inconsistent across the test suite — every test rebuilds its own data
• A bug only reproduces with specific data and no seed covers that case
• Multiple developers are stepping on each other's seed data in shared dev DB

When NOT to Use

• Production data migration — that's database-design + a one-off backfill ADR
• Schema design — that's database-design
• Loading anonymized production data for analytics — separate concern, distinct safety rules

Common Rationalizations

Red Flags

• Lorem ipsum visible in a screenshot, demo, or recording
• Every seeded user named "John Doe", "Test User", or user1 / user2
• All created_at timestamps within seconds of each other
• A seed script that errors on a second run (unique constraint violation)
• No edge-case scenarios: no empty states, no overflow, no missing-optional-field
• Production PII (real emails, names, phone numbers) checked into the seed file
• A demo that requires the demo-runner to "set up the data manually first"
• Factories that don't allow overrides — every test gets the same default user

Core Process

Step 1: Inventory entities needing seed

Read .forge/architecture.md and .forge/database-design.md. List every entity that needs seed data, with the minimum count for a realistic dev environment (e.g., 50 users, 200 tasks per user, 20 organizations, 5k events).

Step 2: Define realistic distributions per field

For each entity, decide what "realistic" means:

Step 3: Write factories with overrides

Every entity has a factory: createUser(overrides?: Partial<User>): User. Defaults from the distribution; overrides allow tests and demos to pin specific fields.

const user = createUser({ email: "demo@example.com", status: "active" });
const power = createUser({ taskCount: 500 });  // edge case

Factories use a seeded RNG (e.g., seedrandom) so the same seed produces the same data — critical for reproducible demos.

Step 4: Write demo-specific scenarios

For each demo scene in .forge/demo-narrative.md (or for each test-needed shape):

• Happy path scenario — the buyer-facing flow
• Empty state scenario — fresh user, no data
• Single-item scenario — one of everything
• Overflow scenario — long names, long content, many items
• Error state scenario — failed payment, expired card, locked account

Each scenario is a named function: seedDemoOnboardingScene(), seedDemoPowerUserScene(). The demo script runs the named scene.

Step 5: Make idempotent

Seeds upsert by a stable key — typically a slug or a UUIDv5 derived from a deterministic input. Re-running the script reconciles: missing rows are inserted, existing rows are updated, drift is corrected.

upsert("users", { stable_id: "demo:onboarding:alex" }, { ... });

The seed script can be run before every demo with confidence.

Step 6: Version + document in .forge/seed-data.md

• Inventory of entities + counts
• Distribution rules per field
• Factory API summary
• Named demo scenarios
• The stable-key naming convention
• The PII safety rule (no production data, ever)

Verification

• .forge/seed-data.md written
• Zero lorem ipsum anywhere in seed output (grep verified)
• No John Doe, Test User, or user1 in any seeded user
• Names span cultures, lengths, and character sets
• Timestamps spread across a realistic window with a realistic curve
• Every demo scene in .forge/demo-narrative.md has a corresponding seedDemo<Scene>() function
• Edge cases seeded: empty list, single item, overflow, error state
• Seed script runs twice without errors (idempotency tested in CI)
• No production PII (real emails, names, phone numbers) checked into the seed file
• Factories accept overrides for every field