h1. factory_girl
Factory Girl is a fixtures replacement with a straightforward definition syntax, support for multiple build strategies (saved instances, unsaved instances, attribute hashes, and mock objects), and support for multiple factories for the same class (user, admin_user, and so on).
Written by "Joe Ferris":jferris@thoughtbot.com.
Thanks to Tammer Saleh, Dan Croak, and Jon Yurek of thoughtbot, inc.
Copyright 2008 Joe Ferris and thoughtbot, inc.
h2. Download
Github: "Page":github.com/thoughtbot/factory_girl/tree/master "Clone":git://github.com/thoughtbot/factory_girl.git
Gem: <pre>gem install thoughtbot-factory_girl —source gems.github.com>
Note: if you install factory_girl using the gem from Github, you‘ll need this in your environment.rb if you want to use Rails 2.1+’s dependency manager:
config.gem "thoughtbot-factory_girl",
:lib => "factory_girl",
:source => "http://gems.github.com"
h2. Defining factories
Each factory has a name and a bunch of attributes. The name is used to guess the class of the object by default, but it‘s possible to excplicitly specify it:
<pre><code># This will guess the User class Factory.define :user do |u|
u.first_name 'John' u.last_name 'Doe' u.admin false
end
# This will use the User class (Admin would have been guessed) Factory.define :admin, :class => User do |u|
u.first_name 'Admin' u.last_name 'User' u.admin true
end
# The same, but using a string instead of class constant Factory.define :admin, :class => ‘user’ do |u|
u.first_name 'Admin' u.last_name 'User' u.admin true
end </code></pre>
Factories can either be defined in test/factories.rb file or in separate files under test/factories or test/spec
h2. Using factories
Factroy girl supports several different build strategies: build, create, attribtues_for and stub:
<pre><code># Returns a User instance that‘s not saved user = Factory.build :user
Returns a saved User instance user = Factory.create :user
Returns a hash of attributes that can be used to build a User instance: attrs = Factory.attributes_for(:user)
Returns a mock object with all defined attributes stubbed out: mock = Factory.stub(:user) </pre></code>
The default is "create" and it‘s used by the Factory shortcut method:
<pre># Same as Factory.create :user: user = Factory :user </pre>
The default strategy can be overriden with the :default_strategy_parameter though:
<pre><code># Now same as Factory.build :user Factory.define :user, :default_strategy => :build do |u|
....
end
user = Factory :user </pre></code>
No matter which startegy is used, it‘s possible to override the attributes by passing a hash:
<pre># Build a User instance and override the first_name property user = Factory.build(:user, :first_name => ‘Joe’) user.first_name # => "Joe" </pre>
h2. Lazy Attributes
Most factory attributes can be added using static values that are evaluated when the factory is defined, but some attributes (such as associations and other attributes that must be dynamically generated) will need values assigned each time an instance is generated. These "lazy" attributes can be added by passing a block instead of a parameter:
<pre><code>Factory.define :user do |u|
# ...
u.activation_code { User.generate_activation_code }
end</code></pre>
h2. Dependent Attributes
Some attributes may need to be generated based on the values of other attributes. This can be done by calling the attribute name on Factory::AttributeProxy, which is yielded to lazy attribute blocks:
<pre><code>Factory.define :user do |u|
u.first_name 'Joe'
u.last_name 'Blow'
u.email {|a| "#{a.first_name}.#{a.last_name}@example.com".downcase }
end
Factory(:user, :last_name => ‘Doe’).email # => "joe.doe@example.com"</code></pre>
h2. Associations
Associated instances can be generated by using the association method when defining a lazy attribute:
<pre><code>Factory.define :post do |p|
# ...
p.author {|author| author.association(:user, :last_name => 'Writely') }
end</code></pre>
When using the association method, the same build strategy will be used for all generated instances:
<pre><code># Builds and saves a User and a Post post = Factory(:post) post.new_record? # => false post.author.new_record # => false
# Builds but does not save a User and a Post Factory.build(:post) post.new_record? # => true post.author.new_record # => true</code></pre>
Because this pattern is so common, a prettier syntax is available for defining associations:
<pre><code># The following definitions are equivilent: Factory.define :post do |p|
p.author {|a| a.association(:user) }
end
Factory.define :post do |p|
p.association :author, :factory => :user
end</code></pre>
If the factory name is the same as the association name, the factory name can be left out.
h2. Inheritance
In case there are several factories for the same class that share common attributes, you can define them in a parent factory and inherit other ones from it. A child factory can override parent attributes and define new ones:
<pre><code> Factory.define :user do |u|
u.first_name 'John' u.last_name 'Doe' u.admin false
end
Factory.define :admin, :parent => :user do |u|
u.admin true
end</code></pre>
Factory.define :guest, :parent => :user do |u|
u.last_name 'Anonymous' u.guest true
end</code></pre>
h2. Sequences
Unique values in a specific format (for example, e-mail addresses) can be generated using sequences. Sequences are defined by calling Factory.sequence, and values in a sequence are generated by calling Factory.next:
<pre><code># Defines a new sequence Factory.sequence :email do |n|
"person#{n}@example.com"
end
Factory.next :email # => "person1@example.com"
Factory.next :email # => "person2@example.com"</code></pre>
Sequences can be used as lazy attributes:
Factory.define :user do |f|
f.email { Factory.next(:email) }
end
And it‘s also possible to define an in-line sequence that is only used in a particular factory:
Factory.define :user do |f|
f.sequence(:username) { |n| "person#{n}" }
end
h2. More Information
"Our blog":giantrobots.thoughtbot.com
"factory_girl rdoc":dev.thoughtbot.com/factory_girl
"Mailing list":groups.google.com/group/factory_girl
h2. Contributing
Please read the contribution guidelines before submitting patches or pull requests.