Test Data Factories skill for Claude Code

Good test data is valid by default, minimal in each test, unique where the schema needs uniqueness, and reproducible. A reader should see in the test exactly which fields drive the outcome; everything else comes from the factory.

Ground rules

• One factory per domain entity, producing a valid object with zero arguments.
• Tests override only the fields that matter to the assertion. If a test depends on a default value, set that value explicitly in the test.
• Unique fields use sequences, never random values alone (randomness collides eventually and is not reproducible).
• Prefer build (in memory) over create (persisted). Persist only when the code under test reads from the database.
• Factories create the minimum graph. Associations are created lazily or on request, not five levels deep by default.
• Never copy raw production data into tests or dev environments.

Workflow

- [ ] 1. Inventory entities, required fields, unique constraints, relationships
- [ ] 2. Write one factory per entity with valid defaults and sequences
- [ ] 3. Add traits for common named states (admin, archived, overdue)
- [ ] 4. Replace inline literals and shared fixtures in tests
- [ ] 5. Seed Faker deterministically and log the seed
- [ ] 6. Build seed scripts or masked datasets for non-test environments

2–3. Factories by ecosystem

TypeScript (fishery):

import { Factory } from 'fishery';
import { faker } from '@faker-js/faker';

class UserFactory extends Factory<User> {
  admin() { return this.params({ role: 'admin' }); }
  suspended() { return this.params({ status: 'suspended', suspendedAt: new Date('2026-01-01T00:00:00Z') }); }
}

export const userFactory = UserFactory.define(({ sequence, onCreate }) => {
  onCreate((user) => db.user.create({ data: user }));
  return {
    id: `usr_${sequence}`,
    email: `user${sequence}@example.test`,
    name: faker.person.fullName(),
    role: 'member',
    status: 'active',
    createdAt: new Date('2026-01-01T00:00:00Z'),
  };
});

// usage
const admin = userFactory.admin().build({ name: 'Ada' });
const members = userFactory.buildList(3);
const persisted = await userFactory.create();

Python (factory_boy):

import factory
from factory.django import DjangoModelFactory   # or factory.alchemy.SQLAlchemyModelFactory

class UserFactory(DjangoModelFactory):
    class Meta:
        model = User

    email = factory.Sequence(lambda n: f"user{n}@example.test")
    name = factory.Faker("name")
    role = "member"
    team = factory.SubFactory(TeamFactory)

    class Params:
        admin = factory.Trait(role="admin", is_staff=True)

# usage
UserFactory.build(name="Ada")         # unsaved
UserFactory(admin=True)               # saved, with trait
UserFactory.create_batch(3, team=team)

Ruby (FactoryBot):

FactoryBot.define do
  factory :user do
    sequence(:email) { |n| "user#{n}@example.test" }
    name { "Test User" }
    role { "member" }
    trait :admin do
      role { "admin" }
    end
  end
end

build_stubbed(:user)          # fastest; no DB
create(:user, :admin)

Builders without a library work well for value objects and small codebases:

export const anOrder = (overrides: Partial<Order> = {}): Order => ({
  id: 'ord_1', currency: 'USD', items: [anItem()], status: 'pending', ...overrides,
});

Name builders aX / anX so tests read naturally: applyCoupon(anOrder({ items: [] }), aCoupon()).

Associations

Need	Approach
Test reads only the child	Build the child with a parent ID, no parent object
Test needs the parent loaded	SubFactory / associations built on demand
Many children share one parent	Create the parent once in the test and pass it in
Deep graphs (org → team → project → task)	Explicit helper per scenario (givenProjectWithTasks(3)), not default cascades

A default that silently creates an organization, a billing account, and three users per create() makes every test slow and every failure confusing.

4. Replace fixtures

Shared static fixtures (fixtures/users.json, a seeded user1 used by 80 tests) cause mystery-guest tests and cross-test coupling. Migrate incrementally: when touching a test, replace its fixture reference with a factory call that sets the relevant fields.

5. Determinism

// test setup
import { faker } from '@faker-js/faker';
const seed = Number(process.env.TEST_SEED ?? Date.now() % 100000);
faker.seed(seed);
console.log(`faker seed: ${seed}`);   // replay with TEST_SEED=<seed>

factory_boy: factory.random.reseed_random(seed). Faker values belong in fields that do not affect assertions; anything an assertion depends on is set explicitly.

Fixed timestamps beat new Date() in factories. If time matters, take it from an injected clock.

6. Seed data and production-like datasets

Dev/staging seed scripts:

• Idempotent: upsert by natural key so running twice changes nothing.
• Built from the same factories, so seeds stay valid as the schema evolves.
• Include named personas for manual testing ([email protected], [email protected]), plus volume data for performance-sensitive screens.
• Run from a single command (npm run db:seed, python manage.py seed, or the ORM’s seed hook, e.g. npx prisma db seed).

Anonymized production-like data (for realistic volume and distribution):

1. Get explicit approval from the data owner; document the purpose and retention.
2. Subset first (e.g., 1% of tenants with referential integrity preserved).
3. Mask every PII column by rule: emails → user{id}@example.test, names → Faker with a deterministic seed per row, phones → fictional ranges, addresses → generated, free-text fields → replaced entirely (they contain PII in unpredictable places).
4. Keep shapes that matter for testing: string lengths, null rates, distributions, edge characters (Unicode names), foreign key cardinality.
5. Run masking inside the trusted environment (tools like PostgreSQL Anonymizer or Greenmask, or a scripted transform) so unmasked data never leaves it.
6. Verify: scan the output for real email domains, phone patterns, and known VIP names before distributing.

Use reserved values: example.com/example.test domains, 555-01xx style fictional phone numbers, test card numbers from the payment provider’s docs.

Gotchas

• Unique constraint failures in parallel test workers: sequences are per process; prefix with the worker ID or use UUIDs plus a sequence.
• Factories that call the API or services under test create circular dependencies; write directly to the DB or build in memory.
• Faker locale changes or upgrades change generated values; tests asserting on Faker output break. Assert only on explicit values.
• build objects missing DB defaults (timestamps, generated IDs) cause false passes; set them in the factory.
• Traits that conflict (archived + active) should raise, not silently pick one.

Verification

1. Every factory builds a valid object with no arguments; add a test per factory that validates against the schema or saves it.
2. Run the suite in parallel and shuffled: no unique-constraint or order failures.
3. Grep tests for large inline object literals and shared fixture IDs that remain.
4. For masked datasets, run the PII scan and record the result.