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:
-
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
. -
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) }
. -
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.