factory_girl 4.3.0 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6276447e1d14327c827a7b14fe08b3bbc729d07b
-  data.tar.gz: d8eac964100d437c88ad82ad217a267285ff7461
+  metadata.gz: b01f71363317939e019ac18363d51ce2b2caa9f0
+  data.tar.gz: cb128a3c6ade6aa7d1222fb4f86e6a81504dbc8a
 SHA512:
-  metadata.gz: c25de9107b3313fe1b40d5713f2a2446ce569bb68923eb8a084af42c50a050571e4b98fee61bf534d77bce8b3751cf832b65793d4058dceb8571e369ab4fa7e8
-  data.tar.gz: 8464e558d14c2a3e0f890af7010dc4c85652c56656a6d0d9b2ec948eb0519e9be15fad7ce843f7124c6437d97343d70b2e320d3e7e2df034e7ce5be5f4f5aca6
+  metadata.gz: 3468641fa299f92b03cf869d2b3bfe9f75dce4de90f94b8cc2ebc86e9240177f8e514bfcf5ad44f99e17042112f1eb587dd2256df3c8606e8791d6580a818a2b
+  data.tar.gz: ffc2c949b1e3e344ad56a0a6609203d33c2464c20888a1aca53ca95530dcab8d74dc4d712a3b54fee55d94682422081782b8638c47a62e8f4c18a9238c43d999

data/.travis.yml

@@ -1,6 +1,7 @@
 rvm:
   - 1.9.3
   - 2.0.0
+  - 2.1.0
   - jruby-19mode
 before_install:
   - gem update --system

data/GETTING_STARTED.md

@@ -16,7 +16,7 @@ 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
@@ -25,40 +25,70 @@ export JRUBY_OPTS=--1.9
 
 Once your Gemfile is updated, you'll want to update your bundle.
 
-Using Without Bundler
----------------------
-
-If you're not using Bundler, be sure to have the gem installed and call:
+Configure your test suite
+-------------------------
 
 ```ruby
-require 'factory_girl'
-```
+# rspec
+RSpec.configure do |config|
+  config.include FactoryGirl::Syntax::Methods
+end
 
-Once required, assuming you have a directory structure of `spec/factories` or
-`test/factories`, all you'll need to do is run
+# Test::Unit
+class Test::Unit::TestCase
+  include FactoryGirl::Syntax::Methods
+end
 
-```ruby
-FactoryGirl.find_definitions
+# Cucumber
+World(FactoryGirl::Syntax::Methods)
+
+# Spinach
+class Spinach::FeatureSteps
+  include FactoryGirl::Syntax::Methods
+end
+
+# 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
 ```
 
-If you're using a separate directory structure for your factories, you can
-change the definition file paths before trying to find definitions:
+If you do not include `FactoryGirl::Syntax::Methods` in your test suite, then all factory_girl methods will need to be prefaced with `FactoryGirl`.
+
+Linting Factories
+-----------------
+
+factory_girl allows for linting known factories:
 
 ```ruby
-FactoryGirl.definition_file_paths = %w(custom_factories_directory)
-FactoryGirl.find_definitions
+FactoryGirl.lint
 ```
 
-If you don't have a separate directory of factories and would like to define
-them inline, that's possible as well:
+`FactoryGirl.lint` builds each factory and subsequently calls `#valid?` on it
+(if `#valid?` is defined); if any calls to `#valid?` return `false`,
+`FactoryGirl::InvalidFactoryError` is raised with a list of the offending
+factories. Recommended usage of `FactoryGirl.lint` is to invoke this once
+before the test suite is run.
+
+With RSpec:
 
 ```ruby
-require 'factory_girl'
+# spec/support/factory_girl.rb
+RSpec.configure do |config|
+  # additional factory_girl configuration
 
-FactoryGirl.define do
-  factory :user do
-    name 'John Doe'
-    date_of_birth { 21.years.ago }
+  config.before(:suite) do
+    FactoryGirl.lint
   end
 end
 ```
@@ -105,19 +135,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,55 +156,11 @@ 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
 ---------------
 
