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

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

Basics

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

`typescript
// ../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) {
Object.assign(this, attrs)
}
}
`

2. We would define our factories..

`typescript
// ../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', 2)
}, Village)

export {
FactoryBot
}
`

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

`typescript
// ../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

`typescript
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

`typescript
FactoryBot.define('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

`typescript
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

`typescript
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', { name: 'Uzimaki Naruto' }) /* => Ninja {
id: 11941,
name: 'Uzimaki Naruto',
username: 'Art_Crist36_1',
level: 'Genin',
sensor: true
} */

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

5. Define chained factories

`typescript
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', 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

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

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

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

FactoryBot.build('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.