Documentation needed that #after hooks are executed for pending/skipped/failed specs

[skalee]

Subject of the issue

This issue is purely about the documentation hosted on Relish.

after(:example) hooks are executed regardless example has failed, was skipped or whatever. I am pretty convinced that this is a correct behaviour, however it does not seem to be documented in https://relishapp.com/rspec/rspec-core/v/3-9/docs, particularly not in https://relishapp.com/rspec/rspec-core/v/3-9/docs/hooks/before-and-after-hooks, nor in https://relishapp.com/rspec/rspec-core/v/3-9/docs/pending-and-skipped-examples. Same for skipped/pending specs

Your environment

• Ruby version: 2.6.3p62
• rspec-core version: 3.9.0

Steps to reproduce

Given following spec file after_spec.rb:

require "rspec"

RSpec.describe(":after hook is run anyway") do
  before(:example) do
    raise "in before example"
  end

  after(:example) do
    raise "in after example"
  end

  example do
    raise "in example"
  end
end

When I run rspec after_spec.rb

I see:

Failures:

  1) :after hook is run anyway
     Got 0 failures and 2 other errors:

     1.1) Failure/Error: raise "in before example"

          RuntimeError:
            in before example
          # ./after_spec.rb:5:in `block (2 levels) in <top (required)>'

     1.2) Failure/Error: raise "in after example"

          RuntimeError:
            in after example
          # ./after_spec.rb:9:in `block (2 levels) in <top (required)>'

Finished in 0.00562 seconds (files took 0.57673 seconds to load)
1 example, 1 failure

Expected behavior documentation

1. It should be documented that :after hooks are executed despite any failures or errors in the example or respective before(:example) hooks.
2. It should be documented that :after hooks are executed for pending examples.

Actual behavior documentation

Is silent on that.

Can you do a pull request?

Yes, but my English may need some corrections.

[pirj]

Pull request is welcome!

[JonRowe]

A pending example is just a failing example thats expected to fail, feel free to add a scenario to https://relishapp.com/rspec/rspec-core/v/3-9/docs/hooks/before-and-after-hooks if you'd like to illustrate that hooks runs despite a failing example, it is kind of covered implicitly elsewhere but I agree it could be more specific.

[JonRowe]

Closed by #2715