factoria
v4.0.1
Published
Simplistic model factory for Node/JavaScript
Downloads
2,141
Readme
factoria
Simplistic model factory for Node/JavaScript, heavily inspired by Laravel's Model Factories.
Install
# install factoria
$ yarn add factoria -D
# install Faker as a peer dependency
$ yarn add @faker-js/faker -D
Usage
1. Define a model
To define a model, import and use define
from the module. define
accepts two arguments:
name
: (string) Name of the model, e.g.'user'
(faker)
(function) A closure to return the model's attribute definition as an object. This closure will receive a Faker instance, which allows you to generate various random testing data.
Example:
const define = require('factoria').define
define('User', faker => ({
id: faker.random.uuid(),
name: faker.name.findName(),
email: faker.internet.email(),
age: faker.random.number({ min: 13, max: 99 })
}))
// TypeScript with generics
define<User>('User', faker => ({
// A good editor/IDE should suggest properties from the User type
}))
2. Generate model objects
To generate model objects, import the factory and call it with the model's defined name. Following the previous example:
import factory from 'factoria'
// The simplest case, returns a "User" object
const user = factory('User')
// Generate a "User" object with "email" preset to "[email protected]"
const userWithSetEmail = factory('User', { email: '[email protected]' })
// Generate an array of 5 "User" objects
const users = factory('User', 5)
// Generate an array of 5 "User" objects, each with "age" preset to 27
const usersWithSetAge = factory('User', 5, { age: 27 })
// Use a function as an overriding value. The function will receive a Faker instance.
const user = factory('User', {
name: faker => {
return faker.name.findName() + ' Jr.'
}
})
// TypeScript with generics
const user = factory<User>('User') // `user` is of type User
const users: User[] = factory<User>('User', 3) // `users` is of type User[]
Nested factories
factoria fully supports nested factories. For example, if you have a Role
and a User
model, the setup might look like this:
import factory from 'factoria'
factory.define('Role', faker => {
name: faker.random.arrayElement(['user', 'manager', 'admin'])
}).define('User', faker => ({
email: faker.internet.email(),
role: factory('Role')
}))
Calling factory('User')
will generate an object of the expected shape e.g.,
{
email: '[email protected]',
role: {
name: 'admin'
}
}
States
States allow you to define modifications that can be applied to your model factories. To create states, add an object as the third parameter of factory.define
, where the key being the state name and its value the state's attributes. For example, you can add an unverified
state for a User model this way:
factory.define('User', faker => ({
email: faker.internet.email(),
verified: true
}), {
unverified: {
verified: false
}
})
State attributes can also be a function with Faker as the sole argument:
factory.define('User', faker => ({
email: faker.internet.email(),
verified: true
}), {
unverified: faker => ({
verified: faker.random.arrayElement([false]) // for the sake of demonstration
})
})
You can then apply the state by calling the method states()
with the state name, which returns the factoria instance itself:
const unverifiedUser = factory.states('unverified')('User')
You can also apply multiple states:
const fourUnverifiedPoorSouls = factory.states('job:engineer', 'unverified')('User', 4)
Test setup tips
Often, you want to set up all model definitions before running the tests. One way to do so is to have one entry point for the factories during test setup. For example, you can have this test
script defined in package.json
:
{
"test": "mocha-webpack --require test/setup.js tests/**/*.spec.js"
}
Or, if Jest is your cup of tea:
{
"jest": {
"setupFilesAfterEnv": [
"<rootDir>/test/setup.js"
]
}
}
Then in test/setup.js
you can import factoria
and add the model definitions there.
Another approach is to have a wrapper module around factoria, have all models defined inside the module, and finally export
factoria itself. You can then import
the wrapper and use the imported object as a factoria instance (because it is a factoria instance), with all model definitions registered:
// tests/factory.js
import factory from 'factoria'
// define the models
factory.define('User', faker => ({}))
.define('Group', faker => ({}))
// now export factoria itself
export default factory
// tests/user.spec.js
import factory from './factory'
// `factory` is a factoria function instance
const user = factory('User')
factoria itself uses this approach for its tests.
License
MIT © Phan An