factory_bot 4.10.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f6cddf8a7633587c40928e1b9bd981a644d0f2f99259eaafdd0ac986fa19775
-  data.tar.gz: 4300e1bc0e6204159ca66ef4ec2a3a9eb1cc131693b7907591e1a94f1f1e93f7
+  metadata.gz: fe33ad3bb5d907e38ceac543f969484fb0ec67a4708a701cdfea0696d4a292c4
+  data.tar.gz: 54cdb44f4ac7782360c8e9efd02ac46f40336d00c34a5767d5d7fc0f86f8d7a5
 SHA512:
-  metadata.gz: 9583c5fb81fd3be6241566123cc1ffa590f54cc58c441868aff8efb679405b2c52bf38fd8ca9c3a4bf89079d12505d64565161ff300fca3d186cfcafc3573dd6
-  data.tar.gz: 10723a4fdc450038aa2d515e3df7ff26d59d634439e6632daa44ba91f6ca87491f52edfb9c9595da8fd3621dda4a2b707dd8523c4eb42c156fda04411d75c332
+  metadata.gz: cdc3ec9def71e797058fb13cff95b911eceb61d1488f193ef1bfb6bdf12c6c7835d1f67dc1885d5539e6da7135f04e4a417a16fbc60cbc0c4d60056a1948c89d
+  data.tar.gz: 2f04ab1a184266a86cf8510be688b8a01b0dd570615d25e314176b4492f9635053596636aa4ec9ab8133e86e4c9f630acdb52468c01ea1bfd2fb8777fc27b2ab

data/.yardopts

@@ -2,4 +2,5 @@ lib/**/*.rb
 -
 GETTING_STARTED.md
 CONTRIBUTING.md
+NAME.md
 LICENSE

data/CONTRIBUTING.md

@@ -12,7 +12,7 @@ Here are some ways *you* can contribute:
 * by suggesting new features
 * by writing or editing documentation
 * by writing specifications
-* by writing code ( **no patch is too small** : fix typos, add comments, clean up inconsistent whitespace )
+* by writing code ( **no patch is too small** : fix typos, add comments, etc. )
 * by refactoring code
 * by closing [issues][]
 * by reviewing patches
@@ -23,13 +23,10 @@ Here are some ways *you* can contribute:
 
 * We use the [GitHub issue tracker][issues] to track bugs and features.
 * Before submitting a bug report or feature request, check to make sure it hasn't
-already been submitted.
-* When submitting a bug report, please include a [Gist][] that includes a stack
-  trace and any details that may be necessary to reproduce the bug, including
-  your gem version, Ruby version, and operating system.  Ideally, a bug report
-  should include a pull request with failing specs.
-
-[gist]: https://gist.github.com/
+  already been submitted.
+* When submitting a bug report, please include a [reproduction script] and any
+  other details that may be necessary to reproduce the bug, including your gem
+  version, Ruby version, and operating system.
 
 ## Cleaning up issues
 
@@ -40,21 +37,63 @@ already been submitted.
   We will happily reopen the issue.
 
 ## Submitting a Pull Request
+
 1. [Fork][fork] the [official repository][repo].
-2. [Create a topic branch.][branch]
-3. Implement your feature or bug fix.
-4. Add, commit, and push your changes.
-5. [Submit a pull request.][pr]
+1. [Create a topic branch.][branch]
+1. Implement your feature or bug fix.
+1. Add, commit, and push your changes.
+1. [Submit a pull request.][pr]
+
+### Notes
 
-## Notes
 * Please add tests if you changed code. Contributions without tests won't be accepted.
 * If you don't know how to add tests, please put in a PR and leave a comment
   asking for help. We love helping!
 * Please don't update the Gem version.
 
