Module: RSpec::Core::Hooks

Included in:
Configuration, ExampleGroup, World
Defined in:
lib/rspec/core/hooks.rb

Defined Under Namespace

Modules: HookCollectionAliases, RegistersGlobals Classes: AfterAllHook, AfterHook, AroundHook, AroundHookCollection, BeforeHook, GroupHookCollection, Hook, HookCollection

Instance Method Summary collapse

Instance Method Details

#after(&block) ⇒ Object #after(scope, &block) ⇒ Object #after(scope, conditions, &block) ⇒ Object #after(conditions, &block) ⇒ Object Also known as: prepend_after

Declare a block of code to be run after each example (using :each) or once after all examples (using :all). See #before for more information about ordering.

Exceptions

after hooks are guaranteed to run even when there are exceptions in before hooks or examples. When an exception is raised in an after block, the exception is captured for later reporting, and subsequent after blocks are run.

Order

after hooks are stored in three scopes, which are run in order: :each, :all, and :suite. They can also be declared in several different places: RSpec.configure, a parent group, the current group. They are run in the following order:

after(:each) # declared in the current group
after(:each) # declared in a parent group
after(:each) # declared in RSpec.configure
after(:all)  # declared in the current group
after(:all)  # declared in a parent group
after(:all)  # declared in RSpec.configure

This is the reverse of the order in which before hooks are run. Similarly, if more than one after is declared within any one scope, they are run in reverse order of that in which they are declared.

Parameters:

  • scope (Symbol) —

    :each, :all, or :suite (defaults to :each)

  • conditions (Hash) —

    constrains this hook to examples matching these conditions e.g. after(:each, :ui => true) { ... } will only run with examples or groups declared with :ui => true.

See Also:



379
380
381
 
# File 'lib/rspec/core/hooks.rb', line 379

def after(*args, &block)
  register_hook :prepend, :after, *args, &block
end

#append_after(*args, &block) ⇒ Object

Adds block to the back of the list of after blocks in the same scope (:each, :all, or :suite).

See #after for scoping semantics.



389
390
391
 
# File 'lib/rspec/core/hooks.rb', line 389

def append_after(*args, &block)
  register_hook :append, :after, *args, &block
end

#around(&block) ⇒ Object #around(scope, &block) ⇒ Object #around(scope, conditions, &block) ⇒ Object #around(conditions, &block) ⇒ Object

Note:

the syntax of around is similar to that of before and after but the semantics are quite different. before and after hooks are run in the context of of the examples with which they are associated, whereas around hooks are actually responsible for running the examples. Consequently, around hooks do not have direct access to resources that are made available within the examples and their associated before and after hooks.

Note:

:each is the only supported scope.

Declare a block of code, parts of which will be run before and parts after the example. It is your responsibility to run the example:

around(:each) do |ex|
  # do some stuff before
  ex.run
  # do some stuff after
end

The yielded example aliases run with call, which lets you treat it like a Proc. This is especially handy when working with libaries that manage their own setup and teardown using a block or proc syntax, e.g.

around(:each) {|ex| Database.transaction(&ex)}
around(:each) {|ex| FakeFS(&ex)}

Parameters:

  • scope (Symbol) —

    :each (defaults to :each) present for syntax parity with before and after, but :each is the only supported value.

  • conditions (Hash) —

    constrains this hook to examples matching these conditions e.g. around(:each, :ui => true) { ... } will only run with examples or groups declared with :ui => true.

Yields:



437
438
439
 
# File 'lib/rspec/core/hooks.rb', line 437

def around(*args, &block)
  register_hook :prepend, :around, *args, &block
end

#before(&block) ⇒ Object #before(scope, &block) ⇒ Object #before(scope, conditions, &block) ⇒ Object #before(conditions, &block) ⇒ Object Also known as: append_before

Declare a block of code to be run before each example (using :each) or once before any example (using :all). These are usually declared directly in the ExampleGroup to which they apply, but they can also be shared across multiple groups.

You can also use before(:suite) to run a block of code before any example groups are run. This should be declared in RSpec.configure

