factory_girl 4.2.0 → 4.8.1

data/GETTING_STARTED.md

@@ -16,53 +16,91 @@ If you're *not* using Rails, you'll just have to change the required version of
 gem "factory_girl", "~> 4.0"
 ```
 
-JRuby users: FactoryGirl works with JRuby starting with 1.6.7.2 (latest stable, as per July 2012).
+JRuby users: factory_girl works with JRuby starting with 1.6.7.2 (latest stable, as per July 2012).
 JRuby has to be used in 1.9 mode, for that, use JRUBY_OPTS environment variable:
 
-```
+```bash
 export JRUBY_OPTS=--1.9
 ```
 
 Once your Gemfile is updated, you'll want to update your bundle.
 
-Using Without Bundler
----------------------
+Configure your test suite
+-------------------------
 
-If you're not using Bundler, be sure to have the gem installed and call:
+# RSpec
 
+```ruby
+# spec/support/factory_girl.rb
+RSpec.configure do |config|
+  config.include FactoryGirl::Syntax::Methods
+end
+
+# RSpec without Rails
+RSpec.configure do |config|
+  config.include FactoryGirl::Syntax::Methods
+
+  config.before(:suite) do
+    FactoryGirl.find_definitions
+  end
+end
 ```
-require 'factory_girl'
+
+Remember to require the above file in your rails_helper since the support folder isn't eagerly loaded
+
+```ruby
+require 'support/factory_girl'
 ```
 
-Once required, assuming you have a directory structure of `spec/factories` or
-`test/factories`, all you'll need to do is run
+# Test::Unit
 
 ```ruby
-FactoryGirl.find_definitions
+class Test::Unit::TestCase
+  include FactoryGirl::Syntax::Methods
+end
 ```
 
-If you're using a separate directory structure for your factories, you can
-change the definition file paths before trying to find definitions:
+# Cucumber
 
 ```ruby
-FactoryGirl.definition_file_paths = %w(custom_factories_directory)
-FactoryGirl.find_definitions
+# env.rb (Rails example location - RAILS_ROOT/features/support/env.rb)
+World(FactoryGirl::Syntax::Methods)
 ```
 
-If you don't have a separate directory of factories and would like to define
-them inline, that's possible as well:
+# Spinach
 
 ```ruby
-require 'factory_girl'
+class Spinach::FeatureSteps
+  include FactoryGirl::Syntax::Methods
+end
+```
 
-FactoryGirl.define do
-  factory :user do
-    name 'John Doe'
-    date_of_birth { 21.years.ago }
-  end
+# Minitest
+
+```ruby
+class Minitest::Unit::TestCase
+  include FactoryGirl::Syntax::Methods
 end
 ```
 
+# Minitest::Spec
+
+```ruby
+class Minitest::Spec
+  include FactoryGirl::Syntax::Methods
+end
+```
+
+# minitest-rails
+
+```ruby
+class ActiveSupport::TestCase
+  include FactoryGirl::Syntax::Methods
+end
+```
+
+If you do not include `FactoryGirl::Syntax::Methods` in your test suite, then all factory_girl methods will need to be prefaced with `FactoryGirl`.
+
 Defining factories
 ------------------
 
@@ -90,8 +128,9 @@ It is highly recommended that you have one factory for each class that provides
 
 Attempting to define multiple factories with the same name will raise an error.
 
-Factories can be defined anywhere, but will be automatically loaded if they
-are defined in files at the following locations:
+Factories can be defined anywhere, but will be automatically loaded after
+calling `FactoryGirl.find_definitions` if factories are defined in files at the
+following locations:
 
     test/factories.rb
     spec/factories.rb
