Permalink
Browse files

rdoc: more detail on before/after hooks

  • Loading branch information...
dchelimsky committed Dec 2, 2011
1 parent 5cf3ec4 commit c149f585df208ea56ce6fc0725eb0c018ff0dcd4
Showing with 53 additions and 15 deletions.
  1. +53 −15 lib/rspec/core/hooks.rb
View
@@ -99,10 +99,15 @@ def hooks
# @api public
# @overload before(&block)
# @overload before(scope, &block)
- # @overload before(scope, tags, &block)
- # @overload before(tags, &block)
+ # @overload before(scope, conditions, &block)
+ # @overload before(conditions, &block)
+ #
# @param [Symbol] scope `:each`, `:all`, or `:suite` (defaults to `:each`)
- # @param [Hash] tags
+ # @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 #after
# @see #around
# @see ExampleGroup
@@ -122,29 +127,62 @@ def hooks
# Instance variables declared in `before(:each)` or `before(:all)` are
# accessible within each example.
#
- # ### 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.
- #
# ### 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(: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
+ # 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

0 comments on commit c149f58

Please sign in to comment.