factory_bot

This week, Chris is joined by thoughtbot's Development Director in Boston, Josh Clayton, to talk about factory_bot; a topic near and dear to Josh's heart, as he's been the maintainer of the project for over five years.

FactoryBot is one of thoughtbot's most popular open-source projects, and is one of the few gems that we consider a requirement for every project, new or old. Let's discover why.

Note: This video was recorded prior to us renaming the FactoryBot gem from its original name, FactoryGirl. In the video we refer to the gem by its old name, but we've updated all code samples and references in these notes to reference the current name. You can read more about the change in the announcement blog post.

What is It?

For any given test, we need some data about which to make an assertion after performing some operation. To help produce test data more easily, Rails comes with built-in support for fixtures, but time and time again we found that fixtures were tedious to write and led to testing antipatterns. factory_bot is intended to be a replacement for fixtures that makes it easier to produce test data while avoiding these antipatterns.

What exactly is it about fixtures that we're trying to move away from?

Fixtures are static data stored in a YAML file; you have to handwrite however many variants of objects that your tests will need, which can be tedious. Also, it moves some of the complexity of a test out of the test itself, and makes it harder to understand at a glance.

Also, fixtures are often all-or-nothing. If you have written several slightly different objects in your fixtures to support a few different tests, you have to load them all up every time; but not every test needs all of the objects.

In contrast, factory_bot allows you to generate valid one-off objects as needed, and you can dynamically send in data to override default attributes and create the variants that you need on a test-specific basis. It tries to strike the right balance between conciseness and explicitness.

How FactoryBot helps avoid mystery guests

Let's look at a specific example. Fixtures often lead to Mystery Guests, an antipattern where we are performing some assertions in our tests but it's not at all obvious at a glance what the data we're asserting against is:

# first_name_spec.rb test using fixture
require "rails_helper"

describe "User" do
  describe "first_name" do
    it "is the first part of the name" do
      user = users(:johnq)

      expect(user.first_name).to eq("John")
    end
  end
end

Looking at just the test alone, it's hard to know exactly what's going on. Are we're testing capitalization? Is the attribute concerned called full_name? Who knows?

Once we look at the fixture, it becomes more clear:

# users.yml fixture
johnq:
  name: John Q User
  email: user@example.com

nancy:
  name: Nancy User
  email: other@example.com

It seems like we're expecting the first_name method to split the name attribute, but we could only know that after examining the fixture. In contrast, using factory_bot, the test would look like this:

# first_name_spec.rb test using factory_bot
require "rails_helper"

describe "User" do
  describe "first_name" do
    it "is the first part of the name" do
      user = build(:user, name: "John Q User")

      expect(user.first_name).to eq("John")
    end
  end
end

This test is now a lot more clear at a glance, and that's a major goal of factory_bot. factory_bot provides the ideal optimization between hiding extraneous details from our test setup, and explicitly including the pertinent details within the spec setup.

Wiring it up

Let's play around with some of the basic factory_bot functionality in a console session.

Here is a simple factory definition:

FactoryBot.define do
  factory :user do
    name "John"
    email { "#{name}@example.com" }
    last_signed_in { 10.days.ago }
    password "password"
    github_username { "#{name}-github" }
  end
end

