Factory Bot Instruments

Instruments for benchmarking, tracing, and debugging Factory Bot models.

Table of content:

• Setup
• Benchmark one Factory
• Benchmark all Factories
• Trace Factory Bot calls

Purpose of this gem

Factory Bot is probably the base of your Rails test suite, but how deeply you understand the models and the associations that are created in your tests?

Factory Bot Instruments help in these three aspects:

1. Slow test suites: Factory Bot is used for the bulk of tests in Rails. Even a small performance improvement in one of your factories can dramatically improve the speed of your overall test suite.

   Hint: Run FactoryBot.benchmark_all.

2. Deeper understanding of the database state: By tracing factory bot and SQL calls you can get a deeper understanding of what is actually created in your tests, helping you to debug the issues faster.

   Hint: Run FactoryBot.trace { FactoryBot.create(:user) }.

3. Find issues with missconfigured factories: When a factory is properly set up it is a bliss to work with it. However, if there is a hidden deep in the association chain debugging the created model can be a hellish experience.

   Hint: Run FactoryBot.trace { FactoryBot.create(:user) } and observe the chain of calls.

Install

Add the following to your Gemfile:

gem 'factory_bot_instruments'

and run bundle install from your shell.

To install the gem manually from your shell, run:

gem install factory_bot_instruments

Documentation

Benchmarking one Factory Bot model

If you have a user factory, you can benchmark it with:

FactoryBot.benchmark(:user)

By default, the FactoryBot.create(<model>) is called. You can pass :method to override this:

FactoryBot.benchmark(:user, :method => :build_stubbed)

The above snippet will call FactoryBot.build_stubbed(:user).

Benchmarking all Factory Bot models

To collect benchmarking information from all Factory Bot models:

FactoryBot.benchmark_all

To skip a factory, pass the :except options:

FactoryBot.benchmark_all(:except => [:user])

By default, benchmarks for FactoryBot.create(<model>), FactoryBot.build(<model>), FactoryBot.build_stubbed(<model>) are collected. You can override this by passing an array of methods:

FactoryBot.benchmark_all(:methods => [:create]) # benchmark only :create

Tracing Factory Bot calls

To trace factory Bot actions, wrap your call in the FactoryBot.trace method:

FactoryBot.trace do
  FactoryBot.create(:comment)
end

The above snippet will output the following tree:

┌ (start) create :comment
|  ┌ (start) create :user
|  |  (0.1ms)  begin transaction
|  |  (0.4ms)  INSERT INTO "users" ("name", "username") VALUES (?, ?)  [["name", "Peter Parker"], ["username", "spiderman"]]
|  |  (2.3ms)  commit transaction
|  └ (finish) create :user [0.010s]
|  ┌ (start) create :article
|  |  ┌ (start) create :user
|  |  |  (0.1ms)  begin transaction
|  |  |  (0.3ms)  INSERT INTO "users" ("name", "username") VALUES (?, ?)  [["name", "Peter Parker"], ["username", "spiderman"]]
|  |  |  (1.8ms)  commit transaction
|  |  └ (finish) create :user [0.007s]
|  |  (0.1ms)  begin transaction
|  |  (0.2ms)  INSERT INTO "articles" ("title", "content", "user_id") VALUES (?, ?, ?)  [["title", "New Article"], ["content", "article content"], ["user_id", "121"]]
|  |  (1.5ms)  commit transaction
|  └ (finish) create :article [0.021s]
|  (0.1ms)  begin transaction
|  (0.2ms)  INSERT INTO "comments" ("content", "user_id", "article_id") VALUES (?, ?, ?)  [["content", "First!"], ["user_id", "120"], ["article_id", "61"]]
|  (1.5ms)  commit transaction
└ (finish) create :comment [0.046s]

To trace without SQL logs, use the following:

FactoryBot.trace(sql: false) do
  FactoryBot.create(:comment)
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/shiroyasha/factory_girl_instruments. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.