factory_bot 4.8.2 → 5.2.0

data/GETTING_STARTED.md

@@ -4,16 +4,16 @@ Getting Started
 Update Your Gemfile
 -------------------
 
-If you're using Rails, you'll need to change the required version of `factory_bot_rails`:
+If you're using Rails:
 
 ```ruby
-gem "factory_bot_rails", "~> 4.0"
+gem "factory_bot_rails"
 ```
 
-If you're *not* using Rails, you'll just have to change the required version of `factory_bot`:
+If you're *not* using Rails:
 
 ```ruby
-gem "factory_bot", "~> 4.0"
+gem "factory_bot"
 ```
 
 JRuby users: factory_bot works with JRuby starting with 1.6.7.2 (latest stable, as per July 2012).
@@ -28,15 +28,19 @@ Once your Gemfile is updated, you'll want to update your bundle.
 Configure your test suite
 -------------------------
 
-# RSpec
+### RSpec
+
+If you're using Rails, add the following configuration to `spec/support/factory_bot.rb` and be sure to require that file in `rails_helper.rb`:
 
 ```ruby
-# spec/support/factory_bot.rb
 RSpec.configure do |config|
   config.include FactoryBot::Syntax::Methods
 end
+```
 
-# RSpec without Rails
+If you're *not* using Rails:
+
+```ruby
 RSpec.configure do |config|
   config.include FactoryBot::Syntax::Methods
 
@@ -46,13 +50,7 @@ RSpec.configure do |config|
 end
 ```
 
-Remember to require the above file in your rails_helper since the support folder isn't eagerly loaded
-
-```ruby
-require 'support/factory_bot'
-```
-
-# Test::Unit
+### Test::Unit
 
 ```ruby
 class Test::Unit::TestCase
@@ -60,14 +58,14 @@ class Test::Unit::TestCase
 end
 ```
 
-# Cucumber
+### Cucumber
 
 ```ruby
 # env.rb (Rails example location - RAILS_ROOT/features/support/env.rb)
 World(FactoryBot::Syntax::Methods)
 ```
 
-# Spinach
+### Spinach
 
 ```ruby
 class Spinach::FeatureSteps
@@ -75,7 +73,7 @@ class Spinach::FeatureSteps
 end
 ```
 
-# Minitest
+### Minitest
 
 ```ruby
 class Minitest::Unit::TestCase
@@ -83,7 +81,7 @@ class Minitest::Unit::TestCase
 end
 ```
 
-# Minitest::Spec
+### Minitest::Spec
 
 ```ruby
 class Minitest::Spec
@@ -91,7 +89,7 @@ class Minitest::Spec
 end
 ```
 
-# minitest-rails
+### minitest-rails
 
 ```ruby
 class ActiveSupport::TestCase
@@ -104,23 +102,42 @@ If you do not include `FactoryBot::Syntax::Methods` in your test suite, then all
 Defining factories
 ------------------
 
-Each factory has a name and a set of attributes. The name is used to guess the class of the object by default, but it's possible to explicitly specify it:
+Each factory has a name and a set of attributes. The name is used to guess the class of the object by default:
 
 ```ruby
 # This will guess the User class
 FactoryBot.define do
   factory :user do
-    first_name "John"
-    last_name  "Doe"
-    admin false
+    first_name { "John" }
+    last_name  { "Doe" }
+    admin { false }
   end
+end
+```
 
-  # This will use the User class (Admin would have been guessed)
-  factory :admin, class: User do
-    first_name "Admin"
-    last_name  "User"
-    admin      true
-  end
+It is also possible to explicitly specify the class:
+
+```ruby
+# This will use the User class (otherwise Admin would have been guessed)
+factory :admin, class: User
+```
+
+If the constant is not available
+(if you are using a Rails engine that waits to load models, for example),
+you can also pass a symbol or string,
+which factory_bot will constantize later, once you start building objects:
+
+```ruby
+# It's OK if Doorkeeper::AccessToken isn't loaded yet
+factory :access_token, class: "Doorkeeper::AccessToken"
+```
+
+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
+factory :program do
+  configuration { { auto_resolve: false, auto_define: true } }
 end
 ```
 