Instance variables declared in before(:each) or before(:all) are accessible within each example.

Order

before hooks are stored in three scopes, which are run in order: :suite, :all, and :each. They can also be declared in several different places: RSpec.configure, a parent group, the current group. They are run in the following order:

before(:suite) # declared in RSpec.configure
before(:all)   # declared in RSpec.configure
before(:all)   # declared in a parent group
before(:all)   # declared in the current group
before(:each)  # declared in RSpec.configure
before(:each)  # declared in a parent group
before(:each)  # declared in the current group

If more than one before is declared within any one scope, they are run in the order in which they are declared.

Conditions

When you add a conditions hash to before(:each) or before(:all), RSpec will only apply that hook to groups or examples that match the conditions. e.g.

RSpec.configure do |config|
  config.before(:each, :authorized => true) do
     :authorized_user
  end
end

describe Something, :authorized => true do
  # the before hook will run in before each example in this group
end

describe SomethingElse do
  it "does something", :authorized => true do
    # the before hook will run before this example
  end

  it "does something else" do
    # the hook will not run before this example
  end
end

Warning: before(:suite, :with => :conditions)

The conditions hash is used to match against specific examples. Since before(:suite) is not run in relation to any specific example or group, conditions passed along with :suite are effectively ignored.

Exceptions

When an exception is raised in a before block, RSpec skips any subsequent before blocks and the example, but runs all of the after(:each) and after(:all) hooks.

Warning: implicit before blocks

before hooks can also be declared in shared contexts which get included implicitly either by you or by extension libraries. Since RSpec runs these in the order in which they are declared within each scope, load order matters, and can lead to confusing results when one before block depends on state that is prepared in another before block that gets run later.

Warning: before(:all)

It is very tempting to use before(:all) to speed things up, but we recommend that you avoid this as there are a number of gotchas, as well as things that simply don't work.

context

before(:all) is run in an example that is generated to provide group context for the block.

instance variables

Instance variables declared in before(:all) are shared across all the examples in the group. This means that each example can change the state of a shared object, resulting in an ordering dependency that can make it difficult to reason about failures.

unsupported rspec constructs

RSpec has several constructs that reset state between each example automatically. These are not intended for use from within before(:all):

  • let declarations
  • subject declarations
  • Any mocking, stubbing or test double declaration

other frameworks

Mock object frameworks and database transaction managers (like ActiveRecord) are typically designed around the idea of setting up before an example, running that one example, and then tearing down. This means that mocks and stubs can (sometimes) be declared in before(:all), but get torn down before the first real example is ever run.

You can create database-backed model objects in a before(:all) in rspec-rails, but it will not be wrapped in a transaction for you, so you are on your own to clean up in an after(:all) block.

Examples:

before(:each) declared in an ExampleGroup


describe Thing do
  before(:each) do
    @thing = Thing.new
  end

  it "does something" do
    # here you can access @thing
  end
end

before(:all) declared in an ExampleGroup


describe Parser do
  before(:all) do
    File.open(file_to_parse, 'w') do |f|
      f.write <<-CONTENT
        stuff in the file
      CONTENT
    end
  end

  it "parses the file" do
    Parser.parse(file_to_parse)
  end

  after(:all) do
    File.delete(file_to_parse)
  end
end

Parameters:

  • scope (Symbol) —

    :each, :all, or :suite (defaults to :each)

  • conditions (Hash) —

    constrains this hook to examples matching these conditions e.g. before(:each, :ui => true) { ... } will only run with examples or groups declared with :ui => true.

See Also:



317
318
319
 
# File 'lib/rspec/core/hooks.rb', line 317

def before(*args, &block)
  register_hook :append, :before, *args, &block
end

#prepend_before(*args, &block) ⇒ Object

Adds block to the front of the list of before blocks in the same scope (:each, :all, or :suite).

See #before for scoping semantics.



327
328
329
 
# File 'lib/rspec/core/hooks.rb', line 327

def prepend_before(*args, &block)
  register_hook :prepend, :before, *args, &block
end