thoughtbot--factory_bot/README.textile

h1. factory_girl

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. 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

h2. Contributing

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

h2. Defining factories

<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

# This will define a new factory using the attributes from :user
# and override last_name
Factory.define :guest, :parent => :user do |u|
  u.last_name  'Anonymous'
end</code></pre>

It is recommended that you create a test/factories.rb file and define your
factories there. This file can be included from test_helper or directly from
your test files. Don't forget:
<pre><code>require 'factory_girl'</code></pre>


h2. Lazy Attributes

Most 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 (build, create, or attributes_for) 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. 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. Using factories

<pre><code># Generate a User instance using the default factory strategy,
# that can be speciied with :default_strategy parameter
# (If not specified :create is used)
Factory :user

# Build and save a User instance
Factory.create(:user)

# Build a User instance and override the first_name property
Factory.build(:user, :first_name => 'Joe')

# Return an attributes Hash that can be used to build a User instance
attrs = Factory.attributes_for(:user)

# Rerurn a mock object with all specified attributes stubbed out
mock = Factory.stub(:user)
</code></pre>