Credits

Originally written by Nathan Herald @ Myobie.com

Feature enhancements by David Lowenfels @ InternautDesign.com

Gemification by Jonathan Barket

Get It

Add it as a gem dependency

  config.gem 'dfl-factories-and-workers', :lib => 'factories-and-workers', :source => 'http://gems.github.com' unless RAILS_ENV=='production'

Or install it as a gem manually

  sudo gem install dfl-factories-and-workers

Or grab the source

  git clone git://github.com/dfl/factories-and-workers.git

The Factory

The Factory idea was inspired completely by Dan Manges’ blog post "Fixin’ Fixtures with Factory" @ www.dcmanges.com/blog/38

The Factory is a module that has three methods for each model: build_model, create_model and valid_model_attributes. ( For semantic purposes, default_model_attributes is also available as an alias to valid_model_attributes. )

These methods create objects in a valid state, with default attributes and associations. When using the create_model and build_model methods, you can pass in a hash to override any of the default attributes if needed. Typically, you should create a file named ‘factories.rb’ in either the spec or test directory in your project to declare factory methods and default attributes. It will be loaded during plugin initialization (see init.rb). You could also explicitly require it from test_helper.rb

A minimal factories.rb file:

  factory :user, :name => "default name"

This would define methods named build_user, create_user, and valid_user_attributes to be available in any Object in the project. If you wanted to override the default valid attributes, you could call:

  create_user( :name => "a different name" )

A more complicated example:

  factory :role, :title => "role title"

  factory :user, {
    :first_name => "Joe",
    :last_name  => "Momma",
    :password   => "$UNIQ(7)",                      # the $UNIQ(n) magic variable interpolates to a unique string of length n
    :login      => "user_$COUNT",                   # the $COUNT magic variable interpolates to an incremental number, beginning with 1
    :role       => :belongs_to_model,
    :created_at => lambda { Time.zone.now - 7 }     # lazy evaluation: will be called on object instantiation rather than factory definition
  } do |u|                                          # code to be called in after_initialize hook
    u.email = "#{u.first_name}.#{u.last_name}@example.com".downcase
  end

  factory :order, {
    :quantity => 5,
    :price    => 500,
    :user     => :belongs_to_model
    :number   => lambda { increment! :foo }         # increment a counter by arbitrary key
  }

  factory :special_order, {
    :kind => 'Special'
  }, :class => Order, :chain => lambda{ valid_order_attributes }   # reverse merges with valid_order_attributes

A value of :belongs_to_model on an attribute adds logic to call create_ or build_, appropriately. For example:

  valid_user_attributes         # assigns :role => build_role
  build_user                    # assigns :role => build_role

  create_user                   # assigns :role => create_role
  valid_user_attributes(true)   # assigns :role => create_role

In this way, models are not saved to the database unnecessarily.

Note that if you pass a foreign key attribute as a build or create override, the corresponding default object will not be constructed. For example:

  create_user( :role_id => 1 ) # will not call create_role.

Two helper methods are available to be used in lambda blocks:

• increment!( key ) — increments a global counter keyed on a symbol or string
• uniq( length ) — returns a random string

There is also a rake task to automagically generate template factories from your models.

  rake factory:generate             # will print templates for all AR models
  rake factory:generate MODEL=user  # will print template for user model

Factories also really come in handy in the development console. The plugin and factories.rb are automatically loaded for test and development environments (see init.rb)

The FactoryWorker

The FactoryWorker is a work in progress and is not automatically loaded with init.rb. Ideally it would behave sort of like a fixture scenario. Anyone want to help make this happen? It currently doesn’t execute in the same scope/binding as where it’s called from, which means instance variables aren’t shared :(

If you create a file named ‘factory_workers.rb’ in either your spec or test directory, you can define snippets of code that can be ran at anytime, anywhere in your tests (this may not be true in the future, I may limit where it can be run, iono).

A factory worker is defined as so:

  factory_worker :name do
    # any ruby code you want
  end

Then, in your tests you can call ‘worker :name’ to run the ruby code contained in the worker.

It can be useful for populating the database with objects:

  factory_worker :salable_and_non_salable_products do
    create_variant( :sku => "1" )
    create_variant( :sku => "2" )
    create_variant( :sku => "3", :in_stock => false )
    create_variant( :sku => "4", :in_stock => false )
  end

The create_variant method would provided by my factory setup, and creates a valid product with associated colors, sizes, and other options that I need. Now, I have 4 products in the database, 2 are in stock and 2 are not. So, in my test: find(:salable).length.should == 2

And it does.

Similar to rake task dependencies, you can chain workers together like this:

  factory_worker :first do
    puts "I am first"
  end

  factory_worker :second => :first do
    puts "I am second"
  end

  factory_worker :third => :second do
    puts "I am third"
  end

If you call ‘worker :third’, it should output:

  I am first
  I am second
  I am third

You can also chain workers like this:

  factory_worker :several => [ :first, :second ]

and even add dependencies to the chain in further statements

  factory_worker :several => [ :third ]