@@ -105,19 +144,19 @@ factory\_girl supports several different build strategies: build, create, attrib
 
 ```ruby
 # Returns a User instance that's not saved
-user = FactoryGirl.build(:user)
+user = build(:user)
 
 # Returns a saved User instance
-user = FactoryGirl.create(:user)
+user = create(:user)
 
 # Returns a hash of attributes that can be used to build a User instance
-attrs = FactoryGirl.attributes_for(:user)
+attrs = attributes_for(:user)
 
 # Returns an object with all defined attributes stubbed out
-stub = FactoryGirl.build_stubbed(:user)
+stub = build_stubbed(:user)
 
 # Passing a block to any of the methods above will yield the return object
-FactoryGirl.create(:user) do |user|
+create(:user) do |user|
   user.posts.create(attributes_for(:post))
 end
 ```
@@ -126,62 +165,18 @@ No matter which strategy is used, it's possible to override the defined attribut
 
 ```ruby
 # Build a User instance and override the first_name property
-user = FactoryGirl.build(:user, first_name: "Joe")
+user = build(:user, first_name: "Joe")
 user.first_name
 # => "Joe"
 ```
 
-If repeating "FactoryGirl" is too verbose for you, you can mix the syntax methods in:
-
-```ruby
-# rspec
-RSpec.configure do |config|
-  config.include FactoryGirl::Syntax::Methods
-end
-
-# Test::Unit
-class Test::Unit::TestCase
-  include FactoryGirl::Syntax::Methods
-end
-
-# Cucumber
-World(FactoryGirl::Syntax::Methods)
-
-# MiniTest
-class MiniTest::Unit::TestCase
-  include FactoryGirl::Syntax::Methods
-end
-
-# MiniTest::Spec
-class MiniTest::Spec
-  include FactoryGirl::Syntax::Methods
-end
-
-# minitest-rails
-class MiniTest::Rails::ActiveSupport::TestCase
-  include FactoryGirl::Syntax::Methods
-end
-```
-
-This allows you to use the core set of syntax methods (`build`,
-`build_stubbed`, `create`, `attributes_for`, and their `*_list` counterparts)
-without having to call them on FactoryGirl directly:
-
-```ruby
-describe User, "#full_name" do
-  subject { create(:user, first_name: "John", last_name: "Doe") }
-
-  its(:full_name) { should eq "John Doe" }
-end
-```
-
-Lazy Attributes
----------------
+Dynamic 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
+time an instance is generated. These "dynamic" attributes can be added by passing a
 block instead of a parameter:
 
 ```ruby
@@ -192,28 +187,18 @@ factory :user do
 end
 ```
 
-In addition to running other methods dynamically, you can use FactoryGirl's
-syntax methods (like `build`, `create`, and `generate`) within dynamic
-attributes without having to prefix the call with `FactoryGirl.`. This allows
-you to do:
+Because of the block syntax in Ruby, defining attributes as `Hash`es (for
+serialized/JSON columns, for example) requires two sets of curly brackets:
 
 ```ruby
-sequence(:random_string) {|n| LoremIpsum.generate }
-
-factory :post do
-  title { generate(:random_string) } # instead of FactoryGirl.generate(:random_string)
-end
-
-factory :comment do
-  post
-  body { generate(:random_string) }  # instead of FactoryGirl.generate(:random_string)
+factory :program do
+  configuration { { auto_resolve: false, auto_define: true } }
 end
 ```
 
 Aliases
 -------
-
-Aliases allow you to use named associations more easily.
+factory_girl allows you to define aliases to existing factories to make them easier to re-use. This could come in handy when, for example, your Post object has an author attribute that actually refers to an instance of a User class. While normally factory_girl can infer the factory name from the association name, in this case it will look for a author factory in vain. So, alias your user factory so it can be used under alias names.
 
 ```ruby
 factory :user, aliases: [:author, :commenter] do
@@ -241,7 +226,8 @@ end
 Dependent Attributes
 --------------------
 
-Attributes can be based on the values of other attributes using the evaluator that is yielded to lazy attribute blocks:
+Attributes can be based on the values of other attributes using the evaluator
+that is yielded to dynamic attribute blocks:
 
 ```ruby
 factory :user do
