Library for factorizing objects factory testing
0.1.5 Latest release released

Factory Build Status Latest Release Docs

Easy to use but flexible factory definition utility. Could be used for testing purpose and for developing as well.


Add this to your application's shard.yml:

    github: imdrasil/factory


require "factory"

To define new factory

class HumanFactory < Factory::Base

By convenience this factory will builds Human class but this behavior can be overrided using describe_class macro:

class AdminFactory < Factory::Base
  describe_class User

Factory will build class passing to constructor hash with string keys, so those class should be ready for this. To define attributes for passing to constructor use attr macro:

class TestFactory < Factory::Base
  attr :f1, "Ivan"
  attr :f2, rand, Float64
  attr :f3, -> { rand(1..3) }

Attributes, passed as Proc will be executed each time. Other ones - only once and cached. If type could be analyzed (as with calling rand upper), you can specify exact type passing it as third parameter.

There is also assign strategy using assign macro. Using it all attributes will be assigned after initializing.

class TestFactory < Factory::Base
  assign :f1, "Ivan"
  assign :f2, rand, Float64
  assign :f3, -> { rand(1..3 }

# Will be do smth like
obj = Test.new
obj.f1 = TestFactory.f1 # "Ivan"
obj.f2 = TestFactory.f2 # 0.61 - just random value shared across all object
obj.f3 = -> { rand(1..3) }.call

If you specify no attr - will call construtor without any arguments and you will not be able pass anything to it.

If you need to specify exact type of given hash value use argument_type:

class Test
  @@static = 1
  @@dynamic = 1
  property f1 : String, f2 : Int32, f3 : Float64,
    f4 : String?, f5 : Int32?, f6 : Array(Int32)?

  def initialize(hash)
    @f1 = hash["f1"].as(String)
    @f2 = hash["f2"].as(Int32)
    @f3 = hash["f3"].as(Float64)
    @f6 = hash["f6"].as(Array(Int32)) if hash.has_key?("f6")

class TestFactory < Factory::Base
  argument_type String | Int32 | Float64 | Array(Int32)
  attr :f1, "some"
  attr :f2, 1
  attr :f3, rand, Float64

Also after_initialize callback could be specified:

class TestFactory < Factory::Base
  after_initialize do |t|
    super # if you want parrent one to be inked as well
    t.f1.not_nil! += 1

Builder method could be specified as well:

class TestFactory < Factory::Base
  # here is default builder
  initialize_with do |hash, traits|
    obj = Test.new(hash)
    make_assigns(obj, traits) # makes all assignements (traits will be described later)

To specify sequence of some attributes (only allowed as attr hook) use sequence:

sequence(:f1) { |i| "user#{i}@example.com" }

You could inherite from existing factory and override some parameters:

class HumanFactory < Factory::Base
  describe_class User
  attr :f1, "asd"

class AdminFactory < HumanFactory
  attr :f1, "admin"
  assign :f2, 1

Child factory inherits all attrs, assigns, traits, sequences, callbacks, class names, has value type.

To group several attributes or assignments use trait.

class HumanFactory < Factory::Base
  trait :homo do
    attr :iq, 50

Traits can't specify callbacks, described type, hash value type.

To build object direct call could be used

HumanFactory.build(some_attr: "asd")
HumanFactory.build({"some_attr" => "asd")
HumanFactory.build(["some_trait"], some_attr: "asd")
HumanFactory.build(["some_trait"], {"some_attr" => "asd"})

Also helper methods are defined as well

Factory.build_human(some_attr: "asd")
Factory.build_human({"some_attr" => "asd")
Factory.build_human(["some_trait"], some_attr: "asd")
Factory.build_human(["some_trait"], {"some_attr" => "asd"})
# also you can specify count as first parameter in any of thos methods
Factory.build_human(3, ["some_trait"], {"some_attr" => "asd"})

Jennifer Support

To create factory for (Jennifer)[https://github.com/imdrasil/jennifer.cr] model

# require all jennifer staff and models
require "factory"
require "factory/jennifer"

class FilmFactory < Factory::Jennifer::Base
  attr :rating, 5
  assign :name, "Test Film" 

  trait :bad do
    assign :rating, 0

It provides direct creating methods same as for building:

FilmFactory.create([:bad], {:name => "Atilla"})

Also any association could be described on the factory or trait level:

class FilmFactory < Factory::Jennifer::Base
  association :author
  association :actor, UserFactory, options: {name: "Artemius Fault"}

Allowed arguments:

  • :name - first argument - represent model association name (mandatory)
  • :factory - represents factory class (optional); is defaulted from association name
  • :strategy - represents creation strategy; optional; default is "create" (also "build" is allowed)
  • :options - represents extra arguments to association factory; optional


For development postgres is required because of testing integration with Jennifer.

Possible next tasks:

  • think about adding assigning via hash or named tuble argument;
  • adding %attr to traits.


  1. Fork it ( https://github.com/imdrasil/factory/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


  • imdrasil Roman Kalnytskyi - creator, maintainer
  github: imdrasil/factory
  version: ~> 0.1.5
License MIT
Crystal >= 0.34.0


Dependencies 0

Development Dependencies 5

  • ameba = 0.14.3
    {'github' => 'crystal-ameba/ameba', 'version' => '= 0.14.3'}
  • jennifer master
    {'branch' => 'master', 'github' => 'imdrasil/jennifer.cr'}
  • minitest ~> 1.0.0
    {'github' => 'ysbaddaden/minitest.cr', 'version' => '~> 1.0.0'}
  • pg
    {'github' => 'will/crystal-pg'}
  • sam ~> 0.4.1
    {'github' => 'imdrasil/sam.cr', 'version' => '~> 0.4.1'}

Dependents 1

Last synced .
search fire star recently