Included Modules

Class Index [+]

Quicksearch

RSpec::Core::Hooks

Constants

SCOPES

Public Instance Methods

after(*args, &block) click to toggle source

@api public @overload after(&block) @overload after(scope, &block) @overload after(scope, conditions, &block) @overload after(conditions, &block)

@param [Symbol] scope `:each`, `:all`, or `:suite` (defaults to `:each`) @param [Hash] conditions

  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 # @see # @see ExampleGroup @see SharedContext @see SharedExampleGroup @see Configuration

Declare a block of code to be run after each example (using `:each`) or once after all examples (using `:all`). See [#](Hooks#before-instance_method) 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.

     # File lib/rspec/core/hooks.rb, line 330
330:       def after(*args, &block)
331:         scope, options = scope_and_options_from(*args)
332:         hooks[:after][scope].unshift block.extend(AfterHookExtension).with(options)
333:       end
Also aliased as: prepend_after
append_after(*args, &block) click to toggle source

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

See # for scoping semantics.

     # File lib/rspec/core/hooks.rb, line 341
341:       def append_after(*args, &block)
342:         scope, options = scope_and_options_from(*args)
343:         hooks[:after][scope] << block.extend(AfterHookExtension).with(options)
344:       end
append_before(*args, &block) click to toggle source
Alias for: before
around(*args, &block) click to toggle source

@api public @overload around(&block) @overload around(scope, &block) @overload around(scope, conditions, &block) @overload around(conditions, &block)

@param [Symbol] scope `:each` (defaults to `:each`)

  present for syntax parity with `before` and `after`, but `:each` is
  the only supported value.

@param [Hash] conditions

  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`.

@yield [Example] the example to run

@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)}
     # File lib/rspec/core/hooks.rb, line 390
390:       def around(*args, &block)
391:         scope, options = scope_and_options_from(*args)
392:         hooks[:around][scope].unshift block.extend(AroundHookExtension).with(options)
393:       end
around_each_hooks_for(example, initial_procsy=nil) click to toggle source

@private

     # File lib/rspec/core/hooks.rb, line 404
404:       def around_each_hooks_for(example, initial_procsy=nil)
405:         AroundHookCollection.new(ancestors.map {|a| a.hooks[:around][:each]}.flatten).for(example, initial_procsy)
406:       end
before(*args, &block) click to toggle source

@api public @overload before(&block) @overload before(scope, &block) @overload before(scope, conditions, &block) @overload before(conditions, &block)

@param [Symbol] scope `:each`, `:all`, or `:suite` (defaults to `:each`) @param [Hash] conditions

  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 # @see # @see ExampleGroup @see SharedContext @see SharedExampleGroup @see Configuration

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](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](../../RSpec#configure-class_method)

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
        log_in_as :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.

### 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.

@example before(:each) declared in an [ExampleGroup](ExampleGroup)

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

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

@example before(:all) declared in an [ExampleGroup](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
     # File lib/rspec/core/hooks.rb, line 266
266:       def before(*args, &block)
267:         scope, options = scope_and_options_from(*args)
268:         hooks[:before][scope] << block.extend(BeforeHookExtension).with(options)
269:       end
Also aliased as: append_before
hooks() click to toggle source

@private

     # File lib/rspec/core/hooks.rb, line 100
100:       def hooks
101:         @hooks ||= {
102:           :around => { :each => AroundHookCollection.new },
103:           :before => { :each => [], :all => [], :suite => HookCollection.new },
104:           :after =>  { :each => [], :all => [], :suite => HookCollection.new }
105:         }
106:       end
prepend_after(*args, &block) click to toggle source
Alias for: after
prepend_before(*args, &block) click to toggle source

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

See # for scoping semantics.

     # File lib/rspec/core/hooks.rb, line 277
277:       def prepend_before(*args, &block)
278:         scope, options = scope_and_options_from(*args)
279:         hooks[:before][scope].unshift block.extend(BeforeHookExtension).with(options)
280:       end
run_hook(hook, scope, example_or_group=ExampleGroup.new, initial_procsy=nil) click to toggle source

@private

Runs all of the blocks stored with the hook in the context of the example. If no example is provided, just calls the hook directly.

     # File lib/rspec/core/hooks.rb, line 399
399:       def run_hook(hook, scope, example_or_group=ExampleGroup.new, initial_procsy=nil)
400:         find_hook(hook, scope, example_or_group, initial_procsy).run
401:       end

Private Instance Methods

after_all_hooks_for(group) click to toggle source
     # File lib/rspec/core/hooks.rb, line 414
414:       def after_all_hooks_for(group)
415:         GroupHookCollection.new(hooks[:after][:all]).for(group)
416:       end
after_each_hooks_for(example) click to toggle source
     # File lib/rspec/core/hooks.rb, line 422
422:       def after_each_hooks_for(example)
423:         HookCollection.new(ancestors.map {|a| a.hooks[:after][:each]}.flatten).for(example)
424:       end
before_all_hooks_for(group) click to toggle source
     # File lib/rspec/core/hooks.rb, line 410
410:       def before_all_hooks_for(group)
411:         GroupHookCollection.new(hooks[:before][:all]).for(group)
412:       end
before_each_hooks_for(example) click to toggle source
     # File lib/rspec/core/hooks.rb, line 418
418:       def before_each_hooks_for(example)
419:         HookCollection.new(ancestors.reverse.map {|a| a.hooks[:before][:each]}.flatten).for(example)
420:       end
extract_scope_from(args) click to toggle source
     # File lib/rspec/core/hooks.rb, line 449
449:       def extract_scope_from(args)
450:         if SCOPES.include?(args.first)
451:           args.shift
452:         elsif args.any? { |a| a.is_a?(Symbol) }
453:           raise ArgumentError.new("You must explicitly give a scope (:each, :all, or :suite) when using symbols as metadata for a hook.")
454:         else
455:           :each
456:         end
457:       end
find_hook(hook, scope, example_or_group, initial_procsy) click to toggle source
     # File lib/rspec/core/hooks.rb, line 426
426:       def find_hook(hook, scope, example_or_group, initial_procsy)
427:         case [hook, scope]
428:         when [:before, :all]
429:           before_all_hooks_for(example_or_group)
430:         when [:after, :all]
431:           after_all_hooks_for(example_or_group)
432:         when [:around, :each]
433:           around_each_hooks_for(example_or_group, initial_procsy)
434:         when [:before, :each]
435:           before_each_hooks_for(example_or_group)
436:         when [:after, :each]
437:           after_each_hooks_for(example_or_group)
438:         when [:before, :suite], [:after, :suite]
439:           hooks[hook][:suite].with(example_or_group)
440:         end
441:       end
scope_and_options_from(*args) click to toggle source
     # File lib/rspec/core/hooks.rb, line 445
445:       def scope_and_options_from(*args)
446:         return extract_scope_from(args), build_metadata_hash_from(args)
447:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.