@@ -192,24 +178,6 @@ 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:
-
-```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)
-end
-```
-
 Aliases
 -------
 
@@ -250,7 +218,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"
 ```
 
@@ -274,7 +242,7 @@ factory :user do
   end
 end
 
-FactoryGirl.create(:user, upcased: true).name
+create(:user, upcased: true).name
 #=> "JOHN DOE - ROCKSTAR"
 ```
 
@@ -282,8 +250,8 @@ 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.
 
-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 ignored 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.
 
@@ -312,12 +280,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 +299,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
 ```
@@ -375,7 +343,7 @@ FactoryGirl.define do
       # 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,9 +353,9 @@ 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
@@ -404,7 +372,7 @@ factory :post do
   end
 end
 
-approved_post = FactoryGirl.create(:approved_post)
+approved_post = create(:approved_post)
 approved_post.title    # => "A title"
 approved_post.approved # => true
 ```
@@ -432,7 +400,7 @@ 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
 definition block, and values in a sequence are generated by calling
-FactoryGirl.generate:
+`generate`:
 
 ```ruby
 # Defines a new sequence
@@ -442,10 +410,10 @@ FactoryGirl.define do
   end
 end
 
-FactoryGirl.generate :email
+generate :email
 # => "person1@example.com"
 
-FactoryGirl.generate :email
+generate :email
 # => "person2@example.com"
 ```
 
@@ -470,7 +438,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 +446,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 +462,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.generate(: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 +481,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
 ```
 
@@ -617,7 +585,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 +602,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 +621,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 +640,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,7 +661,7 @@ factory :post do
 end
 
 # creates an admin user with name "John Doe"
-FactoryGirl.create(:post).author
+create(:post).author
 ```
 
 Finally, traits can be used within other traits to mix in their attributes.
@@ -752,7 +720,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.
 
@@ -771,8 +739,8 @@ To override callbacks for all factories, define them within the
 
 ```ruby
 FactoryGirl.define do
-  after(:build) {|object| puts "Built #{object}" }
-  after(:create) {|object| AuditLog.create(attrs: object.attributes) }
+  after(:build) { |object| puts "Built #{object}" }
+  after(:create) { |object| AuditLog.create(attrs: object.attributes) }
 
   factory :user do
     name "John Doe"
@@ -797,7 +765,7 @@ FactoryGirl.define do
   end
 end
 
-FactoryGirl.create(:user) # creates the user and confirms it
+create(:user) # creates the user and confirms it
 ```
 
 Modifying factories
@@ -812,7 +780,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
@@ -857,22 +825,22 @@ 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)
 ```
 
 There's also a set of `*_pair` methods for creating two records at a time:
 
 ```ruby
-built_users   = FactoryGirl.build_pair(:user) # array of two built users
-created_users = FactoryGirl.create_pair(:user) # array of two created users
+built_users   = build_pair(:user) # array of two built users
+created_users = create_pair(:user) # array of two created users
 ```
 
 Custom Construction
@@ -894,7 +862,7 @@ class User
 end
 
 # factories.rb
-sequence(:email) {|n| "person#{n}@example.com" }
+sequence(:email) { |n| "person#{n}@example.com" }
 
 factory :user do
   ignore do
@@ -905,7 +873,7 @@ factory :user do
   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
@@ -981,12 +949,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
@@ -998,7 +966,7 @@ FactoryGirl.define do
   end
 end
 
-FactoryGirl.build(:user)
+build(:user)
 # runs
 user = User.new('value')
 user.name = 'value'
@@ -1081,9 +1049,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
 ```
@@ -1097,7 +1065,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
 ```
 
@@ -1115,7 +1083,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
@@ -1186,7 +1154,7 @@ end
 The error occurs during the run of the test suite:
 
 ```
-Failure/Error: united_states = FactoryGirl.create(:united_states)
+Failure/Error: united_states = create(:united_states)
 ActiveRecord::AssociationTypeMismatch:
   LocationGroup(#70251250797320) expected, got LocationGroup(#70251200725840)
 ```
@@ -1199,3 +1167,41 @@ 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
+```