Module: RSpec::Core::Hooks
- Included in:
- Configuration, ExampleGroup
- Defined in:
- lib/rspec/core/hooks.rb
Overview
Provides before
, after
and around
hooks as a means of
supporting common setup and teardown. This module is extended
onto ExampleGroup, making the methods available from any describe
or context
block and included in Configuration, making them
available off of the configuration object to define global setup
or teardown logic.
Instance Method Summary collapse
-
#after(*args, &block) ⇒ void
(also: #prepend_after)
Declare a block of code to be run after each example (using
:example
) or once after all examples n the context (using:context
). -
#append_after(*args, &block) ⇒ void
Adds
block
to the back of the list ofafter
blocks in the same scope (:example
,:context
, or:suite
). -
#around(*args) {|Example| ... } ⇒ void
Declare a block of code, parts of which will be run before and parts after the example.
-
#before(*args, &block) ⇒ void
(also: #append_before)
Declare a block of code to be run before each example (using
:example
) or once before any example (using:context
). -
#prepend_before(*args, &block) ⇒ void
Adds
block
to the front of the list ofbefore
blocks in the same scope (:example
,:context
, or:suite
).
Instance Method Details
#after(&block) ⇒ void #after(scope, &block) ⇒ void #after(scope, *conditions, &block) ⇒ void #after(conditions, &block) ⇒ void Also known as: prepend_after
The :example
and :context
scopes are also available as
:each
and :all
, respectively. Use whichever you prefer.
The :suite
scope is only supported for hooks registered on
RSpec.configuration
since they exist independently of any
example or example group.
Declare a block of code to be run after each example (using :example
)
or once after all examples n the context (using :context
). 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:
:example
, :context
, 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(:example) # Declared in the current group.
after(:example) # Declared in a parent group.
after(:example) # Declared in RSpec.configure.
after(:context) # Declared in the current group.
after(:context) # Declared in a parent group.
after(:context) # Declared in RSpec.configure.
after(:suite) # 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 example
group, they are run in reverse order of that in which they are declared.
Also around
hooks will run after any after
example hooks are
invoked but before any after
context hooks.
277 278 279 |
# File 'lib/rspec/core/hooks.rb', line 277 def after(*args, &block) hooks.register :prepend, :after, *args, &block end |
#append_after(*args, &block) ⇒ void
Adds block
to the back of the list of after
blocks in the same
scope (:example
, :context
, or :suite
).
See #after for scoping semantics.
287 288 289 |
# File 'lib/rspec/core/hooks.rb', line 287 def append_after(*args, &block) hooks.register :append, :after, *args, &block end |
#around(&block) ⇒ void #around(scope, &block) ⇒ void #around(scope, *conditions, &block) ⇒ void #around(conditions, &block) ⇒ void
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 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.
:example
/: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(:example) 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 libraries
that manage their own setup and teardown using a block or proc syntax,
e.g.
around(:example) {|ex| Database.transaction(&ex)}
around(:example) {|ex| FakeFS(&ex)}
Order
The around
hooks execute surrounding an example and its hooks.
This means after any before
context hooks, but before any before
example hooks, and similarly after any after
example hooks but before
any after
context hooks.
They are not a synonym for before
/after
.
349 350 351 |
# File 'lib/rspec/core/hooks.rb', line 349 def around(*args, &block) hooks.register :prepend, :around, *args, &block end |
#before(&block) ⇒ void #before(scope, &block) ⇒ void #before(scope, *conditions, &block) ⇒ void #before(conditions, &block) ⇒ void Also known as: append_before
The :example
and :context
scopes are also available as
:each
and :all
, respectively. Use whichever you prefer.
The :suite
scope is only supported for hooks registered on
RSpec.configuration
since they exist independently of any
example or example group.
Declare a block of code to be run before each example (using :example
)
or once before any example (using :context
). 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(:example)
or before(:context)
are accessible within each example.
Order
before
hooks are stored in three scopes, which are run in order:
:suite
, :context
, and :example
. 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(:context) # Declared in RSpec.configure.
before(:context) # Declared in a parent group.
before(:context) # Declared in the current group.
before(:example) # Declared in RSpec.configure.
before(:example) # Declared in a parent group.
before(:example) # Declared in the current group.
If more than one before
is declared within any one example group, they
are run in the order in which they are declared. Any around
hooks will
execute after before
context hooks but before any before
example
hook regardless of where they are declared.
Conditions
When you add a conditions hash to before(:example)
or
before(:context)
, RSpec will only apply that hook to groups or
examples that match the conditions. e.g.
RSpec.configure do |config|
config.before(:example, :authorized => true) do
log_in_as :authorized_user
end
end
RSpec.describe Something, :authorized => true do
# The before hook will run in before each example in this group.
end
RSpec.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
Note that filtered config :context
hooks can still be applied
to individual examples that have matching metadata. Just like
Ruby's object model is that every object has a singleton class
which has only a single instance, RSpec's model is that every
example has a singleton example group containing just the one
example.
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(:example)
and after(:context)
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(:context)
It is very tempting to use before(:context)
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(:context)
is run in an example that is generated to provide
group context for the block.
Instance variables
Instance variables declared in before(:context)
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(:context)
:
let
declarationssubject
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(:context)
, but get torn down before the first real example is
ever run.
You can create database-backed model objects in a before(:context)
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(:context)
block.
200 201 202 |
# File 'lib/rspec/core/hooks.rb', line 200 def before(*args, &block) hooks.register :append, :before, *args, &block end |
#prepend_before(*args, &block) ⇒ void
Adds block
to the front of the list of before
blocks in the same
scope (:example
, :context
, or :suite
).
See #before for scoping semantics.
210 211 212 |
# File 'lib/rspec/core/hooks.rb', line 210 def prepend_before(*args, &block) hooks.register :prepend, :before, *args, &block end |