@@ -170,40 +187,24 @@ user.first_name
 # => "Joe"
 ```
 
-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 "dynamic" attributes can be added by passing a
-block instead of a parameter:
-
-```ruby
-factory :user do
-  # ...
-  activation_code { User.generate_activation_code }
-  date_of_birth   { 21.years.ago }
-end
-```
+Note that objects created with `build_stubbed` cannot be serialized with
+`Marshal.dump`, since factory_bot defines singleton methods on these objects.
 
-Because of the block syntax in Ruby, defining attributes as `Hash`es (for
-serialized/JSON columns, for example) requires two sets of curly brackets:
+Static Attributes
+------------------
 
-```ruby
-factory :program do
-  configuration { { auto_resolve: false, auto_define: true } }
-end
-```
+Static attributes (without a block) are no longer available in factory\_bot 5.
+You can read more about the decision to remove them in
+[this blog post](https://robots.thoughtbot.com/deprecating-static-attributes-in-factory_bot-4-11).
 
 Aliases
 -------
-factory_bot 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_bot 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.
+factory_bot 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_bot can infer the factory name from the association name, in this case it will look for an author factory in vain. So, alias your user factory so it can be used under alias names.
 
 ```ruby
 factory :user, aliases: [:author, :commenter] do
-  first_name    "John"
-  last_name     "Doe"
+  first_name { "John" }
+  last_name { "Doe" }
   date_of_birth { 18.years.ago }
 end
 
@@ -211,15 +212,15 @@ factory :post do
   author
   # instead of
   # association :author, factory: :user
-  title "How to read a book effectively"
-  body  "There are five steps involved."
+  title { "How to read a book effectively" }
+  body { "There are five steps involved." }
 end
 
 factory :comment do
   commenter
   # instead of
   # association :commenter, factory: :user
-  body "Great article!"
+  body { "Great article!" }
 end
 ```
 
@@ -231,8 +232,8 @@ that is yielded to dynamic attribute blocks:
 
 ```ruby
 factory :user do
-  first_name "Joe"
-  last_name  "Blow"
+  first_name { "Joe" }
+  last_name  { "Blow" }
   email { "#{first_name}.#{last_name}@example.com".downcase }
 end
 
@@ -248,11 +249,11 @@ There may be times where your code can be DRYed up by passing in transient attri
 ```ruby
 factory :user do
   transient do
-    rockstar true
-    upcased  false
+    rockstar { true }
+    upcased { false }
   end
 
-  name  { "John Doe#{" - Rockstar" if rockstar}" }
+  name { "John Doe#{" - Rockstar" if rockstar}" }
   email { "#{name.downcase}@example.com" }
 
   after(:create) do |user, evaluator|
@@ -264,8 +265,8 @@ create(:user, upcased: true).name
 #=> "JOHN DOE - ROCKSTAR"
 ```
 
-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,
+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 factory_bot's dynamic attributes, you can access transient attributes as
@@ -276,7 +277,7 @@ 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`.
+If your attributes conflict with existing methods or reserved words (all methods in the [DefinitionProxy](https://github.com/thoughtbot/factory_bot/blob/master/lib/factory_bot/definition_proxy.rb) class) you can define them with `add_attribute`.
 
 ```ruby
 factory :dna do
@@ -296,10 +297,10 @@ You can easily create multiple factories for the same class without repeating co
 
 ```ruby
 factory :post do
-  title "A title"
+  title { "A title" }
 
   factory :approved_post do
-    approved true
+    approved { true }
   end
 end
 
@@ -312,11 +313,11 @@ You can also assign the parent explicitly:
 
 ```ruby
 factory :post do
-  title "A title"
+  title { "A title" }
 end
 
 factory :approved_post, parent: :post do
-  approved true
+  approved { true }
 end
 ```
 
@@ -346,9 +347,35 @@ factory :post do
 end
 ```
 
