progenitor¶ ↑

Progenitor is a factory gem. It can be used as a replacement for fixtures, or just as a unified interface for factories in application code. Unlike Factory Girl, it doesn’t assume your products inherit from ActiveRecord::Base, therefore it can be used with objects of any type.

Also, it is without the bloat of Factory Girl (well under 100 lines of code, not including tests) because I don’t try to create a fancy DSL for assignments when a simple = operator will do the same job.

Finally, you can use Progenitor alongside Factory Girl so that you don’t have to replace all your factories right away. Just be to load it after Factory Girl. See the examples for details.

You need to load Progenitor and then load the individual factories.

# in Gemfile
gem 'progenitor'

If you’re running a Rails app, add the following:

# in test/test_helper.rb
#load progenitor
require 'progenitor/all'
#then load each of the individual factories that you create, for example:
require 'factories/foo_factory'
require 'factories/bar_factory'
require 'factories/factory_that_makes_miniature_models_of_factories_factory'

Let’s say we want to create a factory for making instances of Foo

# in test/factories/foo_factory.rb
class FooFactory < Progenitor::Factory

  #simplest case
  create :foo do
    Foo.new
  end

end

Then, in a test or somewhere, call Factory :foo to produce an instance of Foo.

You can use a sequence if you need to create a persistent object or something else that needs a serial number or ID.

Sequence can be used in concurrent environments. It synchronizes calls on a Mutex, so it is safe for preemptive multitasking, and fail-fast when using cooperative multitasking (although all its methods release locks before accepting blocks, so it would be very hard to try to reacquire the same lock, but if you somehow managed to, you’d get bailed out by ThreadError)

# in test/factories/foo_factory.rb
class FooFactory < Progenitor::Factory

  # Instantiate a Sequence and assign to a class-instance variable in your factory class
  # IMPORTANT: do not instantiate the sequence inside the block you pass to create, or it will get reset each time you
  # call your factory
  @i = Progenitor::Sequence.new
  create :numbered_foo do
    foo = Foo.new
    foo.id = @i.next_int # call next_int to get a sequence number
    foo
  end

end

foo0 = Factory :numbered_foo
foo0.id #=> 0
foo1 = Factory :numbered_foo
foo1.id #=> 1

You can also start sequences at whatever value you desire, and there’s a convenience method for when you need the same sequence number for multiple fields

# in test/factories/foo_factory.rb
class FooFactory < Progenitor::Factory

  @i = Progenitor::Sequence.new 1 #the default starting point is 0, but you can set whatever you want
  create :numbered_foo do
    foo = Foo.new
    @i.in_sequence do |n|
      foo.id = n
      foo.name = "name#{n}"
    end
    foo
  end

end

foo1 = Factory :numbered_foo
foo1.id #=> 1
foo1.name #=> "name1"

foo2 = Factory :numbered_foo
foo2.id #=> 2
foo2.name #=> "name12"

We can get fancy and pass arguments to our factories. If you’re using Ruby 1.9 you can even specify default arguments.

# in test/factories/foo_factory.rb
class FooFactory < Progenitor::Factory

  #passing arguments
  create :foo do |bar, baz=3|
    foo = Foo.new
    foo.bar = bar
    foo.baz = baz
    foo
  end

end

foo = Factory :foo, "something"
foo.bar #=> "something"
foo.baz #=> 3

You can even pass blocks to your factories:

# in test/factories/foo_factory.rb
class FooFactory < Progenitor::Factory

  #passing a block
  create :foo do |arg, &block|
    foo = Foo.new
    block.call "in a block"
    foo
  end

end

foo = Factory :foo, :some_arg do |say_what|
  puts say_what
end

# "in a block" will be displayed

See test/test_progenitor.rb for more examples

If you’d ever want to, you can use Progenitor with Factory Girl. Just make sure that Factory Girl is loaded first, then when you call Factory :something, Progenitor will first see if it knows how to create :something and if not, will delegate to Factory Girl

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

• Fork the project

• Start a feature/bugfix branch

• Commit and push until you are happy with your contribution

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright © 2011 Paul Hieromnimon. See LICENSE.txt for further details.