@@ -250,7 +236,7 @@ factory :user do
   email { "#{first_name}.#{last_name}@example.com".downcase }
 end
 
-FactoryGirl.create(:user, last_name: "Doe").email
+create(:user, last_name: "Doe").email
 # => "joe.doe@example.com"
 ```
 
@@ -261,7 +247,7 @@ There may be times where your code can be DRYed up by passing in transient attri
 
 ```ruby
 factory :user do
-  ignore do
+  transient do
     rockstar true
     upcased  false
   end
@@ -274,18 +260,70 @@ factory :user do
   end
 end
 
-FactoryGirl.create(:user, upcased: true).name
+create(:user, upcased: true).name
 #=> "JOHN DOE - ROCKSTAR"
 ```
 
-Static and dynamic attributes can be ignored. Ignored attributes will be ignored
-within attributes\_for and won't be set on the model, even if the attribute
-exists or you attempt to override it.
+Static and dynamic attributes can be created as transient attributes. Transient
+attributes will be ignored within attributes\_for and won't be set on the model,
+even if the attribute exists or you attempt to override it.
 
-Within FactoryGirl's dynamic attributes, you can access ignored attributes as
-you would expect. If you need to access the evaluator in a FactoryGirl callback,
+Within factory_girl's dynamic attributes, you can access transient attributes as
+you would expect. If you need to access the evaluator in a factory_girl callback,
 you'll need to declare a second block argument (for the evaluator) and access
-ignored attributes from there.
+transient attributes from there.
+
+Method Name / Reserved Word Attributes
+-------------------------------
+
+If your attributes conflict with existing methods or reserved words you can define them with `add_attribute`.
+
+```ruby
+factory :dna do
+  add_attribute(:sequence) { 'GATTACA' }
+end
+
+factory :payment do
+  add_attribute(:method) { 'paypal' }
+end
+
+```
+
+Inheritance
+-----------
+
+You can easily create multiple factories for the same class without repeating common attributes by nesting factories:
+
+```ruby
+factory :post do
+  title "A title"
+
+  factory :approved_post do
+    approved true
+  end
+end
+
+approved_post = create(:approved_post)
+approved_post.title    # => "A title"
+approved_post.approved # => true
+```
+
+You can also assign the parent explicitly:
+
+```ruby
+factory :post do
+  title "A title"
+end
+
+factory :approved_post, parent: :post do
+  approved true
+end
+```
+
+As mentioned above, it's good practice to define a basic factory for each class
+with only the attributes required to create it. Then, create more specific
+factories that inherit from this basic parent. Factory definitions are still
+code, so keep them DRY.
 
 Associations
 ------------
@@ -312,12 +350,12 @@ The behavior of the association method varies depending on the build strategy us
 
 ```ruby
 # Builds and saves a User and a Post
-post = FactoryGirl.create(:post)
+post = create(:post)
 post.new_record?        # => false
 post.author.new_record? # => false
 
 # Builds and saves a User, and then builds but does not save a Post
-post = FactoryGirl.build(:post)
+post = build(:post)
 post.new_record?        # => true
 post.author.new_record? # => false
 ```
@@ -331,7 +369,7 @@ factory :post do
 end
 
 # Builds a User, and then builds a Post, but does not save either
-post = FactoryGirl.build(:post)
+post = build(:post)
 post.new_record?        # => true
 post.author.new_record? # => true
 ```
@@ -364,18 +402,18 @@ FactoryGirl.define do
 
     # user_with_posts will create post data after the user has been created
     factory :user_with_posts do
-      # posts_count is declared as an ignored attribute and available in
+      # posts_count is declared as a transient attribute and available in
       # attributes on the factory, as well as the callback via the evaluator
-      ignore do
+      transient do
         posts_count 5
       end
 
       # the after(:create) yields two values; the user instance itself and the