-The behavior of the association method varies depending on the build strategy used for the parent object.
+In factory\_bot 5, associations default to using the same build strategy as
+their parent object:
+
+```ruby
+FactoryBot.define do
+  factory :author
+
+  factory :post do
+    author
+  end
+end
+
+post = build(:post)
+post.new_record?        # => true
+post.author.new_record? # => true
+
+post = create(:post)
+post.new_record?        # => false
+post.author.new_record? # => false
+```
+
+This is different than the default behavior for previous versions of
+factory\_bot, where the association strategy would not always match the strategy
+of the parent object. If you want to continue using the old behavior, you can
+set the `use_parent_strategy` configuration option to `false`.
 
 ```ruby
+FactoryBot.use_parent_strategy = false
+
 # Builds and saves a User and a Post
 post = create(:post)
 post.new_record?        # => false
@@ -360,9 +387,11 @@ post.new_record?        # => true
 post.author.new_record? # => false
 ```
 
-To not save the associated object, specify strategy: :build in the factory:
+To not save the associated object, specify `strategy: :build` in the factory:
 
 ```ruby
+FactoryBot.use_parent_strategy = false
+
 factory :post do
   # ...
   association :author, factory: :user, strategy: :build
@@ -392,20 +421,20 @@ FactoryBot.define do
 
   # post factory with a `belongs_to` association for the user
   factory :post do
-    title "Through the Looking Glass"
+    title { "Through the Looking Glass" }
     user
   end
 
   # user factory without associated posts
   factory :user do
-    name "John Doe"
+    name { "John Doe" }
 
     # user_with_posts will create post data after the user has been created
     factory :user_with_posts do
       # posts_count is declared as a transient attribute and available in
       # attributes on the factory, as well as the callback via the evaluator
       transient do
-        posts_count 5
+        posts_count { 5 }
       end
 
       # the after(:create) yields two values; the user instance itself and the
@@ -441,13 +470,13 @@ FactoryBot.define do
 
   # language factory with a `belongs_to` association for the profile
   factory :language do
-    title "Through the Looking Glass"
+    title { "Through the Looking Glass" }
     profile
   end
 
   # profile factory without associated languages
   factory :profile do
-    name "John Doe"
+    name { "John Doe" }
 
     # profile_with_languages will create language data after the profile has
     # been created
@@ -455,7 +484,7 @@ FactoryBot.define 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
+        languages_count { 5 }
       end
 
       # the after(:create) yields two values; the profile instance itself and
@@ -479,6 +508,36 @@ create(:profile_with_languages).languages.length # 5
 create(:profile_with_languages, languages_count: 15).languages.length # 15
 ```
 
+Polymorphic associations can be handled with traits:
+
+```ruby
+FactoryBot.define do
+  factory :video
+  factory :photo
+
+  factory :comment do
+    for_photo # default to the :for_photo trait if none is specified
+
+    trait :for_video do
+      association :commentable, factory: :video
+    end
+
+    trait :for_photo do
+      association :commentable, factory: :photo
+    end
+  end
+end
+```
+
+This allows us to do:
+
+```ruby
+create(:comment)
+create(:comment, :for_video)
+create(:comment, :for_photo)
+```
+
+
 Sequences
 ---------
 
@@ -518,6 +577,9 @@ factory :user do
 end
 ```
 
+Note that defining sequences as implicit attributes will not work if you have a
+factory with the same name as the sequence.
+
 And it's also possible to define an in-line sequence that is only used in
 a particular factory:
 
@@ -572,6 +634,22 @@ end
 
 The value just needs to support the `#next` method. Here the next value will be 'a', then 'b', etc.
 
+Sequences can also be rewound with `FactoryBot.rewind_sequences`:
+
+```ruby
+sequence(:email) {|n| "person#{n}@example.com" }
+
+generate(:email) # "person1@example.com"
+generate(:email) # "person2@example.com"
+generate(:email) # "person3@example.com"
+
+FactoryBot.rewind_sequences
+
+generate(:email) # "person1@example.com"
+```
+
+This rewinds all registered sequences.
+
 Traits
 ------
 
@@ -582,25 +660,25 @@ to any factory.
 factory :user, aliases: [:author]
 
 factory :story do
-  title "My awesome story"
+  title { "My awesome story" }
   author
 
   trait :published do
-    published true
+    published { true }
   end
 
   trait :unpublished do
-    published false
+    published { false }
   end
 
   trait :week_long_publishing do
     start_at { 1.week.ago }
-    end_at   { Time.now }
+    end_at { Time.now }
   end
 
   trait :month_long_publishing do
     start_at { 1.month.ago }
