factory-bot-ts

A simple library for setting up TypeScript objects as test data - heavily inspired by the awesome Ruby's factory_bot.

• Fully written in TypeScript
• With (optional) type checking
• With no persistence layer
• And no promises. ☺️

Installation

1. Add to your project

npm i -D factory-bot-ts
yarn add factory-bot-ts --dev

Basics

1. Ok, suppose we've got a Ninja model..

  // ../src/models/ninja.model.ts

  export enum NinjaRank {
    GENIN = 'Genin',
    CHUUNIN = 'Chuunin',
    JONIN = 'Jonin'
  }

  export class Ninja {
    id?: number
    name?: string
    username?: string
    level?: NinjaRank
    sensor?: boolean

    constructor(attrs?: Partial<Ninja>) {
      Object.assign(this, attrs)
    }
  }

2. We would define our factories..

  // ../src/tests/index.ts

  import * as Faker from 'faker'
  import { sample } from 'lodash'

  import { FactoryBot } from 'factory-bot-ts'

  import { Ninja, NinjaRank, Village } from '../src/models'

  FactoryBot.define('ninja', {
    id: () => Faker.random.number(),
    name: () => Faker.name.findName(),
    username: () => FactoryBot.seq(seq => `${Faker.internet.userName()}_${seq}`),
    level: () => FactoryBot.rand(NinjaRank),
    sensor: () => sample([true, false])
  }, Ninja)

  FactoryBot.define('village', {
    id: () => Faker.random.uuid(),
    name: () => Faker.name.findName(),
    members: () => FactoryBot.buildList<Ninja>('ninja', 2)
  }, Village)

  export {
    FactoryBot
  }

3. And then we'd just use them on our tests!

  // ../src/models/ninja.model.spec.ts

  import { FactoryBot } from '../src/tests'

  import { Ninja, NinjaRank, Village } from '.'

  export class NinjaSpec {
    let instance: Ninja

    before(() => {
      instance = FactoryBot.build('ninja', { name: 'Kakashi Hatake' })
    })

    it('builds a Ninja! 👹', () => {
      expect(instance).to.be.an
        .instanceof(Ninja)
    })
  }

More

Factory-bot-ts also allow us to..

1. Define untyped factories with static data

  FactoryBot.define('ninja', {
    id: 1,
    name: 'Sasuke Uchiha',
    username: 'sasuke',
    level: NinjaRank.GENIN,
    sensor: false,
    sharingan: true
  })

  FactoryBot.build('ninja') /* => {
    id: 1,
    name: 'Sasuke Uchiha',
    username: 'sasuke',
    level: 'Genin',
    sensor: false,
    sharingan: true
  } */

2. Define factories with type checking

  FactoryBot.define<Ninja>('ninja', {
    id: 1,
    name: 'Sasuke Uchiha',
    username: 'sasuke',
    level: NinjaRank.GENIN,
    sensor: false
  }, Ninja)

  FactoryBot.build('ninja') /* => Ninja {
    id: 1,
    name: 'Sasuke Uchiha',
    username: 'sasuke',
    level: 'Genin',
    sensor: false
  } */

3. Define factories with Dynamic data

  FactoryBot.define('ninja', {
    id: () => Faker.random.number(),
    name: () => Faker.name.findName(),
    username: () => Faker.internet.userName(),
    level: () => FactoryBot.rand(NinjaRank),
    sensor: () => sample([true, false])
  }, Ninja)

  FactoryBot.build('ninja') /* => Ninja {
    id: 43748,
    name: 'Martine Romaguera MD',
    username: 'Kaleb_Homenick',
    level: 'Jonin',
    sensor: true
  } */

4. Define factories with custom, random and sequenced data

  FactoryBot.define('ninja', {
    id: () => Faker.random.number(),
    name: () => Faker.name.findName(),
    username: () => FactoryBot.seq(seq => `${Faker.internet.userName()}_${seq}`),
    level: () => FactoryBot.rand(NinjaRank),
    sensor: () => sample([true, false])
  }, Ninja)

  FactoryBot.build<Ninja>('ninja', { name: 'Uzimaki Naruto' }) /* => Ninja {
    id: 11941,
    name: 'Uzimaki Naruto',
    username: 'Art_Crist36_1',
    level: 'Genin',
    sensor: true
  } */

  FactoryBot.build<Ninja>('ninja', { name: 'Sasuke Uchiha', username: 'sasuke-kun' }) /* => Ninja {
    id: 52565,
    name: 'Sasuke Uchiha',
    username: 'sasuke-kun',
    level: 'Chuunin',
    sensor: false
  } */

5. Define chained factories

  FactoryBot.define('ninja', {
    id: () => Faker.random.number(),
    name: () => Faker.name.findName(),
    username: () => FactoryBot.seq(seq => `${Faker.internet.userName()}_${seq}`),
    level: () => FactoryBot.rand(NinjaRank),
    sensor: () => sample([true, false])
  }, Ninja)

  FactoryBot.define('village', {
    id: () => Faker.random.uuid(),
    name: 'Leaf',
    members: () => FactoryBot.buildList<Ninja>('ninja', 2)
  }, Village)

  FactoryBot.build('village') /* => Village {
    id: '7ec17407-cfdb-4a3f-b434-de788eb41591',
    name: 'Leaf',
    members: [ Ninja {
      id: 11941,
      name: 'Herta Hane',
      username: 'Kaleb_Homenick_5',
      level: 'Genin',
      sensor: true
    }, Ninja {
      id: 52565,
      name: 'Corbin Koss',
      username: 'Art_Crist36_6',
      level: 'Genin',
      sensor: false
    }]
  } */

6. Extend existing factories in order to generate specialized data

  FactoryBot.define<Ninja>('ninja', {
    id: 1,
    name: 'Kakashi Hatake',
    username: 'kakashi',
    level: NinjaRank.GENIN,
    sensor: false
  }, Ninja)

  FactoryBot.extend<Ninja>('ninja', 'jōnin', {
    level: NinjaRank.JONIN
  })

  FactoryBot.build<Ninja>('ninja') /* => Ninja {
    id: 1,
    name: 'Kakashi Hatake',
    username: 'kakashi',
    level: Genin,
    sensor: false
  } */

  FactoryBot.build<Ninja>('jōnin') /* => Ninja {
    id: 1,
    name: 'Kakashi Hatake',
    username: 'kakashi',
    level: Jōnin,
    sensor: false
  } */

For more examples, please, check out the project's specs.

Dependencies

To run this project we need to have:

• Node
• Yarn

Development

1. Install the dependencies above
2. $ git clone https://github.com/roalcantara/factory-bot-ts.git - Clone the project
3. $ cd factory-bot-ts - Go into the project folder
4. $ yarn - Run the setup script

Running specs

$ yarn test to run the specs

How to contribute

• Bug reports and pull requests are welcome on GitHub
• Follow the Semantic Versioning Specification
• Follow the GitHub Flow
• Follow the 5 Useful Tips For A Better Commit Message article and the How to Write a Git Commit Message post
• Use Commitizen cli when committing

Code of Conduct

Everyone interacting in the factory-bot-ts project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

License

The package is available as open source under the terms of the CC BY-SA 4.0.