+## Running the test suite
+
+The default rake task will run the full test suite and [standard]:
+
+```sh
+bundle exec rake
+```
+
+You can also run a single group of tests (unit, spec, or feature)
+
+```sh
+bundle exec rake spec:unit
+bundle exec rake spec:acceptance
+bundle exec rake features
+```
+
+To run an individual rspec test, you can provide a path and line number:
+
+```sh
+bundle exec rspec spec/path/to/spec.rb:123
+```
+
+You can run tests with a specific version of rails via [appraisal]. To run
+the default rake task against Rails 6, for example:
+
+```sh
+bundle exec appraisal 6.0 rake
+```
+
+## Formatting
+
+Use [standard] to automatically format your code:
+
+```sh
+bundle exec rake standard:fix
+```
+
 [repo]: https://github.com/thoughtbot/factory_bot/tree/master
 [fork]: https://help.github.com/articles/fork-a-repo/
 [branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
 [pr]: https://help.github.com/articles/using-pull-requests/
+[standard]: https://github.com/testdouble/standard
+[appraisal]: https://github.com/thoughtbot/appraisal
+[reproduction script]: https://github.com/thoughtbot/factory_bot/blob/master/.github/REPRODUCTION_SCRIPT.rb
 
 Inspired by https://github.com/middleman/middleman-heroku/blob/master/CONTRIBUTING.md

data/GETTING_STARTED.md

@@ -1,42 +1,118 @@
 Getting Started
 ===============
 
-Update Your Gemfile
--------------------
-
-If you're using Rails, you'll need to change the required version of `factory_bot_rails`:
+* [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)
+  + [Specifying the factory](#specifying-the-factory)
+  + [Overriding attributes](#overriding-attributes)
+  + [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)
+* [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:
+
+```ruby
+gem "factory_bot_rails"
+```
+
+If you're *not* using Rails:
+
+```ruby
+gem "factory_bot"
+```
+
+### Configure your test suite
+
+#### 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
-gem "factory_bot_rails", "~> 4.0"
-```
-
-If you're *not* using Rails, you'll just have to change the required version of `factory_bot`:
-
-```ruby
-gem "factory_bot", "~> 4.0"
-```
-
-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
--------------------------
-
-### RSpec
-
-```ruby
-# spec/support/factory_bot.rb
 RSpec.configure do |config|
   config.include FactoryBot::Syntax::Methods
 end
+```
+
+If you're *not* using Rails:
 
-# RSpec without Rails
+```ruby
 RSpec.configure do |config|
   config.include FactoryBot::Syntax::Methods
 
@@ -46,13 +122,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 +130,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 +145,7 @@ class Spinach::FeatureSteps
 end
 ```
 
-### Minitest
+#### Minitest
 
 ```ruby
 class Minitest::Unit::TestCase
@@ -83,7 +153,7 @@ class Minitest::Unit::TestCase
 end
 ```
 
-### Minitest::Spec
+#### Minitest::Spec
 
 ```ruby
 class Minitest::Spec
@@ -91,7 +161,7 @@ class Minitest::Spec
 end
 ```
 
-### minitest-rails
+#### minitest-rails
 
 ```ruby
 class ActiveSupport::TestCase
@@ -99,35 +169,71 @@ 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, but it's possible to explicitly specify it:
+### 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
 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
+### 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
+```
+
+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"
+```
+
+### 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:
+
+```ruby
+factory :program do
+  configuration { { auto_resolve: false, auto_define: true } }
 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:
@@ -137,10 +243,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
@@ -161,7 +277,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
@@ -170,40 +289,25 @@ user.first_name
 # => "Joe"
 ```
 
-Dynamic Attributes
-------------------
+### `build_stubbed` and `Marshal.dump`
 
-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
-```
-
-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
-```
+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 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 +315,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 +335,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
 
@@ -243,40 +347,82 @@ create(:user, last_name: "Doe").email
 Transient Attributes
 --------------------
 
-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 }
+  end
+
+  name { "John Doe#{" - Rockstar" if rockstar}" }
+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
-    rockstar true
-    upcased  false
+    upcased { false }
   end
 
-  name  { "John Doe#{" - Rockstar" if rockstar}" }
-  email { "#{name.downcase}@example.com" }
+  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"
 ```
 
-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.
+### 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
 -------------------------------
 
-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
@@ -292,14 +438,17 @@ 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
-  title "A title"
+  title { "A title" }
 
   factory :approved_post do
-    approved true
+    approved { true }
   end
 end
 
@@ -308,18 +457,22 @@ approved_post.title    # => "A title"
 approved_post.approved # => true
 ```
 
+### Assigning parent explicitly
+
 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
 ```
 
+### 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
@@ -328,7 +481,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
@@ -337,18 +493,95 @@ 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
+```
+
+### 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
+```
+
+### 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
 ```
 
-The behavior of the association method varies depending on the build strategy used for the parent object.
+### Build strategies
+
+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 +593,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
@@ -383,6 +618,8 @@ factory :post do
   author strategy: :build    # <<< this does *not* work; causes author_id to be nil
 ```
 
+### `has_many` associations
+
 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.
@@ -392,20 +629,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
@@ -428,6 +665,8 @@ create(:user_with_posts).posts.length # 5
 create(:user_with_posts, posts_count: 15).posts.length # 15
 ```
 
+### `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
@@ -441,13 +680,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 +694,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,9 +718,43 @@ create(:profile_with_languages).languages.length # 5
 create(:profile_with_languages, languages_count: 15).languages.length # 15
 ```
 
+### Polymorphic associations
+
+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
 ---------
 
+### 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
@@ -502,6 +775,8 @@ generate :email
 # => "person2@example.com"
 ```
 
+### With dynamic attributes
+
 Sequences can be used in dynamic attributes:
 
 ```ruby
@@ -510,6 +785,8 @@ factory :invite do
 end
 ```
 
+### As implicit attributes
+
 Or as implicit attributes:
 
 ```ruby
@@ -518,6 +795,11 @@ 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.
+
+### Inline sequences
+
 And it's also possible to define an in-line sequence that is only used in
 a particular factory:
 
@@ -527,7 +809,10 @@ factory :user do
 end
 ```
 
-You can also override the initial value:
+### Initial value
+
+You can override the initial value. Any value that response to the `#next`
+method will work (e.g. 1, 2, 3, 'a', 'b', 'c')
 
 ```ruby
 factory :user do
@@ -535,6 +820,8 @@ factory :user do
 end
 ```
 
+### Without a block
+
 Without a block, the value will increment itself, starting at its initial value:
 
 ```ruby
@@ -543,6 +830,8 @@ factory :post do
 end
 ```
 
+### Aliases
+
 Sequences can also have aliases. The sequence aliases share the same counter:
 
 ```ruby
@@ -572,6 +861,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
@@ -588,9 +879,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.
 
@@ -598,25 +907,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]
@@ -626,7 +935,9 @@ factory :story do
 end
 ```
 
-Traits can be used as attributes:
+### As implicit attributes
+
+Traits can be used as implicit attributes:
 
 ```ruby
 factory :week_long_published_story_with_title, parent: :story do
@@ -636,28 +947,33 @@ 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.
+
+### Attribute precedence
+
 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
 
@@ -666,39 +982,44 @@ factory :user do
 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"
+  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
 ```
 
-Traits can also be passed in as a list of symbols when you construct an instance from factory_bot.
+### 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"
+  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
 
@@ -714,10 +1035,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
 
@@ -725,14 +1046,16 @@ end
 create_list(:user, 3, :admin, :male, name: "Jon Snow")
 ```
 
+### With associations
+
 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
 
@@ -748,10 +1071,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
 
@@ -765,6 +1088,8 @@ end
 create(:post).author
 ```
 
+### Traits within traits
+
 Traits can be used within other traits to mix in their attributes.
 
 ```ruby
@@ -780,13 +1105,15 @@ factory :order do
 end
 ```
 
+### With transient attributes
+
 Finally, traits can accept transient attributes.
 
 ```ruby
 factory :invoice do
   trait :with_amount do
     transient do
-      amount 1
+      amount { 1 }
     end
 
     after(:create) do |invoice, evaluator|
@@ -798,9 +1125,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`)
@@ -819,6 +1240,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
@@ -828,7 +1251,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
@@ -839,9 +1263,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
@@ -851,6 +1278,8 @@ factory :user do
 end
 ```
 
+### Global callbacks
+
 To override callbacks for all factories, define them within the
 `FactoryBot.define` block:
 
@@ -860,12 +1289,14 @@ FactoryBot.define do
   after(:create) { |object| AuditLog.create(attrs: object.attributes) }
 
   factory :user do
-    name "John Doe"
+    name { "John Doe" }
   end
 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
@@ -888,17 +1319,18 @@ 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"
+    password { "password" }
   end
 end
 ```
@@ -908,10 +1340,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
 ```
@@ -921,10 +1353,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
 ```
@@ -953,6 +1385,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
@@ -975,7 +1415,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
@@ -1002,8 +1442,10 @@ 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'")
@@ -1015,8 +1457,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:
 
@@ -1050,10 +1491,17 @@ 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
 -------------------
 
-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:
@@ -1072,7 +1520,7 @@ end
 sequence(:email) { |n| "person#{n}@example.com" }
 
 factory :user do
-  name "Jane Doe"
+  name { "Jane Doe" }
   email
 
   initialize_with { new(name) }
@@ -1081,7 +1529,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
@@ -1092,7 +1540,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
@@ -1102,7 +1550,7 @@ For example:
 
 ```ruby
 factory :user do
-  name "John Doe"
+  name { "John Doe" }
 
   initialize_with { User.build_with_name(name) }
 end
@@ -1114,7 +1562,7 @@ by calling `attributes`:
 ```ruby
 factory :user do
   transient do
-    comments_count 5
+    comments_count { 5 }
   end
 
   name "John Doe"
@@ -1125,7 +1573,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:
@@ -1154,7 +1602,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
@@ -1287,7 +1735,7 @@ FactoryBot.define do
 
 
   factory :user do
-    name "John Doe"
+    name { "John Doe" }
   end
 end
 ```
@@ -1340,13 +1788,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
 ```
@@ -1378,7 +1826,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
@@ -1400,7 +1848,7 @@ require 'factory_bot'
 
 FactoryBot.define do
   factory :user do
-    name 'John Doe'
+    name { 'John Doe' }
     date_of_birth { 21.years.ago }
   end
 end