-    end_at   { Time.now }
+    end_at { Time.now }
   end
 
   factory :week_long_published_story,    traits: [:published, :week_long_publishing]
@@ -610,7 +688,7 @@ factory :story do
 end
 ```
 
-Traits can be used as attributes:
+Traits can be used as implicit attributes:
 
 ```ruby
 factory :week_long_published_story_with_title, parent: :story do
@@ -620,28 +698,31 @@ factory :week_long_published_story_with_title, parent: :story do
 end
 ```
 
+Note that defining traits as implicit attributes will not work if you have a
+factory or sequence with the same name as the trait.
+
 Traits that define the same attributes won't raise AttributeDefinitionErrors;
 the trait that defines the attribute latest gets precedence.
 
 ```ruby
 factory :user do
-  name "Friendly User"
+  name { "Friendly User" }
   login { name }
 
   trait :male do
-    name   "John Doe"
-    gender "Male"
+    name { "John Doe" }
+    gender { "Male" }
     login { "#{name} (M)" }
   end
 
   trait :female do
-    name   "Jane Doe"
-    gender "Female"
+    name { "Jane Doe" }
+    gender { "Female" }
     login { "#{name} (F)" }
   end
 
   trait :admin do
-    admin true
+    admin { true }
     login { "admin-#{name}" }
   end
 
@@ -654,18 +735,18 @@ You can also override individual attributes granted by a trait in subclasses.
 
 ```ruby
 factory :user do
-  name "Friendly User"
+  name { "Friendly User" }
   login { name }
 
   trait :male do
-    name   "John Doe"
-    gender "Male"
+    name { "John Doe" }
+    gender { "Male" }
     login { "#{name} (M)" }
   end
 
   factory :brandon do
     male
-    name "Brandon"
+    name { "Brandon" }
   end
 end
 ```
@@ -674,15 +755,15 @@ Traits can also be passed in as a list of symbols when you construct an instance
 
 ```ruby
 factory :user do
-  name "Friendly User"
+  name { "Friendly User" }
 
   trait :male do
-    name   "John Doe"
-    gender "Male"
+    name { "John Doe" }
+    gender { "Male" }
   end
 
   trait :admin do
-    admin true
+    admin { true }
   end
 end
 
@@ -698,10 +779,10 @@ the number of instances to create/build as second parameter, as documented in th
 
 ```ruby
 factory :user do
-  name "Friendly User"
+  name { "Friendly User" }
 
   trait :admin do
-    admin true
+    admin { true }
   end
 end
 
@@ -713,10 +794,10 @@ Traits can be used with associations easily too:
 
 ```ruby
 factory :user do
-  name "Friendly User"
+  name { "Friendly User" }
 
   trait :admin do
-    admin true
+    admin { true }
   end
 end
 
@@ -732,10 +813,10 @@ When you're using association names that're different than the factory:
 
 ```ruby
 factory :user do
-  name "Friendly User"
+  name { "Friendly User" }
 
   trait :admin do
-    admin true
+    admin { true }
   end
 end
 
@@ -770,7 +851,7 @@ Finally, traits can accept transient attributes.
 factory :invoice do
   trait :with_amount do
     transient do
-      amount 1
+      amount { 1 }
     end
 
     after(:create) do |invoice, evaluator|
@@ -844,7 +925,7 @@ FactoryBot.define do
   after(:create) { |object| AuditLog.create(attrs: object.attributes) }
 
   factory :user do
-    name "John Doe"
+    name { "John Doe" }
   end
 end
 ```
@@ -880,9 +961,9 @@ If a gem were to give you a User factory:
 ```ruby
 FactoryBot.define do
   factory :user do
-    full_name "John Doe"
+    full_name { "John Doe" }
     sequence(:username) { |n| "user#{n}" }
-    password "password"
+    password { "password" }
   end
 end
 ```
@@ -892,10 +973,10 @@ Instead of creating a child factory that added additional attributes:
 ```ruby
 FactoryBot.define do
   factory :application_user, parent: :user do
-    full_name     "Jane Doe"
+    full_name { "Jane Doe" }
     date_of_birth { 21.years.ago }