-      # evaluator, which stores all values from the factory, including ignored
+      # evaluator, which stores all values from the factory, including transient
       # attributes; `create_list`'s second argument is the number of records
       # to create and we make sure the user is associated properly to the post
       after(:create) do |user, evaluator|
-        FactoryGirl.create_list(:post, evaluator.posts_count, user: user)
+        create_list(:post, evaluator.posts_count, user: user)
       end
     end
   end
@@ -385,54 +423,69 @@ end
 This allows us to do:
 
 ```ruby
-FactoryGirl.create(:user).posts.length # 0
-FactoryGirl.create(:user_with_posts).posts.length # 5
-FactoryGirl.create(:user_with_posts, posts_count: 15).posts.length # 15
+create(:user).posts.length # 0
+create(:user_with_posts).posts.length # 5
+create(:user_with_posts, posts_count: 15).posts.length # 15
 ```
 
-Inheritance
------------
+Generating data for a `has_and_belongs_to_many` relationship is very similar
+to the above `has_many` relationship, with a small change, you need to pass an
+array of objects to the model's pluralized attribute name rather than a single
+object to the singular version of the attribute name.
 
-You can easily create multiple factories for the same class without repeating common attributes by nesting factories:
+Here's an example with two models that are related via
+ `has_and_belongs_to_many`:
 
 ```ruby
-factory :post do
-  title "A title"
+FactoryGirl.define do
 
-  factory :approved_post do
-    approved true
+  # language factory with a `belongs_to` association for the profile
+  factory :language do
+    title "Through the Looking Glass"
+    profile
   end
-end
 
-approved_post = FactoryGirl.create(:approved_post)
-approved_post.title    # => "A title"
-approved_post.approved # => true
-```
-
-You can also assign the parent explicitly:
+  # profile factory without associated languages
+  factory :profile do
+    name "John Doe"
 
-```ruby
-factory :post do
-  title "A title"
-end
+    # profile_with_languages will create language data after the profile has
+    # been created
+    factory :profile_with_languages do
+      # languages_count is declared as an ignored attribute and available in
+      # attributes on the factory, as well as the callback via the evaluator
+      transient do
+        languages_count 5
+      end
 
-factory :approved_post, parent: :post do
-  approved true
+      # the after(:create) yields two values; the profile instance itself and
+      # the evaluator, which stores all values from the factory, including
+      # ignored attributes; `create_list`'s second argument is the number of
+      # records to create and we make sure the profile is associated properly
+      # to the language
+      after(:create) do |profile, evaluator|
+        create_list(:language, evaluator.languages_count, profiles: [profile])
+      end
+    end
+  end
 end
 ```
 
-As mentioned above, it's good practice to define a basic factory for each class
-with only the attributes required to create it. Then, create more specific
-factories that inherit from this basic parent. Factory definitions are still
-code, so keep them DRY.
+This allows us to do:
+
+```ruby
+create(:profile).languages.length # 0
+create(:profile_with_languages).languages.length # 5
+create(:profile_with_languages, languages_count: 15).languages.length # 15
+```
 
 Sequences
 ---------
 
 Unique values in a specific format (for example, e-mail addresses) can be
-generated using sequences. Sequences are defined by calling sequence in a
+generated using sequences. Sequences are defined by calling `sequence` in a
 definition block, and values in a sequence are generated by calling
-FactoryGirl.generate:
+`generate`:
 
 ```ruby
 # Defines a new sequence
@@ -442,26 +495,26 @@ FactoryGirl.define do
   end
 end
 
-FactoryGirl.generate :email
+generate :email
 # => "person1@example.com"
 
-FactoryGirl.generate :email
+generate :email
 # => "person2@example.com"
 ```
 
-Sequences can be used as attributes:
+Sequences can be used in dynamic attributes:
 
 ```ruby
-factory :user do
-  email
+factory :invite do
+  invitee { generate(:email) }
 end
 ```
 
