minitest-hooks

= minitest-hooks

minitest-hooks adds around and before_all/after_all/around_all hooks for Minitest. This allows you do things like run each suite of specs inside a database transaction, running each spec inside its own savepoint inside that transaction, which can significantly speed up testing for specs that share expensive database setup code.

= Installation

gem install minitest-hooks

= Source Code

Source code is available on GitHub at https://github.com/jeremyevans/minitest-hooks

= Usage

== In Specs (Minitest::Spec)

=== For all specs

require 'minitest/hooks/default'

=== For some specs

First, you need to require the library.

require 'minitest/hooks'

You can set the default for some specs to be Minitest::HooksSpec:

Minitest::Spec.register_spec_type(/something/, Minitest::HooksSpec)

Alternatively, you can include Minitest::Hooks in a specific spec class:

describe 'something' do include Minitest::Hooks end

=== before_all Hooks

To run code before any specs in the suite are executed, pass +:all+ to +before+:

describe 'something' do before(:all) do DB[:table].insert(:column=>1) end end

=== after_all Hooks

To run code after all specs in the suite are executed, pass +:all+ to +after+:

describe 'something' do after(:all) do DB[:table].delete end end

=== around Hooks

To run code around each spec in a suite, call +around+ with a block, and have the block call +super+:

describe 'something' do around do |&block| DB.transaction(:rollback=>:always, :savepoint=>true, :auto_savepoint=>true) do super(&block) end end end

=== around_all Hooks

To run code around all specs in a suite, call around(:all) with a block, and have the block call +super+:

describe 'something' do around(:all) do |&block| DB.transaction(:rollback=>:always) do super(&block) end end end

=== In Tests (Minitest::Test)

Create a subclass of Minitest::Test and include Minitest::Hooks, and have your test classes subclass from that subclass:

require 'minitest/hooks/test' class MyTest < Minitest::Test include Minitest::Hooks end

class TestSuite1 < MyTest end

You can just define the +before_all+, +after_all+, +around+, and +around_all+ methods, instead of using the spec DSL. Make sure to call super when overriding the methods.

class TestSuite1 < MyTest def before_all super DB[:table].insert(:column=>1) end

def after_all
  DB[:table].delete
  super
end

def around
  DB.transaction(:rollback=>:always, :savepoint=>true, :auto_savepoint=>true) do
    super
  end
end

def around_all
  DB.transaction(:rollback=>:always) do
    super
  end
end

end

= Behavior

== Hooks Just Define Methods

Just like the before/after hooks supported by minitest, all hooks supported by minitest-hooks just define methods on the spec class, there is no magic ("It's just ruby"). This has a couple of effects:

1. You cannot define multiple hooks of the same type in the same class. This is because you cannot have multiple methods with the same name in the same class. If you define a second hook of the same type in the same class, it will overwrite the previous hook, just like ruby's behavior if you define a method twice in the same class.

2. For around and around(:all) hooks, you should always call super. If you want a subclass around hook to run inside a superclass around hook, you need to call super in the subclass hook and run the code inside the block you pass to super, then call block.call somewhere inside the super block:

   describe "superclass" do around do |&block| some_outer_method do super(&block) end end

   describe "subclass" do
     around do |&block|
       super do
         some_inner_method do
           block.call
         end
       end
     end
   end
   

   end

   You do not need to call super for before(:all) or after(:all) hooks. Both before(:all) and after(:all) implicitly call super for you in the method they define, mirroring minitest's behavior for before and after hooks.

3. All hooks share state/instance variables. So any instance variables you set in before(:all), around(:all), or around are shared with the examples. Note that after(:all) will only see instance variables set in before(:all) or around(:all), it will not see instance variables set inside examples.

== All Spec Classes are Independent

The way minitest works, all spec classes are indepedent of other spec classes in terms of how and when they are executed, even spec classes that are subclasses of other spec classes. This means that for every spec class, the before(:all), after(:all), and around(:all) hooks for that class will be executed, even if they were defined in the spec's superclass and not in the spec class itself.

So if you have a spec superclass that uses before(:all), and a spec subclass for that superclass, the before(:all) in the spec superclass will be run twice, once in the context of an instance of the superclass, before executing the superclass's specs, and once in the context of an instance of the subclass, before executing the subclass's specs.

== Order of Operations

For each spec class, the around(:all) hooks are run first. Both before(:all) and after(:all) run inside around(:all). For each spec inside the spec class, around will be called, and before and after for each spec will be run inside around.

= License

MIT

= Author

Jeremy Evans [e-mail]