Fixing the FactoryBot configuration

[elia]

We've been doing FactoryBot updates on a number of apps internally at @nebulab, so we'd like to share our process for doing that, in the hope it will be helpful for others.

---

Overview

The way Solidus was loading FactoryBot factories up until v2.11 was a hack that
worked against Rails reloading and made them substantially incompatible with Spring
and other tools, in addition to being at odds with the installation instruction that
could be found in the FactoryBot and FactoryBotRails respective READMEs.

What's wrong with the previous setup?

The basic loading mechanism for factories is still loading the factory file with either
require or load. Over time FactoryBot moved to collecting the paths were factories
are defined and loading them in bulk when FactoryBot.find_definitions is called. Solidus
itself, many of its extensions, and most apps ended up in a mix of calling both require
and find_definitions.

Usually this was the result of trying to apply FactoryBot's instructions and bumping into some
issue with the loading sequence, or weird errors that ended up being resolved only by a
complete app restart (or spring stop, etc.).

How a loading factories in the wrong order can break your app?

One of the main issues with Solidus factories used inside your Rails application is that of
factories modifying existing ones. In fact if you add an attribute to, say, Spree::User you
also probably need to update its factory with code that looks more ore less like this:

spec/factories/users.rb

FactoryBot.modify do
  factory :user do
    my_custom_column { :foo_bar }
  end
end

This kind of factory strictly requires the :user factory defined by solidus in
[solidus-core-root]/lib/spree/testing_support/factories/user_factory.rb to be loaded first.

Even worse the situation in which your application needs to modify a factory that is defined in
Solidus and then modified by one or more extensions.

The solution (in 2 easy steps)

Give all of that we needed a solution that could give a way forward without wreaking havoc in all
existing apps and extensions. For this reason doing nothing will just work, and show some deprecations,
but we strongly encourage the upgrade to benefit from app start times (via spring) and reduced need
for full app restarts.

Step 1: Remove any previous configuration

Things to note down before starting:

• Take a note of your current version of FactoryBot / FactoryBotRails,
  use bundle info factory_bot or bundle info factory_bot_rails
• Take a note of the factories you depend on, usually Solidus, occasionally extensions,
  most of the time those come in the form of requires in your spec_helper, e.g.
  require 'spree/testing_support/factories'
• Make sure you're not cherry-picking factories from Solidus, i.e. you don't have
  anything like require 'spree/testing_support/factories/user_factory', check
  both your spec helper files and your factories

A laundry list of places that could include FactoryBot related code:

• Remove any dependency on factory_bot or factory_bot_rails from the Gemfile
• Remove any spec_helper.rb, rails_helper.rb, or spec/support code related to FactoryBot, including requires coming
• Remove any initialization code in config/application.rb or inside initializers, e.g. config/initializers/factory_bot.rb

Step 2: Add back the updated configuration

1. Add the factory_bot_rails gem

Add gem 'factory_bot_rails', '~> 4.8' to your Gemfile, we advise to use the same version
used by Solidus to ensure you don't get errors from differences in how FactoryBot builds/creates
associations, but if your app was based on a more recent version you might prefer to stick to
that one instead.

Gemfile

group :development, :test do
  gem 'factory_bot_rails', '~> 4.8'
end

2. Configure paths in config/application.rb

The initializer should look like this:

config/application.rb

module MyApplication
  class Application < Rails::Application

    # … everything else

    # Don't initialize this if factory_bot_rails is not part of the
    # current bundle group.
    if defined?(FactoryBotRails)
      initializer after: "factory_bot.set_factory_paths" do
        require 'spree/testing_support'
      
        # The paths for solidus factories.
        solidus_paths = Spree::TestingSupport::FactoryBot.definition_file_paths
      
        # The paths for extensions may be in different places, please refer to each extension
        # and add the factories you require without the ".rb" extension, avoid the directory
        # as it's supported by FactoryBot but can generate ambigous paths when a file with the 
        # same name exists.
        extension_paths = [
          MySolidusExtension::Engine.root.join("lib/solidus_content/factories.rb"),
          # alternative 1: MySolidusExtension::Engine.root.join("lib/solidus_content/factories/product.rb"),
          # alternative 2: MySolidusExtension::Engine.root.join("lib/solidus_content/factories/product_factory.rb"),
          # etc.
        ].map { |path| path.to_s.chomp(".rb") }
      
        # The application factories, according to the place in which they're stored.
        app_paths = [
          Rails.root.join('lib', 'factories'),
          Rails.root.join('spec', 'factories'),
        ]
      
        FactoryBot.definition_file_paths = solidus_paths + extension_paths + app_paths
      end
    end
  end
end

3. Setup the RSpec helpers

As advised by the FactoryBot readme:

spec/support/factory_bot.rb

RSpec.configure do |config|
  config.include FactoryBot::Syntax::Methods
end

🎉 That's all!

[johnpitchko]

Fixed an annoyance we encountered with deprecation warnings from require-ing base factories in our modified factory classes - thank you!