test-prof 0.4.9 → 0.5.0.pre1

data/guides/before_all.md

@@ -1,98 +0,0 @@
-# Before All
-
-Rails has a great feature – `transactional_tests`, i.e. running each example within a transaction which is roll-backed in the end.
-
-Thus no example polutes global database state.
-
-But what if have a lot of examples with a common setup?
-
-Of course, we can do something like this:
-
-```ruby
-describe BeatleWeightedSearchQuery do
-  before(:each) do
-    @paul = create(:beatle, name: 'Paul')
-    @ringo = create(:beatle, name: 'Ringo')
-    @george = create(:beatle, name: 'George')
-    @john = create(:beatle, name: 'John')
-  end
-
-  # and about 15 examples here
-end
-```
-
-Or you can try `before(:all)`:
-
-```ruby
-describe BeatleWeightedSearchQuery do
-  before(:all) do
-    @paul = create(:beatle, name: 'Paul')
-    # ...
-  end
-
-  # ...
-end
-```
-
-But then you have to deal with database cleaning, which can be either tricky or slow.
-
-There is a better option: we can wrap the whole example group into a transaction.
-And that's how `before_all` works:
-
-```ruby
-describe BeatleWeightedSearchQuery do
-  before_all do
-    @paul = create(:beatle, name: 'Paul')
-    # ...
-  end
-
-  # ...
-end
-```
-
-That's all!
-
-## Instructions
-
-In your `spec_helper.rb`:
-
-```ruby
-require 'test_prof/recipes/rspec/before_all'
-```
-
-## Caveats
-
-If you modify objects generated within a `before_all` block in your examples, you maybe have to re-initiate them:
-
-
-```ruby
-before_all do
-  @user = create(:user)
-end
-
-let(:user) { @user }
-
-it 'when user is admin' do
-  # we modified our object in-place!
-  user.update!(role: 1)
-  expect(user).to be_admin
-end
-
-it 'when user is regular' do
-  # now @user's state depends on the order of specs!
-  expect(user).not_to be_admin
-end
-```
-
-The easiest way to solve this is to reload record for every example (it's still much faster than creating a new one):
-
-
-```ruby
-before_all do
-  @user = create(:user)
-end
-
-# Note, that @user.reload may not be enough,
-# 'cause it doesn't reset associations
-let(:user) { User.find(@user.id) }
-```

data/guides/event_prof.md

@@ -1,177 +0,0 @@
-# EventProf
-
-EventProf collects instrumentation (such as ActiveSupport::Notifications) metrics during your test suite run.
-
-It works very similar to `rspec --profile` but can track arbitrary events.
-
-Example output:
-
-```sh
-[TEST PROF INFO] EventProf results for sql.active_record
-
-Total time: 00:00.256
-Total events: 1031
-
-Top 5 slowest suites (by time):
-
-AnswersController (./spec/controllers/answers_controller_spec.rb:3) – 00:00.119 (549 / 20)
-QuestionsController (./spec/controllers/questions_controller_spec.rb:3) – 00:00.105 (360 / 18)
-CommentsController (./spec/controllers/comments_controller_spec.rb:3) – 00:00.032 (122 / 4)
-
-Top 5 slowest tests (by time):
-
-destroys question (./spec/controllers/questions_controller_spec.rb:38) – 00:00.022 (29)
-change comments count (./spec/controllers/comments_controller_spec.rb:7) – 00:00.011 (34)
-change Votes count (./spec/shared_examples/controllers/voted_examples.rb:23) – 00:00.008 (25)
-change Votes count (./spec/shared_examples/controllers/voted_examples.rb:23) – 00:00.008 (32)
-fails (./spec/shared_examples/controllers/invalid_examples.rb:3) – 00:00.007 (34)
-
-```
-
-## Instructions
-
-Currently, EventProf supports only ActiveSupport::Notifications
-
-To activate EventProf with:
-
-### RSpec
-
-Use `EVENT_PROF` environment variable set to event name:
-
-```sh
-# Collect SQL queries stats for every suite and example
-EVENT_PROF='sql.active_record' rspec ...
-```
-
-### Minitest
-
-Use `EVENT_PROF` environment variable set to event name:
-
-```sh
-# Collect SQL queries stats for every suite and example
-EVENT_PROF='sql.active_record' rake test
-```
-or use CLI options as well:
-
-```sh
-# Run a specific file using CLI option
-ruby test/my_super_test.rb --event-prof=sql.active_record
-
-# Show the list of possible options:
-ruby test/my_super_test.rb --help
-```
-
-### Using with Minitest::Reporters
-
-If you're using `Minitest::Reporters` in your project you have to explicitly declare it
-in your test helper file:
-
-```sh
-require 'minitest/reporters'
-Minitest::Reporters.use! [YOUR_FAVORITE_REPORTERS]
-```
-#### NOTICE
-When you have `minitest-reporters` installed as a gem but not declared in your `Gemfile`
-make sure to always prepend your test run command with `bundle exec` (but we sure that you always do it).
-Otherwise, you'll get an error caused by Minitest plugin system, which scans all the entries in the
-`$LOAD_PATH` for any `minitest/*_plugin.rb`, thus initialization of `minitest-reporters` plugin which is
-available in that case doesn't happens correctly.
-
-See [Rails guides](http://guides.rubyonrails.org/active_support_instrumentation.html)
-for the list of available events if you're using Rails.
-
-If you're using [rom-rb](http://rom-rb.org) you might be interested in profiling `'sql.rom'` event.
-
-### Configuration
-
-By default, EventProf collects information only about top-level groups (aka suites),
-but you can also profile individual examples. Just set the configuration option:
-
-```ruby
-TestProf::EventProf.configure do |config|
-  config.per_example = true
-end
-```
-
-Or provide the `EVENT_PROF_EXAMPLES=1` env variable.
-
-Another useful configuration parameter – `rank_by`. It's responsible for sorting stats –
-either by the time spent in the event or by the number of occurrences:
-
-```sh
-EVENT_PROF_RANK=count EVENT_PROF='instantiation.active_record' be rspec
-```
-
-See [event_prof.rb](https://github.com/palkan/test-prof/tree/master/lib/test_prof/event_prof.rb) for all available configuration options and their usage.
-
-## Using with RSpecStamp
-
-EventProf can be used with [RSpec Stamp](https://github.com/palkan/test-prof/tree/master/guides/rspec_stamp.md) to automatically mark _slow_ examples with custom tags. For example:
-
-```sh
-EVENT_PROF="sql.active_record" EVENT_PROF_STAMP="slow:sql" rspec ...
-```
-
-After running the command above the slowest example groups (and examples if configured) would be marked with the `slow: :sql` tag.
-
-## Custom Instrumentation
-
-To use EventProf with your instrumentation engine just complete the two following steps:
-
-- Add a wrapper for your instrumentation:
-
-
-```ruby
-# Wrapper over your instrumentation
-module MyEventsWrapper
-  # Should contain the only one method
-  def self.subscribe(event)
-    raise ArgumentError, 'Block is required!' unless block_given?
-
-    ::MyEvents.subscribe(event) do |start, finish, *|
-      yield (finish - start)
-    end
-  end
-end
-```
-
-- Set instrumenter in the config:
-
-
-```ruby
-TestProf::EventProf.configure do |config|
-  config.instrumenter = MyEventsWrapper
-end
-```
-
-## Custom Events
-
-### `"factory.create"`
-
-FactoryGirl provides its own instrumentation ('factory_girl.run_factory'); but there is a caveat – it fires an event every time a factory is used, even when we use factory for nested associations. Thus it's not possible to calculate the total time spent in factories due to the double calculation.
-
-EventProf comes with a little patch for FactoryGirl which provides instrumentation only for top-level `FactoryGirl.create` calls. It is loaded automatically if you use `"factory.create"` event:
-
-```sh
-EVENT_PROF=factory.create bundle exec rspec
-```
-
-### `"sidekiq.jobs"`
-
-Collects statistics about Sidekiq jobs that have been run inline:
-
-```sh
-EVENT_PROF=sidekiq.jobs bundle exec rspec
-```
-
-**NOTE**: automatically sets `rank_by` to `count` ('cause it doesn't make sense to collect the information about time spent – see below).
-
-### `"sidekiq.inline"`
-
-Collects statistics about Sidekiq jobs that have been run inline (excluding nested jobs):
-
-```sh
-EVENT_PROF=sidekiq.inline bundle exec rspec
-```
-
-Use this event to profile the time spent running Sidekiq jobs.

data/guides/factory_default.md

@@ -1,111 +0,0 @@
-# FactoryDefault
-
-_Factory Default_ aims to help you cope with _factory cascades_ (see [FactoryProf](https://github.com/palkan/test-prof/tree/master/guides/factory_prof.md)) by reusing associated records.
-
-**NOTE**. Only works with FactoryGirl/FactoryBot.
-
-It can be very useful when you're working on a typical SaaS application (or other hierarchical data).
-
-Consider an example. Assume we have the following factories:
-
-```ruby
-factory :account do
-end
-
-factory :user do
-  account
-end
-
-factory :project do
-  account
-  user
-end
-
-factory :task do
-  account
-  project
-  user
-end
-```
-
-And we want to test the `Task` model:
-
-```ruby
-describe 'PATCH #update' do
-  let(:task) { create(:task) }
-
-  it 'works' do
-    patch :update, id: task.id, task: { completed: 't' }
-    expect(response).to be_success
-  end
-
-  # ...
-end
-```
-
-How many users and accounts are created per example? Two and four respectively.
-
-And it breaks our logic (every object should belong to the same account).
-
-Typical workaround:
-
-```ruby
-describe 'PATCH #update' do
-  let(:account) { create(:account) }
-  let(:project) { create(:project, account: account) }
-  let(:task) { create(:task, project: project, account: account) }
-
-  it 'works' do
-    patch :update, id: task.id, task: { completed: 't' }
-    expect(response).to be_success
-  end
-end
-```
-
-That works. And there are some cons: it's a little bit verbose and error-prone (easy to forget something).
-
-Here is how we can deal with it using FactoryDefault:
-
-```ruby
-describe 'PATCH #update' do
-  let(:account) { create_default(:account) }
-  let(:project) { create_default(:project) }
-  let(:task) { create(:task) }
-
-  # and if we need more projects, users, tasks with the same parent record,
-  # we just write
-  let(:another_project) { create(:project) } # uses the same account
-  let(:another_task) { create(:task) } # uses the same account
-
-  it 'works' do
-    patch :update, id: task.id, task: { completed: 't' }
-    expect(response).to be_success
-  end
-end
-```
-
-**NOTE**. This feature introduces a bit of _magic_ to your tests, so use it with caution ('cause tests should be human-readable first). Good idea is to use defaults for top-level entities only (such as tenants in multi-tenancy apps).
-
-## Instructions
-
-In your `spec_helper.rb`:
-
-```ruby
-require 'test_prof/recipes/rspec/factory_default'
-```
-
-This adds two new methods to FactoryBot:
-
-- `FactoryBot#set_factory_default(factory, object)` – use the `object` as default for associations built with `factory`
-
-Example:
-
-```ruby
-let(:user) { create(:user) }
-
-before { FactoryBot.set_factory_default(:user, user) }
-```
-
-- `FactoryBot#create_default(factory, *args)` – is a shortcut for `create` + `set_factory_default`.
-
-**NOTE**. Defaults are cleaned up after each example.

data/guides/factory_doctor.md

@@ -1,119 +0,0 @@
-# Factory Doctor
-
-One common bad pattern that slows our tests down is unnecessary database manipulation. Consider a _bad_ example:
-
-```ruby
-it 'validates name presence' do
-  user = create(:user)
-  user.name = ''
-  expect(user).not_to be_valid
-end
-```
-
-Here we create a new user record, run all callbacks and validations and save it to the database. We don't need all these! Here is a _good_ example:
-
-```ruby
-it 'validates name presence' do
-  user = build_stubbed(:user)
-  user.name = ''
-  expect(user).not_to be_valid
-end
-```
-
-Read more about [`build_stubbed`](https://robots.thoughtbot.com/use-factory-girls-build-stubbed-for-a-faster-test).
-
-FactoryDoctor is a tool that helps you identify such _bad_ tests, i.e. tests that perform unnecessary database queries.
-
-Example output:
-
-```sh
-[TEST PROF INFO] FactoryDoctor report
-
-Total (potentially) bad examples: 2
-Total wasted time: 00:13.165
-
-User (./spec/models/user_spec.rb:3)
-  validates name (./spec/user_spec.rb:8) – 1 record created, 00:00.114
-  validates email (./spec/user_spec.rb:8) – 2 records created, 00:00.514
-```
-
-**NOTE**: have you noticed the "potentially" word? Unfortunately, FactoryDoctor is not a
-magician (it's still learning) and sometimes it produces false negatives and false positives too.
-
-Please, submit an [issue](https://github.com/palkan/test-prof/issues) if you found a case which makes FactoryDoctor fail.
-
-You can also tell FactoryDoctor to ignore specific examples/groups. Just add the `:fd_ignore` tag to it:
-
-```ruby
-# won't be reported as offense
-it 'is ignored', :fd_ignore do
-  user = create(:user)
-  user.name = ''
-  expect(user).not_to be_valid
-end
-```
-
-## Instructions
-
-Currently, FactoryDoctor works only with FactoryGirl/FactoryBot.
-
-## RSpec
-
-To activate FactoryDoctor use `FDOC` environment variable:
-
-```sh
-FDOC=1 rspec ...
-```
-
-## Using with RSpecStamp
-
-FactoryDoctor can be used with [RSpec Stamp](https://github.com/palkan/test-prof/tree/master/guides/rspec_stamp.md) to automatically mark _bad_ examples with custom tags. For example:
-
-```sh
-FDOC=1 FDOC_STAMP="fdoc:consider" rspec ...
-```
-
-After running the command above all _potentially_ bad examples would be marked with the `fdoc: :consider` tag.
-
-## Minitest
-
-To activate FactoryDoctor use `FDOC` environment variable:
-
-```sh
-FDOC=1 ruby ...
-```
-
-or use CLI option as shown below:
-
-```sh
-ruby ... --factory-doctor
-```
-
-The same option to force Factory Doctor to ignore specific examples is also available for Minitest.
-Just use `fd_ignore` inside your example:
-
-```ruby
-# won't be reported as offense
-it 'is ignored' do
-  fd_ignore
-
-  @user.name = ''
-  refute @user.valid?
-end
-```
-
-## Using with Minitest::Reporters
-
-If you're using `Minitest::Reporters` in your project you have to explicitly declare it
-in your test helper file:
-
-```sh
-require 'minitest/reporters'
-Minitest::Reporters.use! [YOUR_FAVORITE_REPORTERS]
-```
-#### NOTICE
-When you have `minitest-reporters` installed as a gem but not declared in your `Gemfile`
-make sure to always prepend your test run command with `bundle exec` (but we sure that you always do it).
-Otherwise, you'll get an error caused by Minitest plugin system, which scans all the entries in the
-`$LOAD_PATH` for any `minitest/*_plugin.rb`, thus initialization of `minitest-reporters` plugin which is
-available in that case doesn't happens correctly.