thoughtbot--factory_bot/README.textile

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":mailto: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":http://github.com/thoughtbot/factory_girl/tree/master "Clone":git://github.com/thoughtbot/factory_girl.git

Gem: <pre>gem install thoughtbot-factory_girl --source http://gems.github.com</pre>

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

factory_girl will automatically load factory definitions if you place your them in 'test/factories.rb', 'spec/factories.rb', or in individual files underneath the 'test/factories' and 'spec/factories' directories.

factory_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><code># Same as Factory.create :user:
user = Factory :user
</pre></code>

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><code># Build a User instance and override the first_name property
user = Factory.build(:user, :first_name => 'Joe')
user.first_name
# => "Joe"
</code></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:

h2. More Information

"Our blog":http://giantrobots.thoughtbot.com

"factory_girl rdoc":http://dev.thoughtbot.com/factory_girl

"Mailing list":http://groups.google.com/group/factory_girl

"factory_girl tickets":http://thoughtbot.lighthouseapp.com/projects/14354-factory_girl

h2. Contributing

Please read the contribution guidelines before submitting patches or pull requests.