-    gender        "Female"
-    health        90
+    gender { "Female" }
+    health { 90 }
   end
 end
 ```
@@ -905,10 +986,10 @@ You could modify that factory instead.
 ```ruby
 FactoryBot.modify do
   factory :user do
-    full_name     "Jane Doe"
+    full_name { "Jane Doe" }
     date_of_birth { 21.years.ago }
-    gender        "Female"
-    health        90
+    gender { "Female" }
+    health { 90 }
   end
 end
 ```
@@ -937,6 +1018,14 @@ To set the attributes for each of the factories, you can pass in a hash as you n
 twenty_year_olds = build_list(:user, 25, date_of_birth: 20.years.ago)
 ```
 
+In order to set different attributes for each factory, these methods may be passed a block, with the factory and the index as parameters:
+
+```ruby
+twenty_somethings = build_list(:user, 10) do |user, i|
+  user.date_of_birth = (20 + i).years.ago
+end
+```
+
 `build_stubbed_list` will give you fully stubbed out instances:
 
 ```ruby
@@ -986,12 +1075,14 @@ namespace :factory_bot do
   desc "Verify that all FactoryBot factories are valid"
   task lint: :environment do
     if Rails.env.test?
-      DatabaseCleaner.cleaning do
+      conn = ActiveRecord::Base.connection
+      conn.transaction do
         FactoryBot.lint
+        raise ActiveRecord::Rollback
       end
     else
       system("bundle exec rake factory_bot:lint RAILS_ENV='test'")
-      exit $?.exitstatus
+      fail if $?.exitstatus.nonzero?
     end
   end
 end
@@ -999,8 +1090,7 @@ end
 
 After calling `FactoryBot.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.
+uses an sql transaction and rollback to leave the database clean.
 
 You can lint factories selectively by passing only factories you want linted:
 
@@ -1034,6 +1124,13 @@ You can also specify the strategy used for linting:
 FactoryBot.lint strategy: :build
 ```
 
+Verbose linting will include full backtraces for each error, which can be
+helpful for debugging:
+
+```ruby
+FactoryBot.lint verbose: true
+```
+
 Custom Construction
 -------------------
 
@@ -1056,7 +1153,7 @@ end
 sequence(:email) { |n| "person#{n}@example.com" }
 
 factory :user do
-  name "Jane Doe"
+  name { "Jane Doe" }
   email
 
   initialize_with { new(name) }
@@ -1086,7 +1183,7 @@ For example:
 
 ```ruby
 factory :user do
-  name "John Doe"
+  name { "John Doe" }
 
   initialize_with { User.build_with_name(name) }
 end
@@ -1098,7 +1195,7 @@ by calling `attributes`:
 ```ruby
 factory :user do
   transient do
-    comments_count 5
+    comments_count { 5 }
   end
 
   name "John Doe"
@@ -1109,7 +1206,7 @@ end
 
 This will build a hash of all attributes to be passed to `new`. It won't
 include transient attributes, but everything else defined in the factory will be
-passed (associations, evalued sequences, etc.)
+passed (associations, evaluated sequences, etc.)
 
 You can define `initialize_with` for all factories by including it in the
 `FactoryBot.define` block:
@@ -1271,7 +1368,7 @@ FactoryBot.define do
 
 
   factory :user do
-    name "John Doe"
+    name { "John Doe" }
   end
 end
 ```
@@ -1324,13 +1421,13 @@ with associations, as below:
 
 ```ruby
 FactoryBot.define do
-  factory :united_states, class: Location do
-    name 'United States'
+  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'
+  factory :north_america, class: "LocationGroup" do
+    name { 'North America' }
   end
 end
 ```
@@ -1362,7 +1459,7 @@ require 'factory_bot'
 ```
 
 Once required, assuming you have a directory structure of `spec/factories` or
-`test/factories`, all you'll need to do is run
+`test/factories`, all you'll need to do is run:
 
 ```ruby
 FactoryBot.find_definitions
@@ -1384,7 +1481,7 @@ require 'factory_bot'
 
 FactoryBot.define do
   factory :user do
-    name 'John Doe'
+    name { 'John Doe' }
     date_of_birth { 21.years.ago }
   end
 end