factory_bot.md

   1 ---
   2 title: Factory Bot
   3 category: Ruby libraries
   4 layout: 2017/sheet
   5 weight: -3
   6 updated: 2017-10-31
   7 keywords:
   8   - "FactoryBot.define do"
   9   - "factory :user"
  10   - "first_name 'John'"
  11   - "sequence(:username) { |n| \"user#{n}\" }"
  12 tags: [Featurable]
  13 intro: |
  14   [Factory Bot](http://www.rubydoc.info/gems/factory_bot/) is a helper for writing factories for Ruby tests.
  15   It was previously known as Factory Girl. For older versions, use `FactoryGirl` instead of `FactoryBot`.
  16 ---
  17
  18 ## Factories
  19 {: .-three-column}
  20
  21 ### Defining factories
  22
  23 ```ruby
  24 FactoryBot.define do
  25   factory :user do
  26     first_name 'John'
  27     last_name  'Doe'
  28     birthdate  { 21.years.ago }
  29     admin false
  30
  31     sequence(:username) { |n| "user#{n}" }
  32   end
  33 end
  34 ```
  35 {: data-line="2"}
  36
  37 See: [Defining factories](http://www.rubydoc.info/gems/factory_bot/file/GETTING_STARTED.md#Defining_factories)
  38
  39 ### Extra options
  40
  41 #### Custom class names
  42
  43 ```ruby
  44 factory :user, class: 'User' do
  45   ···
  46 end
  47 ```
  48
  49 #### Aliases
  50
  51 ```ruby
  52 factory :user, aliases: [:author] do
  53   ···
  54 end
  55 ```
  56
  57 ### Using
  58
  59 #### Build a model
  60
  61 ```ruby
  62 FactoryBot.build(:user)
  63 ```
  64
  65 #### Other ways
  66
  67 ```ruby
  68 build(:user)           # → model (not saved)
  69 create(:user)          # → model (saved)
  70 attributes_for(:user)  # → hash
  71 build_stubbed(:user)   # stubbed out attributes
  72 ```
  73
  74 #### With options
  75
  76 ```ruby
  77 build(:user, name: 'John')
  78 ```
  79
  80 #### Lists
  81
  82 ```ruby
  83 create_list(:user, 3)
  84 build_list(:user, 3)
  85 ```
  86
  87 ## Associations
  88
  89 ### Defining
  90
  91 ```ruby
  92 factory :post do
  93   association :author, factory: :user
  94   association :author, factory: [:user, :admin]
  95 end
  96 ```
  97 {: data-line="2,3"}
  98
  99 #### or
 100
 101 ```ruby
 102 factory :post do
 103   author  # assumes there's a factory :author
 104 end
 105 ```
 106
 107 ### After-create hooks
 108
 109 ```ruby
 110 factory :post do
 111   after :create do |post|
 112     create :theme, post: post             # has_one
 113     create_list :comment, 3, post: post   # has_many
 114   end
 115 end
 116 ```
 117 {: data-line="2"}
 118
 119 ## Other features
 120 {: .-three-column}
 121
 122 ### Traits
 123
 124 ```ruby
 125 factory :user do
 126   trait :admin do
 127     admin true
 128   end
 129 end
 130 ```
 131 {: data-line="2,3,4"}
 132
 133 ```ruby
 134 create :user, :admin
 135 ```
 136
 137 Traits allow you to group attributes together.
 138 See: [Traits](http://www.rubydoc.info/gems/factory_bot/file/GETTING_STARTED.md#Traits)
 139
 140 ### Nested factories
 141
 142 ```ruby
 143 factory :user do
 144   first_name 'John'
 145
 146   factory :sample_user do
 147     first_name { FFaker::Name.first_name }
 148   end
 149 end
 150 ```
 151 {: data-line="4,5,6"}
 152
 153 ```ruby
 154 create :sample_user
 155 ```
 156
 157 See: [Inheritance](http://www.rubydoc.info/gems/factory_bot/file/GETTING_STARTED.md#Inheritance)
 158
 159 ### Sub-factories
 160
 161 ```ruby
 162 factory :user do
 163   ···
 164 end
 165 ```
 166
 167 ```ruby
 168 factory :sample_user, parent: :user do
 169   first_name { FFaker::Name.first_name }
 170 end
 171 ```
 172 {: data-line="1"}
 173
 174 ```ruby
 175 create :sample_user
 176 ```
 177
 178 Works the same as nested factories.
 179
 180 ### Options (transients)
 181
 182 ```ruby
 183 factory :user do
 184   transient do
 185     upcased true
 186   end
 187
 188   after :create do |user, options|
 189     user.name.upcase! if options.upcased
 190   end
 191 end
 192 ```
 193 {: data-line="2,3,4"}
 194
 195 ```ruby
 196 create(user, upcased: true)
 197 ```
 198
 199 Transient attributes will not get passed to the model, but will be available in after-create hooks.
 200 See: [Transient attributes](http://www.rubydoc.info/gems/factory_bot/file/GETTING_STARTED.md#Transient_Attributes)
 201
 202 ### Paths
 203
 204 * test/factories.rb
 205 * spec/factories.rb
 206 * test/factories/*.rb
 207 * spec/factories/*.rb
 208
 209 Place your factories in these locations.
 210 {: .-setup}
 211
 212 ## See also
 213 {: .-one-column}
 214
 215 * <http://rubydoc.info/gems/factory_bot/file/GETTING_STARTED.md>