Factory Girl Instruments

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

Table of content:

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

Purpose of this gem

Factory Girl 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 Girl Instruments help in these three aspects:

1. Slow test suites: Factory Girl 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 FactoryGirl.benchmark_all.

1. Deeper understanding of the database state: By tracing factory girl 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 FactoryGirl.trace { FactoryGirl.create(:user) }.

1. 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 FactoryGirl.trace { FactoryGirl.create(:user) } and observe the chain of calls.

Install

Add the following to your Gemfile:

gem 'factory_girl_instruments'

and run bundle install from your shell.

To install the gem manually from your shell, run:

gem install factory_girl_instruments

Documentation

Benchmarking one Factory Girl model

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

FactoryGirl.benchmark(:user)

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

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

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

Benchmarking all Factory Girl models

To collect benchmarking information from all Factory Girl models:

FactoryGirl.benchmark_all

To skip a factory, pass the :except options:

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

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

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

Tracing Factory Girl calls

To trace factory girl actions, wrap your call in the FactoryGirl.trace method:

FactoryGirl.trace do
  FactoryGirl.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:

FactoryGirl.trace(sql: false) do
  FactoryGirl.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.