Factory 🏭
This package makes testing easier by providing ways to create factories for your entities/models. Inspiration came from the Factory Boy 👦 python package and Factory Girl 👧.
You can also have a look at these projects:
Installation
NPM
npm install @adrien-may/factory --save-dev
Yarn
yarn add @adrien-may/factory --dev
Usage
This section provides a quick overview of what you can achieve with this package.
Factories
Declaration
To declare a factory, you have to provide:
- An adapter: ObjectAdapter, TypeormAdapter, ...
- An entity [Optional without typeorm]: the model you are building
- The fields to be populated (theirs default values or ways to generate them)
The adapter allows you to persist your data. If you want to save your data in a database via typeorm, you can use the TypeormAdapter . Default Adapter is ObjectAdapter and does not persist anything. You can create your own adapter to persist your data the way you want.
import { Factory } from '@adrien-may/factory';
// Object/Entity to create
class User {
email: string;
role: string;
}
// Factories
class UserFactory extends Factory<User> {
entity = User;
attrs = {
email: '[email protected]',
role: 'basic',
};
// By default, adapter is ObjectAdapter
}
class AdminUserFactory extends Factory<User> {
entity = User;
attrs = {
email: '[email protected]',
role: 'admin',
};
}
// Usage
const adminFactory = new AdminUserFactory();
const admin1 = adminFactory.create();
const admins = adminFactory.createMany(5);
Typeorm
import { Factory, TypeormFactory, TypeormAdapter } from '@adrien-may/factory';
import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
const dataSource = new DataSource({
type: 'sqlite',
database: ':memory:',
... // other typeorm options
});
@Entity()
class User {
@PrimaryGeneratedColumn()
id: number;
@Column('text')
email: string;
}
export class UserFactory extends TypeormFactory<User> {
entity = User;
attrs = {
email: '[email protected]',
};
}
// Usage
const userFactory = new UserFactory(dataSource);
const user = userFactory.create();
const users = userFactory.createMany(5);
Object and interfaces
You could use directly the factory without a defined entity and provide only an interface.
import { ObjectFactory } from '@adrien-may/factory';
interface User {
name: string;
}
class UserFactory extends ObjectFactory<User> {
// No entity defined
attrs = {
name: 'John Doe',
};
}
// Usage
const userFactory = new UserFactory();
const user = userFactory.create();
const users = userFactory.createMany(5);
Custom
You may want to use factory with other ORMs or CMS. To illustrate it we will demonstrate how you would create a factory for payload cms
For this, you should first create an adapter.
import { Adapter } from '@teammay/factory'
import {
DataFromCollectionSlug,
RequiredDataFromCollectionSlug,
} from 'node_modules/payload/dist/collections/config/types'
interface PayloadArgs {
draft: boolean;
locale: string
}
class PayloadAdapter extends Adapter<S extends CollectionSlug, [PayloadArgs?]> {
constructor(
private payload: Payload,
private slug: S,
) {}
async save(
instance: RequiredDataFromCollectionSlug<S> | RequiredDataFromCollectionSlug<S>[],
{ draft = false, locale = 'en' }: PayloadArgs = { draft: false, locale: 'en' },
): Promise<DataFromCollectionSlug<S> | DataFromCollectionSlug<S>[]> {
const instances = Array.isArray(instance) ? instance : [instance]
const savedInstances = await Promise.all(
instances.map((data) =>
this.payload.create({
collection: this.slug,
data,
draft,
locale,
}),
),
)
return Array.isArray(instance) ? savedInstances : savedInstances[0]
}
}
Now with this adapter, we can create a PayloadFactory class
import { Factory } from '@teammay/factory'
import {
DataFromCollectionSlug,
RequiredDataFromCollectionSlug,
} from 'node_modules/payload/dist/collections/config/types'
import { CollectionSlug, Payload } from 'payload'
abstract class PayloadFactory<S extends CollectionSlug> extends Factory<DataFromCollectionSlug<S>, [PayloadArgs?]> {
constructor(protected payload: Payload, protected slug: S) {
super()
this.adapter = new PayloadAdapter(payload, slug)
}
}
With this class we can now instantiate factories for every payload collections. For instance if we have a collection with slug 'author' and containing only one field 'name' we would do :
interface User {
name: string;
}
class UserFactory extends PayloadFactory<'author'> {
// No entity defined
attrs = {
name: 'John Doe',
};
}
// Usage
const userFactory = new UserFactory();
const user = userFactory.create({}, {draft: true, locale: 'fr'});
const users = userFactory.createMany(5, {}, {draft: false, locale: 'es'});
Fuzzy generation with Fakerjs/Chancejs/
To generate pseudo random data for our factories, we can take advantage of libraries like:
import { TypeormFactory } from '@adrien-may/factory';
import Chance from 'chance';
const chance = new Chance();
export class ProfileFactory extends TypeormFactory<Profile> {
entity = Profile;
attrs = {
name: () => chance.name(),
email: () => chance.email(),
description: () => chance.paragraph({ sentences: 5 }),
};
}
Note: Faker/Change are not included in this library. We only use the fact that a function passed to attrs is called every time a factory is created. Thus, you can use Faker/Chancejs to generate data.
Exploiting our created factories
We can use our factories to create new instances of entities:
const userFactory = new UserFactory();
For typeorm factories you should either set a default factory using:
import { setDefaultFactory } from '@adrien-may/factory';
{...}
setDefaultDataSource(typeormDatasource)
{...}
const userFactory = new UserFactory();
Or set a datasource for each instances using:
const userFactory = new UserFactory(typeormDatasource);
The factory and its adapters expose some functions:
- build: to create an object (and eventually generate data / subFactories)
- create: same as make but persist object in database via ORM "save" method
- buildMany and createMany allow to create several instances in one go
const user: User = await userFactory.create();
const users: User[] = await userFactory.createMany(5);
To override factory default attributes, add them as parameter to the create function:
const user: User = await userFactory.create({ email: '[email protected]' });
SubFactories
It is fairly common for entities to have relations (manyToOne, oneToMany, oneToOne etc...) between them. In this case we create factories for all the entities and make use of SubFactory to create a link between them. SubFactories will be resolved when instances are built. Note that this is pure syntactic sugar as one could use an arrow function calling another factory.
Example
If one user has a profile entity linked to it: we use the UserFactory as a SubFactory on the ProfileFactory
import { Factory, SubFactory } from '@adrien-may/factory';
import { UseFactory } from './user.factory.ts'; // factory naming is free of convention here, don't worry about it.
export class ProfileFactory extends Factory<Profile> {
entity = Profile;
attrs = {
name: 'Handsome name',
user: new SubFactory(UserFactory, { name: 'Override factory name' }),
};
}
Sequences
Sequences allow you to get an incremental value each time it is ran with the same factory. That way, you can use a counter to have more meaningful data.
import { Factory, Sequence } from '@adrien-may/factory';
export class UserFactory extends Factory<User> {
entity = User;
attrs = {
customerId: new Sequence((nb: number) => `cust__abc__xyz__00${nb}`),
};
}
Lazy Attributes
Lazy attributes are useful when you want to generate a value based on the instance being created. They are resolved after every other attribute but BEFORE saving the entity. For any action "post save", use the PostGenerate hook.
import { Factory, LazyAttribute } from '@adrien-may/factory';
export class UserFactory extends Factory<User> {
entity = User;
attrs = {
name: 'Sarah Connor',
mail: new LazyAttribute(instance => `${instance.name.toLowerCase()}@skynet.org`),
};
}
Lazy Sequences
Lazy sequences combine the power of sequences and lazy attributes. The callback is called with an incremental number and the instance being created.
import { Factory, LazySequence } from '@adrien-may/factory';
export class UserFactory extends Factory<User> {
entity = User;
attrs = {
name: 'Sarah Connor',
mail: new LazySequence((nb, instance) => `${instance.name.toLowerCase()}.${nb}@skynet.org`),
};
}
Post Generations
To perform actions after an instance has been created, you can use the PostGeneration decorator.
import { Factory, PostGeneration } from '@adrien-may/factory';
export class UserFactory extends Factory<User> {
...
@PostGeneration()
postGenerationFunction() {
// perform an action after creation
}
@PostGeneration()
async actionOnCreatedUser(user: User) {
// do something with user
}
}
Adapters
You can provide your own adapter to extend this library. This library provides for now ObjectAdapter (default) and TypeormAdapter .
To ease testing, this library provides a TypeormFactory class.
The following example shows how to use them:
import { Factory, TypeormFactory, TypeormAdapter } from '@adrien-may/factory';
export class UserFactory extends Factory<User> {
entity = User;
attrs = {
email: '[email protected]',
role: 'basic',
};
adapter = TypeormAdapter();
}
// Same as:
export class TypeormUserFactory extends TypeormFactory<User> {
entity = User;
attrs = {
email: '[email protected]',
role: 'admin',
};
}
Seeding (NEW)
You can now easily seed your database using your factories with the runSeed utility.
Example
Create a seed.ts file in your project:
import { runSeed } from '@adrien-may/factory';
import { UserFactory } from './factories/user.factory';
import { PostFactory } from './factories/post.factory';
import { dataSource } from './db'; // your TypeORM DataSource
export let fixtures: any = {};
async function main() {
fixtures = await runSeed({
dataSource,
factories: { UserFactory, PostFactory },
seeds: async ({ UserFactory, PostFactory }) => {
const users = await UserFactory.createMany(10);
const posts = await PostFactory.createMany(20);
return {
users,
posts,
};
},
});
}
main();
- All factories are instantiated with the provided
dataSource. - You can use all factory methods (create, createMany, etc) inside the
seedsfunction. - This utility is framework-agnostic but works best with TypeORM.
- You can access created instances via the
fixturesobject.
Example: Seeding in Jest setup
You can also use runSeed in your Jest setup to ensure your test database is seeded before tests run:
// jest.setup.ts
import { runSeed } from '@adrien-may/factory';
import { UserFactory } from './factories/user.factory';
import { dataSource } from './db';
beforeAll(async () => {
await runSeed({
dataSource,
factories: { UserFactory },
seeds: async ({ UserFactory }) => {
await UserFactory.createMany(5);
},
});
});
Example: Running seeds via npm
Add this to your package.json scripts:
"scripts": {
"seed": "ts-node ./seed.ts"
}
Then run:
npm run seed