We're specifying here that we want a user's default name to be "John", and how to use the name to construct the rest of the attributes. (We'll get into more depth on defining factories later in the episode.)

To play around with it, we'll spin up a console and do some setup:

(development) main:0> require "factory_bot"
(development) main:0> require "./factories"
(development) main:0> include FactoryBot::Syntax::Methods

The last line allows us to say things like build(:user) and create(:user) rather than FactoryBot.build(:user) and FactoryBot.create(:user).

(This setup is not usually required while writing tests; it will be handled by the rails_helper file.)

Methods for building

build

Now we can quickly build a new filled out user with valid attributes with:

(development) main:0> build(:user, name: "James")

Notice that we can be explicit about the name, or any other attribute that is important for the test that we are writing at the moment, and the default will be overridden.

attributes_for and attributes_for_pair

We can also easily generate a hash of attributes, which is often handy (for example, in controller spec when you need some data to post):

(development) main:0> attributes_for(:user, name: "James")

Similarly, for each of the methods in factory_bot, there is an _pair and _list variant that will give you multiple objects:

(development) main:0> attributes_for_pair(:user, name: "James")

In this case, they are largely identical, since we don't have any dynamic or sequential data -- but we'll see soon how we can do that, and how it makes creating multiple variants of an object a breeze.

build_stubbed

One of our favorite methods is build_stubbed:

(development) main:0> build_stubbed(:user)

This is a little different than build, in that the object acts as though it has been persisted to the database, without actually touching the database; and it will even build_stubbed objects for any associations that we define in the factory as well. Again, there are also build_stubbed_pair and build_stubbed_list methods.

Methods for defining

Now let's have a closer look at the methods we can use to define our factories.

Dependent attributes

We've already encountered the first nice feature: dependent attributes. This allows us to, for example, have attributes like email and github_username which are dependent on name:

factory :user do
  name "John"
  email { "#{name}@example.com" }
  github_username { "#{name}-github" }
end

This behavior works even if we pass in a custom name, all of these attributes will be custom as well, accordingly.

Lazy evaluation

Another important thing to note is the lazy evaluation of these attributes; rather than using a value for the attribute, we pass a block which will be evaluated on demand. This is particularly important for time values:

# Good
last_signed_in { 10.days.ago } # lazily evaluated
password "password"            # not lazily evaluated

If we had instead not used the block,

last_signed_in 10.days.ago # not fine
password "password"        # fine

then that value would be initialized when the factories file is read, and static for all factories created.

Sequences

Another very commonly used feature is sequences, which makes it easy to create unique values for each attribute across multiple objects. Right now, our email attribute looks like this:

email { "#{name}@example.com" }

However, if we have two objects with the same name, their email addresses would also be the same. Often for fields that we validate to be unique (like email), this is not ideal.

Instead, we can use a sequence:

sequence(:email) { |n| "#{n}@example.com" }

The block variable n will receive a value that the sequence method guarantees will be unique to each factory. Take a peek at Upcase's factories file for lots more examples of sequences, including defining a standalone sequence that can be used across all factories and have guaranteed uniqueness.

Associations

Many times, we are testing not just the behavior of objects in isolation, but objects along with associated objects. factory_bot can help us quickly populate these associations as well.

For example, in Upcase, an invitation must belong to a team; and factory_bot makes it trivial to build and associate a team when building an invitation.

One thing to note is that if you FactoryBot.create the object, it will also FactoryBot.create the associated objects. If you FactoryBot.build the object, it will still FactoryBot.create the associated objects. This reasoning behind this has to do with satisfying validations.

If you really want to keep yourself isolated from the database, use FactoryBot.build_stubbed instead, which will also FactoryBot.build_stubbed associated objects.

Traits

One of the last features that we use a lot is traits, which are named additional arguments that you can pass when creating factory_bot objects. Again, to use Upcase as an example:

build_stubbed(:invitation, :accepted)

This will cause the :accepted trait of invitations to be invoked, which is a block of additional setup work:

trait :accepted do
  recipient factory: :user
  accepted_at { Time.now }
end

In the trait block, we are free to override or add additional behavior, so it's a nice way to dry up our actual specs and make them more explicit at the same time with a nicely named argument.

Vim plugin for navigating to factories

Despite factory_bot being better than fixtures at avoiding Mystery Guests, it can still be helpful from time to time to quickly navigate back and forth between specs and factories. Chris has (of course) created a Vim plugin to make this really easy. You can find all the details and install instructions on the Rfactory page on GitHub.

The big picture

That is a solid introduction to the most commonly used features of factory_bot. Now, let's talk about when we should and shouldn't be using it.

First of all, it's important to recognize that sometimes we simply don't need all of the power that factory_bot gives us; you don't always need to be persisting data to the database. While build_stubbed can mitigate many of these issues, unit tests, for example, can often be run as effectively and much more quickly by simply instantiating the object directly. (Read more about this in Josh's Giant Robots post.)

Multiple named factories for the same object

The whole point of factory_bot is to replace fixtures, and avoid hiding the complexity of test data in differently named fixtures. If you find yourself doing something similar, and having differently named factories for the same object, then you might want to reevaluate your approach or whether factories is a good choice.

You should have one factory per model, and the factory should set up a minimal viable object for you, allowing you to override whatever attributes are relevant to the test in question.

Use a single factories file

In the same vein, we recommend having a single factories file, although factory_bot doesn't require this. This is, again, to reinforce the idea that our factories should just be setting up simple and minimal baseline objects, and shouldn't contain a lot of complexity, and should thus fit into a single file. Upcase, for example, uses a single factories file.

Using FactoryBot to generate development data

Another place where we often want to quickly generate valid data is for priming our development database. factory_bot can be used to great effect here, and in fact thoughbot's Suspenders includes the boilerplate required to use it in the dev:prime rake task.

Note that there's a subtle difference between development data and seed data; db/seeds.rb should be reserved for static data that the application requires, like the fifty US states, and be intended to run in production. This is not a good use case for our factories, which are intended to evolve over time.

Conclusion

We hope that gives you a better sense of how to use factory_bot, and some situations when you should (and shouldn't) use it. For much more information, check out the very detailed FactoryBot Getting Started. We'll see you in the forums!