-Or in lazy attributes:
+Or as implicit attributes:
 
 ```ruby
-factory :invite do
-  invitee { generate(:email) }
+factory :user do
+  email # Same as `email { generate(:email) }`
 end
 ```
 
@@ -470,7 +523,7 @@ a particular factory:
 
 ```ruby
 factory :user do
-  sequence(:email) {|n| "person#{n}@example.com" }
+  sequence(:email) { |n| "person#{n}@example.com" }
 end
 ```
 
@@ -478,7 +531,7 @@ You can also override the initial value:
 
 ```ruby
 factory :user do
-  sequence(:email, 1000) {|n| "person#{n}@example.com" }
+  sequence(:email, 1000) { |n| "person#{n}@example.com" }
 end
 ```
 
@@ -494,18 +547,18 @@ Sequences can also have aliases. The sequence aliases share the same counter:
 
 ```ruby
 factory :user do
-  sequence(:email, 1000, aliases: [:sender, :receiver]) {|n| "person#{n}@example.com" }
+  sequence(:email, 1000, aliases: [:sender, :receiver]) { |n| "person#{n}@example.com" }
 end
 
 # will increase value counter for :email which is shared by :sender and :receiver
-FactoryGirl.next(:sender)
+generate(:sender)
 ```
 
 Define aliases and use default value (1) for the counter
 
 ```ruby
 factory :user do
-  sequence(:email, aliases: [:sender, :receiver]) {|n| "person#{n}@example.com" }
+  sequence(:email, aliases: [:sender, :receiver]) { |n| "person#{n}@example.com" }
 end
 ```
 
@@ -513,7 +566,7 @@ Setting the value:
 
 ```ruby
 factory :user do
-  sequence(:email, 'a', aliases: [:sender, :receiver]) {|n| "person#{n}@example.com" }
+  sequence(:email, 'a', aliases: [:sender, :receiver]) { |n| "person#{n}@example.com" }
 end
 ```
 
@@ -563,7 +616,7 @@ Traits can be used as attributes:
 factory :week_long_published_story_with_title, parent: :story do
   published
   week_long_publishing
-  title { "Publishing that was started at {start_at}" }
+  title { "Publishing that was started at #{start_at}" }
 end
 ```
 
@@ -617,7 +670,7 @@ factory :user do
 end
 ```
 
-Traits can also be passed in as a list of symbols when you construct an instance from FactoryGirl.
+Traits can also be passed in as a list of symbols when you construct an instance from factory_girl.
 
 ```ruby
 factory :user do
@@ -634,7 +687,7 @@ factory :user do
 end
 
 # creates an admin user with gender "Male" and name "Jon Snow"
-FactoryGirl.create(:user, :admin, :male, name: "Jon Snow")
+create(:user, :admin, :male, name: "Jon Snow")
 ```
 
 This ability works with `build`, `build_stubbed`, `attributes_for`, and `create`.
@@ -653,7 +706,7 @@ factory :user do
 end
 
 # creates 3 admin users with gender "Male" and name "Jon Snow"
-FactoryGirl.create_list(:user, 3, :admin, :male, name: "Jon Snow")
+create_list(:user, 3, :admin, :male, name: "Jon Snow")
 ```
 
 Traits can be used with associations easily too:
@@ -672,7 +725,7 @@ factory :post do
 end
 
 # creates an admin user with name "John Doe"
-FactoryGirl.create(:post).user
+create(:post).user
 ```
 
 When you're using association names that're different than the factory:
@@ -693,8 +746,42 @@ factory :post do
 end
 
 # creates an admin user with name "John Doe"
