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:

• typeorm-seeding
• typeorm-factories
• typeorm-factory
• factory-girl-typeorm

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: 'adrien@factory.com',
    role: 'basic',
  };
  // By default, adapter is ObjectAdapter
}

class AdminUserFactory extends Factory<User> {
  entity = User;
  attrs = {
    email: 'adrien@factory.com',
    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: 'adrien@factory.com',
  };
}

// 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 { Factory } from '@adrien-may/factory';

interface User {
  name: string;
}

class UserFactory extends Factory<User> {
  // No entity defined
  attrs = {
    name: 'John Doe',
  };
}

// Usage
const userFactory = new UserFactory();
const user = userFactory.create();
const users = userFactory.createMany(5);

Fuzzy generation with Fakerjs/Chancejs/

To generate pseudo random data for our factories, we can take advantage of libraries like:

• Fakerjs
• Chancejs
• ...

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: 'adrien@example.com' });

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: 'adrien@factory.com',
    role: 'basic',
  };
  adapter = TypeormAdapter();
}

// Same as:
export class TypeormUserFactory extends TypeormFactory<User> {
  entity = User;
  attrs = {
    email: 'adrien@factory.com',
    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 seeds function.
• This utility is framework-agnostic but works best with TypeORM.
• You can access created instances via the fixtures object.

---

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

---