Neverending Package Mountain

    TypeScript icon, indicating that this package has built-in type declarations

    3.2.2 • Public • Published

    factoria Main npm

    Simplistic model factory for Node/JavaScript, heavily inspired by Laravel's Model Factories.


    # install factoria
    $ yarn add factoria -D
    # install Faker as a peer dependency
    $ yarn add faker -D


    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.


    const define = require('factoria').define
    define('User', faker => ({
      id: faker.random.uuid(),
      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 "foo@bar.baz"
    const userWithSetEmail = factory('User', { email: 'foo@bar.baz' })
    // 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 + ' 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 => ({
      role: factory('Role')

    Calling factory('User') will generate an object of the expected shape e.g.,

      email: '',
      role: {
        name: 'admin'


    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 => ({
      verified: true
    }), {
      unverified: {
        verified: false

    State attributes can also be a function with Faker as the sole argument:

    factory.define('User', faker => ({
      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": [

    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.


    MIT © Phan An


    npm i factoria

    DownloadsWeekly Downloads






    Unpacked Size

    27.7 kB

    Total Files


    Last publish


    • phanan