-FactoryGirl.create(:post).author
+create(:post).author
+```
+
+Traits can be used within other traits to mix in their attributes.
+
+```ruby
+factory :order do
+  trait :completed do
+    completed_at { 3.days.ago }
+  end
+
+  trait :refunded do
+    completed
+    refunded_at { 1.day.ago }
+  end
+end
 ```
+
+Finally, traits can accept transient attributes.
+
+```ruby
+factory :invoice do
+  trait :with_amount do
+    transient do
+      amount 1
+    end
+
+    after(:create) do |invoice, evaluator|
+      create :line_item, invoice: invoice, amount: evaluator.amount
+    end
+  end
+end
+
+create :invoice, :with_amount, amount: 2
+```
+
 Callbacks
 ---------
 
@@ -734,7 +821,7 @@ factory :user do
 end
 ```
 
-Calling FactoryGirl.create will invoke both `after_build` and `after_create` callbacks.
+Calling `create` will invoke both `after_build` and `after_create` callbacks.
 
 Also, like standard attributes, child factories will inherit (and can also define) callbacks from their parent factory.
 
@@ -748,6 +835,40 @@ factory :user do
 end
 ```
 
+To override callbacks for all factories, define them within the
+`FactoryGirl.define` block:
+
+```ruby
+FactoryGirl.define do
+  after(:build) { |object| puts "Built #{object}" }
+  after(:create) { |object| AuditLog.create(attrs: object.attributes) }
+
+  factory :user do
+    name "John Doe"
+  end
+end
+```
+
+You can also call callbacks that rely on `Symbol#to_proc`:
+
+```ruby
+# app/models/user.rb
+class User < ActiveRecord::Base
+  def confirm!
+    # confirm the user account
+  end
+end
+
+# spec/factories.rb
+FactoryGirl.define do
+  factory :user do
+    after :create, &:confirm!
+  end
+end
+
+create(:user) # creates the user and confirms it
+```
+
 Modifying factories
 -------------------
 
@@ -760,7 +881,7 @@ If a gem were to give you a User factory:
 FactoryGirl.define do
   factory :user do
     full_name "John Doe"
-    sequence(:username) {|n| "user#{n}" }
+    sequence(:username) { |n| "user#{n}" }
     password "password"
   end
 end
@@ -805,15 +926,108 @@ Building or Creating Multiple Records
 Sometimes, you'll want to create or build multiple instances of a factory at once.
 
 ```ruby
-built_users   = FactoryGirl.build_list(:user, 25)
-created_users = FactoryGirl.create_list(:user, 25)
+built_users   = build_list(:user, 25)
+created_users = create_list(:user, 25)
 ```
 
 These methods will build or create a specific amount of factories and return them as an array.
 To set the attributes for each of the factories, you can pass in a hash as you normally would.
 
 ```ruby
-twenty_year_olds = FactoryGirl.build_list(:user, 25, date_of_birth: 20.years.ago)
+twenty_year_olds = build_list(:user, 25, date_of_birth: 20.years.ago)
+```
+
+`build_stubbed_list` will give you fully stubbed out instances:
+
+```ruby
+stubbed_users = build_stubbed_list(:user, 25) # array of stubbed users
+```
+
+There's also a set of `*_pair` methods for creating two records at a time:
+
+```ruby
+built_users   = build_pair(:user) # array of two built users
+created_users = create_pair(:user) # array of two created users
+```
+
+If you need multiple attribute hashes, `attributes_for_list` will generate them:
+
+```ruby
+users_attrs = attributes_for_list(:user, 25) # array of attribute hashes
+```
+
+Linting Factories
+-----------------
+
+factory_girl allows for linting known factories:
+
+```ruby
+FactoryGirl.lint
+```
+
+`FactoryGirl.lint` creates each factory and catches any exceptions raised
+during the creation process. `FactoryGirl::InvalidFactoryError` is raised with
+a list of factories (and corresponding exceptions) for factories which could
+not be created.
+
+Recommended usage of `FactoryGirl.lint`
+is to run this in a task
+before your test suite is executed.
+Running it in a `before(:suite)`,
+will negatively impact the performance
+of your tests
+when running single tests.
+
+Example Rake task:
+
+```ruby
+# lib/tasks/factory_girl.rake
+namespace :factory_girl do
+  desc "Verify that all FactoryGirl factories are valid"
+  task lint: :environment do
+    if Rails.env.test?
+      begin
+        DatabaseCleaner.start
+        FactoryGirl.lint
+      ensure
+        DatabaseCleaner.clean
+      end
+    else
+      system("bundle exec rake factory_girl:lint RAILS_ENV='test'")
+    end
+  end
+end
+```
+
+After calling `FactoryGirl.lint`, you'll likely want to clear out the
+database, as records will most likely be created. The provided example above
+uses the database_cleaner gem to clear out the database; be sure to add the
+gem to your Gemfile under the appropriate groups.
+
+You can lint factories selectively by passing only factories you want linted:
+
+```ruby
+factories_to_lint = FactoryGirl.factories.reject do |factory|
+  factory.name =~ /^old_/
+end
+
+FactoryGirl.lint factories_to_lint
+```
+
+This would lint all factories that aren't prefixed with `old_`.
+
+Traits can also be linted. This option verifies that each
+and every trait of a factory generates a valid object on its own.
+This is turned on by passing `traits: true` to the `lint` method:
+
+```ruby
+FactoryGirl.lint traits: true
+```
+
+This can also be combined with other arguments:
+
+```ruby
+FactoryGirl.lint factories_to_lint, traits: true
 ```
 
 Custom Construction
