Include exception that raised failure in backtrace

Problem

Sometimes rspec-core does not display the underlying cause of an
exception that was raised.

Previously if an exception was raised there would sometimes be an
underlying cause of the exception. For example an exception that's
raised and rescued within an application causes the exception that
is displayed in the stacktrace.

```
class BrokenCode
  def self.shallow_method
    begin
      deep_method
    rescue
      raise "Something happened and I'm hiding that from the message
'because usability'."
    end
  end

  def self.deep_method
    raise 'The real cause for the failure is here!'
  end
end

RSpec.describe 'some broken code' do
  it 'works' do
    BrokenCode.shallow_method
  end
end
```

```
  1) some broken code works
     Failure/Error: raise "Something happened and I'm hiding that from
the message 'because usability'."
     RuntimeError:
       Something happened and I'm hiding that from the message 'because
usability'.
     # ./my_spec.rb:32:in `rescue in shallow_method'
     # ./my_spec.rb:29:in `shallow_method'
     # ./my_spec.rb:43:in `block (2 levels) in <top (required)>'
```

The above example demonstrates the problem, the stacktrace above is not
very clear as it does not show the initial exception that caused the
problem. This makes it difficult to fix their failing test.

Solution

Ruby 2.1 introduced `Exception#cause` which shows the underlying cause
of an exception if there is one. This commit uses that new Ruby method
to get the cause of an exception and display it in the stacktrace.

The stacktrace for the above code example would change to the below
example:

```
  1) some broken code works
     Failure/Error: raise "Something happened and I'm hiding that from
the message 'because usability'."
     RuntimeError:
       Something happened and I'm hiding that from the message 'because
usability'.
     # ./my_spec.rb:32:in `rescue in shallow_method'
     # ./my_spec.rb:29:in `shallow_method'
     # ./my_spec.rb:43:in `block (2 levels) in <top (required)>'
  ------------------
  --- Caused by: ---
     RuntimeError:
       The real cause for the failure is here!
     # ./my_spec.rb:37:in `deep_method'
     # ./my_spec.rb:30:in `shallow_method'
     # ./my_spec.rb:43:in `block (2 levels) in <top (required)>'
