From 0058c8e3f8c34ce489cc32ce5b9f2d33e5723247 Mon Sep 17 00:00:00 2001 From: Jon Rowe Date: Wed, 11 Sep 2019 22:09:03 +0100 Subject: [PATCH] Update docs for hooks specifying order of before/around/after --- features/hooks/around_hooks.feature | 3 +++ features/hooks/before_and_after_hooks.feature | 3 +++ lib/rspec/core/hooks.rb | 12 ++++++++++-- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/features/hooks/around_hooks.feature b/features/hooks/around_hooks.feature index 99a76d9224..748210c938 100644 --- a/features/hooks/around_hooks.feature +++ b/features/hooks/around_hooks.feature @@ -17,6 +17,9 @@ Feature: `around` hooks **WARNING:** Mock frameworks are set up and torn down within the context of running the example. You cannot interact with them directly in `around` hooks. + **WARNING:** `around` hooks will execute *after* any `before` hooks, and *before* + any `after` hooks regardless of the context they were defined in. + Scenario: Use the example as a proc within the block passed to `around()` Given a file named "example_spec.rb" with: """ruby diff --git a/features/hooks/before_and_after_hooks.feature b/features/hooks/before_and_after_hooks.feature index c1c9159e67..6110a9819e 100644 --- a/features/hooks/before_and_after_hooks.feature +++ b/features/hooks/before_and_after_hooks.feature @@ -29,6 +29,9 @@ Feature: `before` and `after` hooks **WARNING:** Mocks are only supported in `before(:example)`. + **WARNING:** `around` hooks will execute *after* any `before` hooks, and *before* + any `after` hooks regardless of the context they were defined in. + Note: the `:example` and `:context` scopes are also available as `:each` and `:all`, respectively. Use whichever you prefer. diff --git a/lib/rspec/core/hooks.rb b/lib/rspec/core/hooks.rb index d3acdabb9f..56c0be852d 100644 --- a/lib/rspec/core/hooks.rb +++ b/lib/rspec/core/hooks.rb @@ -60,7 +60,8 @@ module Hooks # before(:example) # 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. + # in the order in which they are declared. Any `around` hooks will execute + # later than any `before` hook regardless of scope. # # ### Conditions # @@ -261,7 +262,8 @@ def prepend_before(*args, &block) # # 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. + # they are run in reverse order of that in which they are declared. Also + # `around` hooks will all have run before any after hooks are invoked. # # @note The `:example` and `:context` scopes are also available as # `:each` and `:all`, respectively. Use whichever you prefer. @@ -329,6 +331,12 @@ def append_after(*args, &block) # around(:example) {|ex| Database.transaction(&ex)} # around(:example) {|ex| FakeFS(&ex)} # + # ### Order + # + # All `around` hooks execute immediately surrounding an example, this means + # that all `before` hooks will have run and no `after` hooks will have run yet. + # + # They are not a synonym for `before`/`after`. def around(*args, &block) hooks.register :prepend, :around, *args, &block end