@@ -835,26 +1049,21 @@ class User
 end
 
 # factories.rb
-sequence(:name) {|n| "person#{n}@example.com" }
+sequence(:email) { |n| "person#{n}@example.com" }
 
 factory :user do
-  ignore do
-    name "Jane Doe"
-  end
-
+  name "Jane Doe"
   email
+
   initialize_with { new(name) }
 end
 
-FactoryGirl.build(:user).name # Jane Doe
+build(:user).name # Jane Doe
 ```
 
-Notice that I ignored the `name` attribute. If you don't want attributes
-reassigned after your object has been instantiated, you'll want to `ignore` them.
-
 Although factory_girl is written to work with ActiveRecord out of the box, it
-can also work with any Ruby class. For maximum compatibiltiy with ActiveRecord,
-the default initializer builds all instances by calling new on your build class
+can also work with any Ruby class. For maximum compatibility with ActiveRecord,
+the default initializer builds all instances by calling `new` on your build class
 without any arguments. It then calls attribute writer methods to assign all the
 attribute values. While that works fine for ActiveRecord, it actually doesn't
 work for almost any other Ruby class.
@@ -873,9 +1082,7 @@ For example:
 
 ```ruby
 factory :user do
-  ignore do
-    name "John Doe"
-  end
+  name "John Doe"
 
   initialize_with { User.build_with_name(name) }
 end
@@ -886,7 +1093,7 @@ by calling `attributes`:
 
 ```ruby
 factory :user do
-  ignore do
+  transient do
     comments_count 5
   end
 
@@ -897,7 +1104,7 @@ end
 ```
 
 This will build a hash of all attributes to be passed to `new`. It won't
-include ignored attributes, but everything else defined in the factory will be
+include transient attributes, but everything else defined in the factory will be
 passed (associations, evalued sequences, etc.)
 
 You can define `initialize_with` for all factories by including it in the
@@ -922,12 +1129,12 @@ FactoryGirl.define do
   end
 end
 
-FactoryGirl.build(:user)
+build(:user)
 # runs
 User.new('value')
 ```
 
-This prevents duplicate assignment; in versions of FactoryGirl before 4.0, it
+This prevents duplicate assignment; in versions of factory_girl before 4.0, it
 would run this:
 
 ```ruby
@@ -939,7 +1146,7 @@ FactoryGirl.define do
   end
 end
 
-FactoryGirl.build(:user)
+build(:user)
 # runs
 user = User.new('value')
 user.name = 'value'
@@ -1022,9 +1229,9 @@ FactoryGirl.register_strategy(:json, JsonStrategy)
 
 FactoryGirl.define do
   factory :user do
