Documentation / @zerotal/testing / index / Factory

Class: Factory<T>

Fluent, type-safe model factory for tests and database seeders.

Define once, use everywhere. The definition callback receives the built-in fake helper for quick random data — or ignore it and use your own faker.

Example

// database/factories/UserFactory.ts
export const UserFactory = Factory.define(User, (f) => ({
  name:     f.string(10),
  email:    f.email(),
  password: 'password',  // auto-hashed by BaseModel.hashable
}));

// In a test:
const user   = await UserFactory.create({ name: 'Alice' });
const five   = await UserFactory.count(5).create();
const sub    = await SubscriptionFactory.state('expired').create();
const post   = await PostFactory.for(user).create();

Type Parameters

T

T extends BaseModel

Properties

_ModelClass

protected readonly _ModelClass: ModelCtor<T>

Defined in: testing/src/factory.ts:104

_definition

protected readonly _definition: DefinitionFn<T>

Defined in: testing/src/factory.ts:105

_config

protected readonly _config: FactoryConfig<T>

Defined in: testing/src/factory.ts:106

Methods

define()

static define<T>(ModelClass, definition): Factory<T>

Defined in: testing/src/factory.ts:110

Define a factory for a model class. Returns a reusable Factory<T> instance.

Type Parameters

T

T extends BaseModel

Parameters

ModelClass

ModelCtor<T>

definition

DefinitionFn<T>

Returns

Factory<T>

state()

state(stateName): Factory<T>

Defined in: testing/src/factory.ts:124

Force the created instance to stateName via forceState(), bypassing all guards and onTransition callbacks.

Parameters

stateName

string

Returns

Factory<T>

Example

const expired = await SubscriptionFactory.state('expired').create();

for()

for(model, foreignKey?): Factory<T>

Defined in: testing/src/factory.ts:139

Inject a parent model's primary key as a foreign key. foreignKey defaults to <ModelName>Id (camelCase).

Parameters

model

BaseModel

foreignKey?

string

Returns

Factory<T>

Example

const post = await PostFactory.for(user).create();
const post = await PostFactory.for(user, 'authorId').create();

afterCreate()

afterCreate(callback): Factory<T>

Defined in: testing/src/factory.ts:149

Run callback after each instance is created.

Parameters

callback

(instance) => void | Promise<void>

Returns

Factory<T>

dispatchEvents()

dispatchEvents(): Factory<T>

Defined in: testing/src/factory.ts:172

Enable observer and hook dispatch for instances created by this factory.

By default factories silence all model observers and hooks so that seeders don't emit side-effects (logs, emails, jobs). Call .dispatchEvents() when you explicitly need the full lifecycle to fire — e.g. in a test that asserts a side-effect triggered by model creation.

Returns

Factory<T>

Example

// Seeder — silent by default, no "User registered" log spam
await UserFactory.count(20).create();

// Test — assert the welcome email was queued
const user = await UserFactory.dispatchEvents().create();
Queue.assertDispatched(WelcomeEmailJob);

count()

count(n): FactoryBatch<T>

Defined in: testing/src/factory.ts:186

Switch to batch mode — create() will return Promise<T[]> instead of Promise<T>.

Parameters

n

number

Returns

FactoryBatch<T>

Example

const users = await UserFactory.count(5).create();
//    ^? User[]

make()

make(overrides?): T

Defined in: testing/src/factory.ts:191

Build an in-memory instance without touching the database.

Parameters

overrides?

Partial<InsertPayload<T>> = {}

Returns

T

create()

create(overrides?): Promise<T>

Defined in: testing/src/factory.ts:210

Insert a single instance into the database.

Parameters

overrides?

Partial<InsertPayload<T>> = {}

Returns

Promise<T>

createMany()

createMany(n, overrides?): Promise<T[]>

Defined in: testing/src/factory.ts:215

Insert n instances sequentially without switching to batch mode.

Parameters

n

number

overrides?

Partial<InsertPayload<T>> = {}

Returns

Promise<T[]>