factory_bot 5.0.2 → 6.2.1

data/GETTING_STARTED.md

@@ -1,8 +1,91 @@
 Getting Started
 ===============
 
-Update Your Gemfile
--------------------
+* [Setup](#setup)
+  + [Update Your Gemfile](#update-your-gemfile)
+  + [Configure your test suite](#configure-your-test-suite)
+    - [RSpec](#rspec)
+    - [Test::Unit](#testunit)
+    - [Cucumber](#cucumber)
+    - [Spinach](#spinach)
+    - [Minitest](#minitest)
+    - [Minitest::Spec](#minitestspec)
+    - [minitest-rails](#minitest-rails)
+* [Defining factories](#defining-factories)
+  + [Factory name and attributes](#factory-name-and-attributes)
+  + [Specifying the class explicitly](#specifying-the-class-explicitly)
+  + [Hash attributes](#hash-attributes)
+  + [Best practices](#best-practices)
+  + [Definition file paths](#definition-file-paths)
+  + [Static Attributes](#static-attributes)
+* [Using factories](#using-factories)
+  + [Build strategies](#build-strategies)
+  + [Attribute overrides](#attribute-overrides)
+  + [`build_stubbed` and `Marshal.dump`](#build_stubbed-and-marshaldump)
+* [Aliases](#aliases)
+* [Dependent Attributes](#dependent-attributes)
+* [Transient Attributes](#transient-attributes)
+  + [With other attributes](#with-other-attributes)
+  + [With `attributes_for`](#with-attributes_for)
+  + [With callbacks](#with-callbacks)
+  + [With associations](#with-associations)
+* [Method Name / Reserved Word Attributes](#method-name--reserved-word-attributes)
+* [Inheritance](#inheritance)
+  + [Nested factories](#nested-factories)
+  + [Assigning parent explicitly](#assigning-parent-explicitly)
+  + [Best practices](#best-practices-1)
+* [Associations](#associations)
+  + [Implicit definition](#implicit-definition)
+  + [Explicit definition](#explicit-definition)
+  + [Inline definition](#inline-definition)
+  + [Specifying the factory](#specifying-the-factory)
+  + [Overriding attributes](#overriding-attributes)
+  + [Association overrides](#association-overrides)
+  + [Build strategies](#build-strategies-1)
+  + [`has_many` associations](#has_many-associations)
+  + [`has_and_belongs_to_many` associations](#has_and_belongs_to_many-associations)
+  + [Polymorphic associations](#polymorphic-associations)
+  + [Interconnected associations](#interconnected-associations)
+* [Sequences](#sequences)
+  + [Global sequences](#global-sequences)
+  + [With dynamic attributes](#with-dynamic-attributes)
+  + [As implicit attributes](#as-implicit-attributes)
+  + [Inline sequences](#inline-sequences)
+  + [Initial value](#initial-value)
+  + [Without a block](#without-a-block)
+  + [Aliases](#aliases-1)
+  + [Rewinding](#rewinding)
+  + [Uniqueness](#uniqueness)
+* [Traits](#traits)
+  + [Defining traits](#defining-traits)
+  + [As implicit attributes](#as-implicit-attributes-1)
+  + [Attribute precedence](#attribute-precedence)
+  + [In child factories](#in-child-factories)
+  + [Using traits](#using-traits)
+  + [With associations](#with-associations-1)
+  + [Traits within traits](#traits-within-traits)
+  + [With transient attributes](#with-transient-attributes)
+  + [Enum traits](#enum-traits)
+* [Callbacks](#callbacks)
+  + [Default callbacks](#default-callbacks)
+  + [Multiple callbacks](#multiple-callbacks)
+  + [Global callbacks](#global-callbacks)
+  + [Symbol#to_proc](#symbolto_proc)
+* [Modifying factories](#modifying-factories)
+* [Building or Creating Multiple Records](#building-or-creating-multiple-records)
+* [Linting Factories](#linting-factories)
+* [Custom Construction](#custom-construction)
+* [Custom Strategies](#custom-strategies)
+* [Custom Callbacks](#custom-callbacks)
+* [Custom Methods to Persist Objects](#custom-methods-to-persist-objects)
+* [ActiveSupport Instrumentation](#activesupport-instrumentation)
+* [Rails Preloaders and RSpec](#rails-preloaders-and-rspec)
+* [Using Without Bundler](#using-without-bundler)
+
+Setup
+-----
+
+### Update Your Gemfile
 
 If you're using Rails:
 
@@ -16,21 +99,13 @@ If you're *not* using Rails:
 gem "factory_bot"
 ```
 
-JRuby users: factory_bot 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.
-
-Configure your test suite
--------------------------
+### Configure your test suite
 
-### RSpec
+#### RSpec
 
-If you're using Rails:
+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
 RSpec.configure do |config|
@@ -50,7 +125,7 @@ RSpec.configure do |config|
 end
 ```
 
-### Test::Unit
+#### Test::Unit
 
 ```ruby
 class Test::Unit::TestCase
@@ -58,14 +133,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
@@ -73,7 +148,7 @@ class Spinach::FeatureSteps
 end
 ```
 
-### Minitest
+#### Minitest
 
 ```ruby
 class Minitest::Unit::TestCase
@@ -81,7 +156,7 @@ class Minitest::Unit::TestCase
 end
 ```
 
-### Minitest::Spec
+#### Minitest::Spec
 
 ```ruby
 class Minitest::Spec
@@ -89,7 +164,7 @@ class Minitest::Spec
 end
 ```
 
-### minitest-rails
+#### minitest-rails
 
 ```ruby
 class ActiveSupport::TestCase
@@ -97,12 +172,16 @@ class ActiveSupport::TestCase
 end
 ```
 
-If you do not include `FactoryBot::Syntax::Methods` in your test suite, then all factory_bot methods will need to be prefaced with `FactoryBot`.
+If you do not include `FactoryBot::Syntax::Methods` in your test suite, then all
+factory\_bot methods will need to be prefaced with `FactoryBot`.
 
 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:
+### Factory name and attributes
+
+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
@@ -115,23 +194,25 @@ FactoryBot.define do
 end
 ```
 
+### Specifying the class explicitly
+
 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
+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:
+You can pass a constant as well, if the constant is available (note that this
+can cause test performance problems in large Rails applications, since
+referring to the constant will cause it to be eagerly loaded).
 
 ```ruby
-# It's OK if Doorkeeper::AccessToken isn't loaded yet
-factory :access_token, class: "Doorkeeper::AccessToken"
+factory :access_token, class: User
 ```
 
+### Hash attributes
+
 Because of the block syntax in Ruby, defining attributes as `Hash`es (for
 serialized/JSON columns, for example) requires two sets of curly brackets:
 
@@ -141,10 +222,19 @@ factory :program do
 end
 ```
 
-It is highly recommended that you have one factory for each class that provides the simplest set of attributes necessary to create an instance of that class. If you're creating ActiveRecord objects, that means that you should only provide attributes that are required through validations and that do not have defaults. Other factories can be created through inheritance to cover common scenarios for each class.
+### Best practices
+
+It is recommended that you have one factory for each class that provides
+the simplest set of attributes necessary to create an instance of that class. If
+you're creating ActiveRecord objects, that means that you should only provide
+attributes that are required through validations and that do not have defaults.
+Other factories can be created through inheritance to cover common scenarios for
+each class.
 
 Attempting to define multiple factories with the same name will raise an error.
 
+### Definition file paths
+
 Factories can be defined anywhere, but will be automatically loaded after
 calling `FactoryBot.find_definitions` if factories are defined in files at the
 following locations:
@@ -154,10 +244,20 @@ following locations:
     test/factories/*.rb
     spec/factories/*.rb
 
+### Static Attributes
+
+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).
+
+
 Using factories
 ---------------
 
-factory\_bot supports several different build strategies: build, create, attributes\_for and build\_stubbed:
+### Build strategies
+
+factory\_bot supports several different build strategies: build, create,
+attributes\_for and build\_stubbed:
 
 ```ruby
 # Returns a User instance that's not saved
@@ -178,7 +278,10 @@ create(:user) do |user|
 end
 ```
 
-No matter which strategy is used, it's possible to override the defined attributes by passing a hash:
+### Attribute overrides
+
+No matter which strategy is used, it's possible to override the defined
+attributes by passing a hash:
 
 ```ruby
 # Build a User instance and override the first_name property
@@ -187,19 +290,20 @@ user.first_name
 # => "Joe"
 ```
 
-Note that objects created with `build_stubbed` cannot be serialized with
-`Marshal.dump`, since factory_bot defines singleton methods on these objects.
-
-Static Attributes
-------------------
+### `build_stubbed` and `Marshal.dump`
 
-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).
+Note that objects created with `build_stubbed` cannot be serialized with
+`Marshal.dump`, since factory\_bot defines singleton methods on these objects.
 
 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 an 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
@@ -209,17 +313,17 @@ factory :user, aliases: [:author, :commenter] do
 end
 
 factory :post do
-  author
-  # instead of
+  # The alias allows us to write author instead of
   # association :author, factory: :user
+  author
   title { "How to read a book effectively" }
   body { "There are five steps involved." }
 end
 
 factory :comment do
-  commenter
-  # instead of
+  # The alias allows us to write commenter instead of
   # association :commenter, factory: :user
+  commenter
   body { "Great article!" }
 end
 ```
@@ -243,36 +347,79 @@ create(:user, last_name: "Doe").email
 
 Transient Attributes
 --------------------
+Transient attributes are attributes only available within the factory definition, and not set on the object being built. This allows for more complex logic inside factories.
 
-There may be times where your code can be DRYed up by passing in transient attributes to factories.
+### With other attributes
+
+There may be times where your code can be DRYed up by passing in transient
+attributes to factories. You can access transient attributes within other
+attributes (see [Dependent Attributes](#dependent-attributes)):
 
 ```ruby
 factory :user do
   transient do
     rockstar { true }
-    upcased { false }
   end
 
   name { "John Doe#{" - Rockstar" if rockstar}" }
-  email { "#{name.downcase}@example.com" }
+end
+
+create(:user).name
+#=> "John Doe - ROCKSTAR"
+
+create(:user, rockstar: false).name
+#=> "John Doe"
+```
+
+### With `attributes_for`
+
+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.
+
+### With callbacks
+
+If you need to access the evaluator in a factory\_bot callback,
+you'll need to declare a second block argument (for the evaluator) and access
+transient attributes from there.
+
+```ruby
+factory :user do
+  transient do
+    upcased { false }
+  end
+
+  name { "John Doe" }
 
   after(:create) do |user, evaluator|
     user.name.upcase! if evaluator.upcased
   end
 end
 
+create(:user).name
+#=> "John Doe"
+
 create(:user, upcased: true).name
-#=> "JOHN DOE - ROCKSTAR"
+#=> "JOHN DOE"
 ```
 
-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.
+### With associations
 
-Within factory_bot's dynamic attributes, you can access transient attributes as
-you would expect. If you need to access the evaluator in a factory_bot callback,
-you'll need to declare a second block argument (for the evaluator) and access
-transient attributes from there.
+Transient [associations](#associations) are not supported in factory\_bot.
+Associations within the transient block will be treated as regular,
+non-transient associations.
+
+If needed, you can generally work around this by building a factory within a
+transient attribute:
+
+```ruby
+factory :post
+
+factory :user do
+  transient do
+    post { build(:post) }
+  end
+end
+```
 
 Method Name / Reserved Word Attributes
 -------------------------------
@@ -293,7 +440,10 @@ end
 Inheritance
 -----------
 
-You can easily create multiple factories for the same class without repeating common attributes by nesting factories:
+### Nested factories
+
+You can easily create multiple factories for the same class without repeating
+common attributes by nesting factories:
 
 ```ruby
 factory :post do
@@ -309,6 +459,8 @@ approved_post.title    # => "A title"
 approved_post.approved # => true
 ```
 
+### Assigning parent explicitly
+
 You can also assign the parent explicitly:
 
 ```ruby
@@ -321,6 +473,8 @@ factory :approved_post, parent: :post do
 end
 ```
 
+### Best practices
+
 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
@@ -329,7 +483,10 @@ code, so keep them DRY.
 Associations
 ------------
 
-It's possible to set up associations within factories. If the factory name is the same as the association name, the factory name can be left out.
+### Implicit definition
+
+It's possible to set up associations within factories. If the factory name is
+the same as the association name, the factory name can be left out.
 
 ```ruby
 factory :post do
@@ -338,15 +495,117 @@ factory :post do
 end
 ```
 
-You can also specify a different factory or override attributes:
+### Explicit definition
+
+You can define associations explicitly. This can be handy especially when
+[Overriding attributes](#overriding-attributes)
+
+```ruby
+factory :post do
+  # ...
+  association :author
+end
+```
+
+### Inline definition
+
+You can also define associations inline within regular attributes,
+but note that the value will be `nil`
+when using the `attributes_for` strategy.
+
+```ruby
+factory :post do
+  # ...
+  author { association :author }
+end
+```
+
+### Specifying the factory
+
+You can specify a different factory (although [Aliases](#aliases) might also
+help you out here).
+
+Implicitly:
+
+```ruby
+factory :post do
+  # ...
+  author factory: :user
+end
+```
+
+Explicitly:
+
+```ruby
+factory :post do
+  # ...
+  association :author, factory: :user
+end
+```
+
+Inline:
+
+```ruby
+factory :post do
+  # ...
+  author { association :user }
+end
+```
+
+### Overriding attributes
+
+You can also override attributes.
+
+Implicitly:
+
+```ruby
+factory :post do
+  # ...
+  author factory: :author, last_name: "Writely"
+end
+```
+
+Explicitly:
+
 
 ```ruby
 factory :post do
   # ...
-  association :author, factory: :user, last_name: "Writely"
+  association :author, last_name: "Writely"
+end
+```
+
+Or inline using attributes from the factory:
+
+```rb
+factory :post do
+  # ...
+  author_last_name { "Writely" }
+  author { association :author, last_name: author_last_name }
+end
+```
+
+### Association overrides
+
+Attribute overrides can be used to link associated objects:
+
+```ruby
+FactoryBot.define do
+  factory :author do
+    name { 'Taylor' }
+  end
+
+  factory :post do
+    author
+  end
 end
+
+eunji = build(:author, name: 'Eunji')
+post = build(:post, author: eunji)
 ```
 
+### Build strategies
+
 In factory\_bot 5, associations default to using the same build strategy as
 their parent object:
 
@@ -387,7 +646,7 @@ 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
@@ -412,27 +671,53 @@ factory :post do
   author strategy: :build    # <<< this does *not* work; causes author_id to be nil
 ```
 
-Generating data for a `has_many` relationship is a bit more involved,
-depending on the amount of flexibility desired, but here's a surefire example
-of generating associated data.
+### `has_many` associations
+
+There are a few ways to generate data for a `has_many` relationship. The
+simplest approach is to write a helper method in plain Ruby to tie together the
+different records:
 
 ```ruby
 FactoryBot.define do
+  factory :post do
+    title { "Through the Looking Glass" }
+    user
+  end
+
+  factory :user do
+    name { "Rachel Sanchez" }
+  end
+end
+
+def user_with_posts(posts_count: 5)
+  FactoryBot.create(:user) do |user|
+    FactoryBot.create_list(:post, posts_count, user: user)
+  end
+end
 
-  # post factory with a `belongs_to` association for the user
+create(:user).posts.length # 0
+user_with_posts.posts.length # 5
+user_with_posts(posts_count: 15).posts.length # 15
+```
+
+If you prefer to keep the object creation fully within factory\_bot, you can
+build the posts in an `after(:create)` callback.
+
+
+```ruby
+FactoryBot.define do
   factory :post do
     title { "Through the Looking Glass" }
     user
   end
 
-  # user factory without associated posts
   factory :user do
     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
+      # posts_count is declared as a transient attribute available in the
+      # callback via the evaluator
       transient do
         posts_count { 5 }
       end
@@ -443,87 +728,142 @@ FactoryBot.define do
       # to create and we make sure the user is associated properly to the post
       after(:create) do |user, evaluator|
         create_list(:post, evaluator.posts_count, user: user)
+
+        # You may need to reload the record here, depending on your application
+        user.reload
       end
     end
   end
 end
-```
 
-This allows us to do:
-
-```ruby
 create(:user).posts.length # 0
 create(:user_with_posts).posts.length # 5
 create(:user_with_posts, posts_count: 15).posts.length # 15
 ```
 
-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.
-
-Here's an example with two models that are related via
- `has_and_belongs_to_many`:
+Or, for a solution that works with `build`, `build_stubbed`, and `create`
+(although it doesn't work well with `attributes_for`), you can use inline
+associations:
 
 ```ruby
 FactoryBot.define do
+  factory :post do
+    title { "Through the Looking Glass" }
+    user
+  end
+
+  factory :user do
+    name { "Taylor Kim" }
+
+    factory :user_with_posts do
+      posts { [association(:post)] }
+    end
+  end
+end
+
+create(:user).posts.length # 0
+create(:user_with_posts).posts.length # 1
+build(:user_with_posts).posts.length # 1
+build_stubbed(:user_with_posts).posts.length # 1
+```
+
+For more flexibility you can combine this with the `posts_count` transient
+attribute from the callback example:
 
-  # language factory with a `belongs_to` association for the profile
-  factory :language do
+```ruby
+FactoryBot.define do
+  factory :post do
     title { "Through the Looking Glass" }
-    profile
+    user
   end
 
-  # profile factory without associated languages
-  factory :profile do
-    name { "John Doe" }
+  factory :user do
+    name { "Adiza Kumato" }
 
-    # 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
+    factory :user_with_posts do
       transient do
-        languages_count { 5 }
+        posts_count { 5 }
       end
 
-      # 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])
+      posts do
+        Array.new(posts_count) { association(:post) }
       end
     end
   end
 end
+
+create(:user_with_posts).posts.length # 5
+create(:user_with_posts, posts_count: 15).posts.length # 15
+build(:user_with_posts, posts_count: 15).posts.length # 15
+build_stubbed(:user_with_posts, posts_count: 15).posts.length # 15
 ```
 
-This allows us to do:
+### `has_and_belongs_to_many` associations
+
+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.
+
+
+```ruby
+def profile_with_languages(languages_count: 2)
+  FactoryBot.create(:profile) do |profile|
+    FactoryBot.create_list(:language, languages_count, profiles: [profile])
+  end
+end
+```
+
+Or with the callback approach:
 
 ```ruby
-create(:profile).languages.length # 0
-create(:profile_with_languages).languages.length # 5
-create(:profile_with_languages, languages_count: 15).languages.length # 15
+factory :profile_with_languages do
+  transient do
+    languages_count { 2 }
+  end
+
+  after(:create) do |profile, evaluator|
+    create_list(:language, evaluator.languages_count, profiles: [profile])
+    profile.reload
+  end
+end
 ```
 
-Polymorphic associations can be handled with traits:
+Or the inline association approach (note the use of the `instance` method here
+to refer to the profile being built):
 
+```ruby
+factory :profile_with_languages do
+  transient do
+    languages_count { 2 }
+  end
+
+  languages do
+    Array.new(languages_count) do
+      association(:language, profiles: [instance])
+    end
+  end
+end
 ```
+
+### Polymorphic associations
+
+Polymorphic associations can be handled with traits:
+
+```ruby
 FactoryBot.define do
   factory :video
   factory :photo
 
   factory :comment do
-    for_photo
+    for_photo # default to the :for_photo trait if none is specified
 
     trait :for_video do
-      association(:commentable, factory: :video)
+      association :commentable, factory: :video
     end
 
     trait :for_photo do
-      association(:commentable, factory: :photo)
+      association :commentable, factory: :photo
     end
   end
 end
@@ -531,16 +871,73 @@ end
 
 This allows us to do:
 
-```
+```ruby
 create(:comment)
 create(:comment, :for_video)
 create(:comment, :for_photo)
 ```
 
+### Interconnected associations
+
+There are limitless ways objects might be interconnected, and
+factory\_bot may not always be suited to handle those relationships. In some
+cases it makes sense to use factory\_bot to build each individual object, and
+then to write helper methods in plain Ruby to tie those objects together.
+
+That said, some more complex, interconnected relationships can be built in factory\_bot
+using inline associations with reference to the `instance` being built.
+
+Let's say your models look like this, where an associated `Student` and
+`Profile` should both belong to the same `School`:
+
+```ruby
+class Student < ApplicationRecord
+  belongs_to :school
+  has_one :profile
+end
+
+class Profile < ApplicationRecord
+  belongs_to :school
+  belongs_to :student
+end
+
+class School < ApplicationRecord
+  has_many :students
+  has_many :profiles
+end
+```
+
+We can ensure the student and profile are connected to each other and to the
+same school with a factory like this:
+
+```ruby
+FactoryBot.define do
+  factory :student do
+    school
+    profile { association :profile, student: instance, school: school }
+  end
+
+  factory :profile do
+    school
+    student { association :student, profile: instance, school: school }
+  end
+
+  factory :school
+end
+```
+
+Note that this approach works with `build`, `build_stubbed`, and `create`, but
+the associations will return `nil` when using `attributes_for`.
+
+Also, note that if you assign any attributes inside a custom `initialize_with` 
+(e.g. `initialize_with { new(**attributes) }`), those attributes should not refer to `instance`,
+since it will be `nil`.
 
 Sequences
 ---------
 
+### Global 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
@@ -561,6 +958,8 @@ generate :email
 # => "person2@example.com"
 ```
 
+### With dynamic attributes
+
 Sequences can be used in dynamic attributes:
 
 ```ruby
@@ -569,6 +968,8 @@ factory :invite do
 end
 ```
 
+### As implicit attributes
+
 Or as implicit attributes:
 
 ```ruby
@@ -580,6 +981,8 @@ end
 Note that defining sequences as implicit attributes will not work if you have a
 factory with the same name as the sequence.
 
+### Inline sequences
+
 And it's also possible to define an in-line sequence that is only used in
 a particular factory:
 
@@ -589,7 +992,10 @@ factory :user do
 end
 ```
 
-You can also override the initial value:
+### Initial value
+
+You can override the initial value. Any value that responds to the `#next`
+method will work (e.g. 1, 2, 3, 'a', 'b', 'c')
 
 ```ruby
 factory :user do
@@ -597,6 +1003,8 @@ factory :user do
 end
 ```
 
+### Without a block
+
 Without a block, the value will increment itself, starting at its initial value:
 
 ```ruby
@@ -605,6 +1013,17 @@ factory :post do
 end
 ```
 
+Please note, that the value for the sequence could be any Enumerable instance,
+as long as it responds to `#next`:
+
+```ruby
+factory :task do
+  sequence :priority, %i[low medium high urgent].cycle
+end
+```
+
+### Aliases
+
 Sequences can also have aliases. The sequence aliases share the same counter:
 
 ```ruby
@@ -634,6 +1053,8 @@ end
 
 The value just needs to support the `#next` method. Here the next value will be 'a', then 'b', etc.
 
+### Rewinding
+
 Sequences can also be rewound with `FactoryBot.rewind_sequences`:
 
 ```ruby
@@ -650,9 +1071,27 @@ generate(:email) # "person1@example.com"
 
 This rewinds all registered sequences.
 
+### Uniqueness
+
+When working with uniqueness constraints, be careful not to pass in override values that will conflict with the generated sequence values.
+
+In this example the email will be the same for both users. If email must be unique, this code will error:
+
+```rb
+factory :user do
+  sequence(:email) { |n| "person#{n}@example.com" }
+end
+
+FactoryBot.create(:user, email: "person1@example.com")
+FactoryBot.create(:user)
+```
+
+
 Traits
 ------
 
+### Defining traits
+
 Traits allow you to group attributes together and then apply them
 to any factory.
 
@@ -688,6 +1127,8 @@ factory :story do
 end
 ```
 
+### As implicit attributes
+
 Traits can be used as implicit attributes:
 
 ```ruby
@@ -701,6 +1142,8 @@ 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.
 
+### Attribute precedence
+
 Traits that define the same attributes won't raise AttributeDefinitionErrors;
 the trait that defines the attribute latest gets precedence.
 
@@ -709,16 +1152,16 @@ factory :user do
   name { "Friendly User" }
   login { name }
 
-  trait :male do
+  trait :active do
     name { "John Doe" }
-    gender { "Male" }
-    login { "#{name} (M)" }
+    status { :active }
+    login { "#{name} (active)" }
   end
 
-  trait :female do
+  trait :inactive do
     name { "Jane Doe" }
-    gender { "Female" }
-    login { "#{name} (F)" }
+    status { :inactive }
+    login { "#{name} (inactive)" }
   end
 
   trait :admin do
@@ -726,40 +1169,67 @@ factory :user do
     login { "admin-#{name}" }
   end
 
-  factory :male_admin,   traits: [:male, :admin]   # login will be "admin-John Doe"
-  factory :female_admin, traits: [:admin, :female] # login will be "Jane Doe (F)"
+  factory :active_admin,   traits: [:active, :admin]   # login will be "admin-John Doe"
+  factory :inactive_admin, traits: [:admin, :inactive] # login will be "Jane Doe (inactive)"
 end
 ```
 
-You can also override individual attributes granted by a trait in subclasses.
+### In child factories
+
+You can override individual attributes granted by a trait in a child factory:
 
 ```ruby
 factory :user do
   name { "Friendly User" }
   login { name }
 
-  trait :male do
+  trait :active do
     name { "John Doe" }
-    gender { "Male" }
+    status { :active }
     login { "#{name} (M)" }
   end
 
   factory :brandon do
-    male
+    active
     name { "Brandon" }
   end
 end
 ```
 
-Traits can also be passed in as a list of symbols when you construct an instance from factory_bot.
+### As mixins
+
+Traits can be defined outside of factories and used as mixins to compose shared attributes
+
+```ruby
+FactoryBot.define do
+  trait :timestamps do
+    created_at { 8.days.ago }
+    updated_at { 4.days.ago }
+  end
+  
+  factory :user, traits: [:timestamps] do
+    username { "john_doe" }
+  end
+  
+  factory :post do
+    timestamps
+    title { "Traits rock" }
+  end
+end
+```
+
+### Using traits
+
+Traits can also be passed in as a list of symbols when you construct an instance
+from factory\_bot.
 
 ```ruby
 factory :user do
   name { "Friendly User" }
 
-  trait :male do
+  trait :active do
     name { "John Doe" }
-    gender { "Male" }
+    status { :active }
   end
 
   trait :admin do
@@ -767,8 +1237,8 @@ factory :user do
   end
 end
 
-# creates an admin user with gender "Male" and name "Jon Snow"
-create(:user, :admin, :male, name: "Jon Snow")
+# creates an admin user with :active status and name "Jon Snow"
+create(:user, :admin, :active, name: "Jon Snow")
 ```
 
 This ability works with `build`, `build_stubbed`, `attributes_for`, and `create`.
@@ -786,10 +1256,12 @@ factory :user do
   end
 end
 
-# creates 3 admin users with gender "Male" and name "Jon Snow"
-create_list(:user, 3, :admin, :male, name: "Jon Snow")
+# creates 3 admin users with :active status and name "Jon Snow"
+create_list(:user, 3, :admin, :active, name: "Jon Snow")
 ```
 
+### With associations
+
 Traits can be used with associations easily too:
 
 ```ruby
@@ -830,6 +1302,8 @@ end
 create(:post).author
 ```
 
+### Traits within traits
+
 Traits can be used within other traits to mix in their attributes.
 
 ```ruby
@@ -845,6 +1319,8 @@ factory :order do
 end
 ```
 
+### With transient attributes
+
 Finally, traits can accept transient attributes.
 
 ```ruby
@@ -863,9 +1339,103 @@ end
 create :invoice, :with_amount, amount: 2
 ```
 
+### Enum traits
+
+Given an Active Record model with an enum attribute:
+
+```rb
+class Task < ActiveRecord::Base
+  enum status: {queued: 0, started: 1, finished: 2}
+end
+
+```
+
+factory\_bot will automatically define traits for each possible value of the
+enum:
+
+```rb
+FactoryBot.define do
+  factory :task
+end
+
+FactoryBot.build(:task, :queued)
+FactoryBot.build(:task, :started)
+FactoryBot.build(:task, :finished)
+```
+
+Writing the traits out manually would be cumbersome, and is not necessary:
+
+```rb
+FactoryBot.define do
+  factory :task do
+    trait :queued do
+      status { :queued }
+    end
+
+    trait :started do
+      status { :started }
+    end
+
+    trait :finished do
+      status { :finished }
+    end
+  end
+end
+```
+
+If automatically defining traits for enum attributes on every factory is not
+desired, it is possible to disable the feature by setting
+`FactoryBot.automatically_define_enum_traits = false`
+
+In that case, it is still possible to explicitly define traits for an enum
+attribute in a particular factory:
+
+```rb
+FactoryBot.automatically_define_enum_traits = false
+
+FactoryBot.define do
+  factory :task do
+    traits_for_enum(:status)
+  end
+end
+```
+
+It is also possible to use this feature for other enumerable values, not
+specifically tied to Active Record enum attributes.
+
+With an array:
+
+```rb
+class Task
+  attr_accessor :status
+end
+
+FactoryBot.define do
+  factory :task do
+    traits_for_enum(:status, ["queued", "started", "finished"])
+  end
+end
+```
+
+Or with a hash:
+
+```rb
+class Task
+  attr_accessor :status
+end
+
+FactoryBot.define do
+  factory :task do
+    traits_for_enum(:status, { queued: 0, started: 1, finished: 2 })
+  end
+end
+```
+
 Callbacks
 ---------
 
+### Default callbacks
+
 factory\_bot makes available four callbacks for injecting some code:
 
 * after(:build)   - called after a factory is built   (via `FactoryBot.build`, `FactoryBot.create`)
@@ -884,6 +1454,8 @@ end
 
 Note that you'll have an instance of the user in the block. This can be useful.
 
+### Multiple callbacks
+
 You can also define multiple types of callbacks on the same factory:
 
 ```ruby
@@ -893,7 +1465,8 @@ factory :user do
 end
 ```
 
-Factories can also define any number of the same kind of callback.  These callbacks will be executed in the order they are specified:
+Factories can also define any number of the same kind of callback.  These
+callbacks will be executed in the order they are specified:
 
 ```ruby
 factory :user do
@@ -904,9 +1477,12 @@ end
 
 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.
+Also, like standard attributes, child factories will inherit (and can also
+define) callbacks from their parent factory.
 
-Multiple callbacks can be assigned to run a block; this is useful when building various strategies that run the same code (since there are no callbacks that are shared across all strategies).
+Multiple callbacks can be assigned to run a block; this is useful when building
+various strategies that run the same code (since there are no callbacks that are
+shared across all strategies).
 
 ```ruby
 factory :user do
@@ -916,6 +1492,8 @@ factory :user do
 end
 ```
 
+### Global callbacks
+
 To override callbacks for all factories, define them within the
 `FactoryBot.define` block:
 
@@ -930,7 +1508,9 @@ FactoryBot.define do
 end
 ```
 
-You can also call callbacks that rely on `Symbol#to_proc`:
+### Symbol#to_proc
+
+You can call callbacks that rely on `Symbol#to_proc`:
 
 ```ruby
 # app/models/user.rb
@@ -953,15 +1533,16 @@ create(:user) # creates the user and confirms it
 Modifying factories
 -------------------
 
-If you're given a set of factories (say, from a gem developer) but want to change them to fit into your application better, you can
-modify that factory instead of creating a child factory and adding attributes there.
+If you're given a set of factories (say, from a gem developer) but want to
+change them to fit into your application better, you can modify that factory
+instead of creating a child factory and adding attributes there.
 
 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" }
   end
@@ -975,7 +1556,6 @@ FactoryBot.define do
   factory :application_user, parent: :user do
     full_name { "Jane Doe" }
     date_of_birth { 21.years.ago }
-    gender { "Female" }
     health { 90 }
   end
 end
@@ -988,7 +1568,6 @@ FactoryBot.modify do
   factory :user do
     full_name { "Jane Doe" }
     date_of_birth { 21.years.ago }
-    gender { "Female" }
     health { 90 }
   end
 end
@@ -1018,6 +1597,23 @@ 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
+```
+
+`create_list` passes saved instances into the block. If you modify the instance, you must save it again:
+
+```ruby
+twenty_somethings = create_list(:user, 10) do |user, i|
+  user.date_of_birth = (20 + i).years.ago
+  user.save!
+end
+```
+
 `build_stubbed_list` will give you fully stubbed out instances:
 
 ```ruby
@@ -1040,7 +1636,7 @@ users_attrs = attributes_for_list(:user, 25) # array of attribute hashes
 Linting Factories
 -----------------
 
-factory_bot allows for linting known factories:
+factory\_bot allows for linting known factories:
 
 ```ruby
 FactoryBot.lint
@@ -1067,9 +1663,10 @@ namespace :factory_bot do
   desc "Verify that all FactoryBot factories are valid"
   task lint: :environment do
     if Rails.env.test?
-      DatabaseCleaner.clean_with(:deletion)
-      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'")
@@ -1081,8 +1678,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:
 
@@ -1126,7 +1722,7 @@ FactoryBot.lint verbose: true
 Custom Construction
 -------------------
 
-If you want to use factory_bot to construct an object where some attributes
+If you want to use factory\_bot to construct an object where some attributes
 are passed to `initialize` or if you want to do something other than simply
 calling `new` on your build class, you can override the default behavior by
 defining `initialize_with` on your factory. Example:
@@ -1154,7 +1750,7 @@ end
 build(:user).name # Jane Doe
 ```
 
-Although factory_bot is written to work with ActiveRecord out of the box, it
+Although factory\_bot is written to work with ActiveRecord out of the box, it
 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
@@ -1165,7 +1761,7 @@ You can override the initializer in order to:
 
 * Build non-ActiveRecord objects that require arguments to `initialize`
 * Use a method other than `new` to instantiate the instance
-* Do crazy things like decorate the instance after it's built
+* Do wild things like decorate the instance after it's built
 
 When using `initialize_with`, you don't have to declare the class itself when
 calling `new`; however, any other class methods you want to call will have to
@@ -1192,7 +1788,7 @@ factory :user do
 
   name "John Doe"
 
-  initialize_with { new(attributes) }
+  initialize_with { new(**attributes) }
 end
 ```
 
@@ -1227,7 +1823,7 @@ build(:user)
 User.new('value')
 ```
 
-This prevents duplicate assignment; in versions of factory_bot before 4.0, it
+This prevents duplicate assignment; in versions of factory\_bot before 4.0, it
 would run this:
 
 ```ruby
@@ -1413,12 +2009,12 @@ with associations, as below:
 
 ```ruby
 FactoryBot.define do
-  factory :united_states, class: Location do
+  factory :united_states, class: "Location" do
     name { 'United States' }
     association :location_group, factory: :north_america
   end
 
-  factory :north_america, class: LocationGroup do
+  factory :north_america, class: "LocationGroup" do
     name { 'North America' }
   end
 end