-    before(:json)                {|user| do_something_to(user) }
-    after(:json)                 {|user_json| do_something_to(user_json) }
-    callback(:make_json_awesome) {|user_json| do_something_to(user_json) }
+    before(:json)                { |user| do_something_to(user) }
+    after(:json)                 { |user_json| do_something_to(user_json) }
+    callback(:make_json_awesome) { |user_json| do_something_to(user_json) }
   end
 end
 ```
@@ -1038,7 +1245,7 @@ may not always be ideal, you can override that behavior by defining
 
 ```ruby
 factory :different_orm_model do
-  to_create {|instance| instance.persist! }
+  to_create { |instance| instance.persist! }
 end
 ```
 
@@ -1056,7 +1263,7 @@ To override `to_create` for all factories, define it within the
 
 ```ruby
 FactoryGirl.define do
-  to_create {|instance| instance.persist! }
+  to_create { |instance| instance.persist! }
 
 
   factory :user do
@@ -1088,18 +1295,93 @@ throughout your test suite. If you're using RSpec, it's as simple as adding a
 `before(:suite)` and `after(:suite)`:
 
 ```ruby
+factory_girl_results = {}
 config.before(:suite) do
-  @factory_girl_results = {}
   ActiveSupport::Notifications.subscribe("factory_girl.run_factory") do |name, start, finish, id, payload|
     factory_name = payload[:name]
     strategy_name = payload[:strategy]
-    @factory_girl_results[factory_name] ||= {}
-    @factory_girl_results[factory_name][strategy_name] ||= 0
-    @factory_girl_results[factory_name][strategy_name] += 1
+    factory_girl_results[factory_name] ||= {}
+    factory_girl_results[factory_name][strategy_name] ||= 0
+    factory_girl_results[factory_name][strategy_name] += 1
   end
 end
 
 config.after(:suite) do
-  puts @factory_girl_results
+  puts factory_girl_results
+end
+```
+
+Rails Preloaders and RSpec
+--------------------------
+
+When running RSpec with a Rails preloader such as `spring` or `zeus`, it's possible
+to encounter an `ActiveRecord::AssociationTypeMismatch` error when creating a factory
+with associations, as below:
+
+```ruby
+FactoryGirl.define do
+  factory :united_states, class: Location do
+    name 'United States'
+    association :location_group, factory: :north_america
+  end
+
+  factory :north_america, class: LocationGroup do
+    name 'North America'
+  end
+end
+```
+
+The error occurs during the run of the test suite:
+
+```
+Failure/Error: united_states = create(:united_states)
+ActiveRecord::AssociationTypeMismatch:
+  LocationGroup(#70251250797320) expected, got LocationGroup(#70251200725840)
+```
+
+The two possible solutions are to either run the suite without the preloader, or
+to add `FactoryGirl.reload` to the RSpec configuration, like so:
+
+```ruby
+RSpec.configure do |config|
+  config.before(:suite) { FactoryGirl.reload }
+end
+```
+
+Using Without Bundler
+---------------------
+
+If you're not using Bundler, be sure to have the gem installed and call:
+
+```ruby
+require 'factory_girl'
+```
+
+Once required, assuming you have a directory structure of `spec/factories` or
+`test/factories`, all you'll need to do is run
+
+```ruby
+FactoryGirl.find_definitions
+```
+
+If you're using a separate directory structure for your factories, you can
+change the definition file paths before trying to find definitions:
+
+```ruby
+FactoryGirl.definition_file_paths = %w(custom_factories_directory)
+FactoryGirl.find_definitions
+```
+
+If you don't have a separate directory of factories and would like to define
+them inline, that's possible as well:
+
+```ruby
+require 'factory_girl'
+
+FactoryGirl.define do
+  factory :user do
+    name 'John Doe'
+    date_of_birth { 21.years.ago }
+  end
 end
 ```