```

This makes it a lot easier to fix the main cause of the test failure.

Edge case

There may be a situation where lots of exceptions are captured and
bubble up the stacktrace. In that case I don't think we want to print out
the cause of every single exception. Instead what I propose we do is to
print out the first exception that caused the other exceptions to bubble
up the stack trace.

Author: mrageh

lib/rspec/core/formatters/exception_presenter.rb

@@ -31,8 +31,36 @@ def colorized_message_lines(colorizer=::RSpec::Core::Formatters::ConsoleCodes)
           end
         end
 
-        def formatted_backtrace
-          backtrace_formatter.format_backtrace(exception_backtrace, example.metadata)
+        def formatted_backtrace(exception=@exception)
+          backtrace_formatter.format_backtrace((exception.backtrace || []), example.metadata) +
+            formatted_cause(exception)
+        end
+
+        if RSpec::Support::RubyFeatures.supports_exception_cause?
+          def formatted_cause(exception)
+            last_cause = final_exception(exception)
+            cause = []
+
+            if exception.cause
+              cause << '------------------'
+              cause << '--- Caused by: ---'
+              cause << "#{exception_class_name(last_cause)}:" unless exception_class_name(last_cause) =~ /RSpec/
+
+              encoded_string(last_cause.message.to_s).split("\n").each do |line|
+                cause << "  #{line}"
+              end
+
+              cause << ("  #{backtrace_formatter.format_backtrace(last_cause.backtrace, example.metadata).first}")
+            end
+
+            cause
+          end
+        else
+          # :nocov:
+          def formatted_cause(_)
+            []
+          end
+          # :nocov:
         end
 
         def colorized_formatted_backtrace(colorizer=::RSpec::Core::Formatters::ConsoleCodes)
@@ -56,6 +84,14 @@ def failure_slash_error_line
 
       private
 
+        def final_exception(exception)
+          if exception.cause
+            final_exception(exception.cause)
+          else
+            exception
+          end
+        end
+
         def description_and_detail(colorizer, indentation)
           detail = detail_formatter.call(example, colorizer, indentation)
           return (description || detail) unless description && detail
@@ -81,7 +117,7 @@ def encoded_string(string)
           # :nocov:
         end
 
-        def exception_class_name
+        def exception_class_name(exception=@exception)
           name = exception.class.name.to_s
           name = "(anonymous error class)" if name == ''
           name

spec/rspec/core/formatters/exception_presenter_spec.rb

@@ -11,6 +11,7 @@ module RSpec::Core
     before do
       allow(example.execution_result).to receive(:exception) { exception }
       example.metadata[:absolute_file_path] = __FILE__
+      allow(exception).to receive(:cause) if RSpec::Support::RubyFeatures.supports_exception_cause?
     end
 
     describe "#fully_formatted" do
@@ -49,9 +50,9 @@ module RSpec::Core
       end
 
       it "allows the caller to specify additional indentation" do
-        presenter = Formatters::ExceptionPresenter.new(exception, example, :indentation => 4)
+        the_presenter = Formatters::ExceptionPresenter.new(exception, example, :indentation => 4)
 
-        expect(presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
+        expect(the_presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
           |
           |    1) Example
           |       Failure/Error: # The failure happened here!#{ encoding_check }
@@ -64,9 +65,9 @@ module RSpec::Core
       it 'passes the indentation on to the `:detail_formatter` lambda so it can align things' do
         detail_formatter = Proc.new { "Some Detail" }
 
-        presenter = Formatters::ExceptionPresenter.new(exception, example, :indentation => 4,
+        the_presenter = Formatters::ExceptionPresenter.new(exception, example, :indentation => 4,
                                                        :detail_formatter => detail_formatter)
-        expect(presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
+        expect(the_presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
           |
           |    1) Example
           |       Some Detail
@@ -78,11 +79,11 @@ module RSpec::Core
       end
 
       it 'allows the caller to omit the description' do
-        presenter = Formatters::ExceptionPresenter.new(exception, example,
+        the_presenter = Formatters::ExceptionPresenter.new(exception, example,
                                                        :detail_formatter => Proc.new { "Detail!" },
                                                        :description_formatter => Proc.new { })
 
-        expect(presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
+        expect(the_presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
           |
           |  1) Detail!
           |     Failure/Error: # The failure happened here!#{ encoding_check }
@@ -93,9 +94,9 @@ module RSpec::Core
       end
 
       it 'allows the failure/error line to be used as the description' do
-        presenter = Formatters::ExceptionPresenter.new(exception, example, :description_formatter => lambda { |p| p.failure_slash_error_line })
+        the_presenter = Formatters::ExceptionPresenter.new(exception, example, :description_formatter => lambda { |p| p.failure_slash_error_line })
 
-        expect(presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
+        expect(the_presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
           |
           |  1) Failure/Error: # The failure happened here!#{ encoding_check }
           |       Boom
@@ -105,13 +106,13 @@ module RSpec::Core
       end
 
       it 'allows a caller to specify extra details that are added to the bottom' do
-        presenter = Formatters::ExceptionPresenter.new(
+        the_presenter = Formatters::ExceptionPresenter.new(
           exception, example, :extra_detail_formatter => lambda do |failure_number, colorizer, indentation|
             "#{indentation}extra detail for failure: #{failure_number}\n"
           end
         )
 
-        expect(presenter.fully_formatted(2)).to eq(<<-EOS.gsub(/^ +\|/, ''))
+        expect(the_presenter.fully_formatted(2)).to eq(<<-EOS.gsub(/^ +\|/, ''))
           |
           |  2) Example
           |     Failure/Error: # The failure happened here!#{ encoding_check }
@@ -121,8 +122,35 @@ module RSpec::Core
           |     extra detail for failure: 2
         EOS
       end
-    end
 
+      let(:the_exception) { instance_double(Exception, :cause => second_exception, :message => "Boom\nBam", :backtrace => [ "#{__FILE__}:#{line_num}"]) }
+
+      let(:second_exception) do
+        instance_double(Exception, :cause => first_exception, :message => "Second\nexception", :backtrace => ["#{__FILE__}:#{__LINE__}"])
+      end
+
+      let(:first_exception) do
+        instance_double(Exception, :cause => nil, :message => "Real\nculprit", :backtrace => ["#{__FILE__}:#{__LINE__}"])
+      end
+
+      it 'includes the first exception that caused the failure', :if => RSpec::Support::RubyFeatures.supports_exception_cause? do
+        the_presenter = Formatters::ExceptionPresenter.new(the_exception, example)
+
+        expect(the_presenter.fully_formatted(1)).to eq(<<-EOS.gsub(/^ +\|/, ''))
+          |
+          |  1) Example
+          |     Failure/Error: # The failure happened here!#{ encoding_check }
+          |       Boom
+          |       Bam
+          |     # ./spec/rspec/core/formatters/exception_presenter_spec.rb:#{line_num}
+          |     # ------------------
+          |     # --- Caused by: ---
+          |     #   Real
+          |     #   culprit
+          |     #   ./spec/rspec/core/formatters/exception_presenter_spec.rb:133
+        EOS
+      end
+    end
     describe "#read_failed_line" do
       def read_failed_line
         presenter.send(:read_failed_line)

spec/rspec/core/notifications_spec.rb

@@ -18,6 +18,7 @@
   end
 
   it 'provides `colorized_formatted_backtrace`, which formats the backtrace and colorizes it' do
+    allow(exception).to receive(:cause) if RSpec::Support::RubyFeatures.supports_exception_cause?
     allow(RSpec.configuration).to receive(:color_enabled?).and_return(true)
     expect(notification.colorized_formatted_backtrace).to eq(["\e[36m# #{RSpec::Core::Metadata.relative_path(__FILE__)}:#{exception_line}\e[0m"])
   end