factory_bot_rails

factory_bot is a fixtures replacement with a straightforward definition syntax, support for multiple build strategies (saved instances, unsaved instances, attribute hashes, and stubbed objects), and support for multiple factories for the same class (user, admin_user, and so on), including factory inheritance.

Transitioning from factory_girl_rails?

Check out the guide.

Rails

factory_bot_rails provides Rails integration for factory_bot.

Supported Rails versions are listed in Appraisals. Supported Ruby versions are listed in .github/workflows/build.yml.

Download

Github: http://github.com/thoughtbot/factory_bot_rails

Gem:

$ gem install factory_bot_rails

Configuration

Add factory_bot_rails to your Gemfile in both the test and development groups:

group :development, :test do
  gem 'factory_bot_rails'
end

You may want to configure your test suite to include factory_bot methods; see configuration.

Automatic Factory Definition Loading

By default, factory_bot_rails will automatically load factories defined in the following locations, relative to the root of the Rails project:

factories.rb
test/factories.rb
spec/factories.rb
factories/*.rb
test/factories/*.rb
spec/factories/*.rb

You can configure by adding the following to config/application.rb or the appropriate environment configuration in config/environments:

config.factory_bot.definition_file_paths = ["custom/factories"]

This will cause factory_bot_rails to automatically load factories in custom/factories.rb and custom/factories/*.rb.

It is possible to use this setting to share factories from a gem:

begin
  require 'factory_bot_rails'
rescue LoadError
end

class MyEngine < ::Rails::Engine
  config.factory_bot.definition_file_paths +=
    [File.expand_path('../factories', __FILE__)] if defined?(FactoryBotRails)
end

You can also disable automatic factory definition loading entirely by using an empty array:

config.factory_bot.definition_file_paths = []

Generators

Including factory_bot_rails in the development group of your Gemfile will cause Rails to generate factories instead of fixtures. If you want to disable this feature, you can either move factory_bot_rails out of the development group of your Gemfile, or add the following configuration:

config.generators do |g|
  g.factory_bot false
end

If fixture replacement is enabled and you already have a test/factories.rb file (or spec/factories.rb if using rspec_rails), generated factories will be inserted at the top of the existing file. Otherwise, factories will be generated in the test/factories directory (spec/factories if using rspec_rails), in a file matching the name of the table (e.g. test/factories/users.rb).

To generate factories in a different directory, you can use the following configuration:

config.generators do |g|
  g.factory_bot dir: 'custom/dir/for/factories'
end

Note that factory_bot_rails will not automatically load files in custom locations unless you add them to config.factory_bot.definition_file_paths as well.

The suffix option allows you to customize the name of the generated file with a suffix:

config.generators do |g|
  g.factory_bot suffix: "factory"
end

This will generate test/factories/users_factory.rb instead of test/factories/users.rb.

For even more customization, use the filename_proc option:

config.generators do |g|
  g.factory_bot filename_proc: ->(table_name) { "prefix_#{table_name}_suffix" }
end

To override the default factory template, define your own template in lib/templates/factory_bot/model/factories.erb. This template will have access to any methods available in FactoryBot::Generators::ModelGenerator. Note that factory_bot_rails will only use this custom template if you are generating each factory in a separate file; it will have no effect if you are generating all of your factories in test/factories.rb or spec/factories.rb.

Factory_bot_rails will add a custom generator:

rails generate factory_bot:model NAME [field:type field:type] [options]

Contributing

Please see CONTRIBUTING.md.

factory_bot_rails was originally written by Joe Ferris and is maintained by thoughtbot. Many improvements and bugfixes were contributed by the open source community.