Module: RSpec::Core::Hooks

Included in:
Configuration, ExampleGroup
Defined in:
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/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.

Defined Under Namespace

Classes: AfterContextHook, AfterHook, AroundHook, BeforeHook, Hook, HookCollections

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

Note:

The ‘:example` and `:context` scopes are also available as `:each` and `:all`, respectively. Use whichever you prefer.

Note:

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.

Overloads:

  • #after(scope, &block) ⇒ Object

    Parameters:

    • scope (Symbol) —

      ‘:example`, `:context`, or `:suite` (defaults to `:example`)

  • #after(scope, *conditions, &block) ⇒ Object

    Parameters:

    • scope (Symbol) —

      ‘:example`, `:context`, or `:suite` (defaults to `:example`)

    • conditions (Array<Symbol>, Hash) —

      constrains this hook to examples matching these conditions e.g. ‘after(:example, :ui => true) { … }` will only run with examples or groups declared with `:ui => true`. Symbols will be transformed into hash entries with `true` values.

  • #after(conditions, &block) ⇒ Object

    Parameters:

    • conditions (Hash) —

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

See Also:



277
278
279
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/hooks.rb', line 277

def after(*args, &block)
  hooks.register :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 (`:example`, `:context`, or `:suite`).

See #after for scoping semantics.



287
288
289
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/hooks.rb', line 287

def append_after(*args, &block)
  hooks.register :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 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:

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

Overloads:

  • #around(scope, &block) ⇒ Object

    Parameters:

    • scope (Symbol) —

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

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

    Parameters:

    • scope (Symbol) —

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

    • conditions (Array<Symbol>, Hash) —

      constrains this hook to examples matching these conditions e.g. ‘around(:example, :ui => true) { … }` will only run with examples or groups declared with `:ui => true`. Symbols will be transformed into hash entries with `true` values.

  • #around(conditions, &block) ⇒ Object

    Parameters:

    • conditions (Hash) —

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

Yields:



349
350
351
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/hooks.rb', line 349

def around(*args, &block)
  hooks.register :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

Note:

The ‘:example` and `:context` scopes are also available as `:each` and `:all`, respectively. Use whichever you prefer.

Note:

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

Examples:

before(:example) declared in an ExampleGroup


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

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

before(:context) declared in an ExampleGroup


RSpec.describe Parser do
  before(:context) 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(:context) do
    File.delete(file_to_parse)
  end
end

Overloads:

  • #before(scope, &block) ⇒ Object

    Parameters:

    • scope (Symbol) —

      ‘:example`, `:context`, or `:suite` (defaults to `:example`)

  • #before(scope, *conditions, &block) ⇒ Object

    Parameters:

    • scope (Symbol) —

      ‘:example`, `:context`, or `:suite` (defaults to `:example`)

    • conditions (Array<Symbol>, Hash) —

      constrains this hook to examples matching these conditions e.g. ‘before(:example, :ui => true) { … }` will only run with examples or groups declared with `:ui => true`. Symbols will be transformed into hash entries with `true` values.

  • #before(conditions, &block) ⇒ Object

    Parameters:

    • conditions (Hash) —

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

See Also:



200
201
202
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/hooks.rb', line 200

def before(*args, &block)
  hooks.register :append, :before, *args, &block
end

#hooks ⇒ Object

Holds the various registered hooks.



355
356
357
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/hooks.rb', line 355

def hooks
  @hooks ||= HookCollections.new(self, FilterableItemRepository::UpdateOptimized)
end

#prepend_before(*args, &block) ⇒ Object

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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/hooks.rb', line 210

def prepend_before(*args, &block)
  hooks.register :prepend, :before, *args, &block
end