enhanced_errors 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42e0ffde5da4be326f8b1d721652eed031f7bfb20a07d31a256d69c588a383b7
-  data.tar.gz: 5ef8303d0e6dd089253643b2abbf4aeef9a195831c946b2c92396390685e0a5b
+  metadata.gz: f9b5672dcc4f5583ab60b46799b58676f6ded0dbdec03a6dcd4637d53c5f9f77
+  data.tar.gz: c6a1faec38495fa64ce018c14bd10248ac38278dd41840137c7dbc6edc083661
 SHA512:
-  metadata.gz: cb553e2a7f127a2d7efbf77c25867a9706d500ffb70e6e48060cd42390cdd903f140d60a899ed61f0d3340697b3ec4458a704545aa4380dad928d64a76d9b158
-  data.tar.gz: 467e3f82cb5a170081b43f417dfa0b53c12df77a6a2614d13377d47227a00df0623d515a92707b52fd5cc8461f3862c16ae83c3aa264beff2ee63f88072299ce
+  metadata.gz: 00dde7064adf86a435200f8944139f7f6f042e3c797e3a97f38592e4c274b1131b54dbf6964069fa61a36aac5f7560cdeb6a62da3f0996d4f68416727de638d2
+  data.tar.gz: 17e332764e329e84a749621121eeb281e8c7e69b7b2c66dcb7248bfce81af6f9952d7ef5976e8bea0d72adcba483e5c9a564674256386b807a81a6629eec085c

data/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-**EnhancedErrors** is a pure Ruby gem that enhances exception messages by capturing and appending variables and their values from the scope where the error was raised.
+**EnhancedErrors** is a pure Ruby gem that enhances exceptions by capturing variables and their values from the scope where the error was raised.
 
 **EnhancedErrors** leverages Ruby's built-in [TracePoint](https://ruby-doc.org/core-3.1.0/TracePoint.html) feature to provide detailed context for exceptions, making debugging easier without significant performance overhead.
 
@@ -16,7 +16,10 @@ When an exception is raised, EnhancedErrors captures the surrounding context.  I
 require 'enhanced_errors'
 require 'awesome_print' # Optional, for better output
 
-EnhancedErrors.enhance!
+# Enable capturing of variables at exception at raise-time. The .captured_variables method
+# is added to all Exceptions and gets populated with in-scope variables and values on `raise`
+
+EnhancedErrors.enhance_exceptions!
 
 def foo
   begin
@@ -24,18 +27,19 @@ def foo
     @myinstance = 10
     foo = @myinstance / myvar
   rescue => e
-    puts e.message
+    puts e.captured_variables
   end
 end
 
 foo
-
 ```
 
 ##### Output:
 
 <img src="./doc/images/enhanced-error.png" style="height: 215px; width: 429px;"></img>
 <br>
+
+
 #### Enhanced Exception In Specs:
 
 ```ruby
@@ -60,6 +64,67 @@ end
 
 <img src="./doc/images/enhanced-spec.png" style="height: 369px; width: 712px;"></img>
 
+# RSpec Setup
+
+The simplest way to get started with EnhancedErrors is to use it for RSpec
+exception capturing. To get variable output into RSpec, the approach below
+enables capturing, but also gives nice output by formatting the failure message
+with the variable capture.
+
+The advantage of this approach is that it is only active for your spec runs.
+This approach is ideal for CI and local testing because it doesn't make
+any changes that should bleed through to production--it doesn't enhance
+exceptions except those that pass by during the RSpec run.
+
+```ruby
+
+RSpec.configure do |config|
+   
+  # add these config changes to your RSpec config to get variable messages
+  config.before(:suite) do
+    RSpec::Core::Example.prepend(Enhanced::Integrations::RSpecErrorFailureMessage)
+  end
+  
+  config.before(:example) do |_example|
+    EnhancedErrors.start_rspec_binding_capture
+  end
+
+  config.after(:example) do |example|
+    example.metadata[:expect_binding] = EnhancedErrors.stop_rspec_binding_capture
+  end
+  
+end
+
+```
+
+## Minitest
+
+Untested as of yet, but enhance_exceptions!(override_messages: true) is likely to work.
+
+If anyone wants to look into an integration implementation like RSpec, it would
+be welcomed. With a more targeted approach like the RSpec one, exceptions could be captured and 
+modified only during test time, like the RSpec approach. This would be advantageous as
+it wouldn't modify the exception message itself, but still makes the variable output available in
+test messages.
+
+## Enhancing .message
+
+EnhancedErrors can also append the captured variable description into the Exception's
+.message method output if the override_messages argument is true. 
+
+This can be very convenient as it lets you capture and diagnose 
+the context of totally unanticipated exceptions without modifying all your error handlers. 
+
+The downside to this approach is that if you have expectations in your tests/specs 
+around exception messages, those may break. Also, if you are doing something with the error messages, 
+like storing them in a database, they could be *much* longer and that may pose an issue.
+
+Ideally, use exception.captured_variables instead.
+
+```ruby
+EnhancedErrors.enhance_exceptions!(override_messages: true)
+```
+
 
 ## Features
 
@@ -116,28 +181,35 @@ $ gem install enhanced_errors
 
 ## Basic Usage
 
-To enable EnhancedErrors, call the `enhance!` method:
+To enable EnhancedErrors, call the `enhance_exceptions!` method:
 
 ```ruby
-# For a rails app, put this in an initializer, or spec_helper.rb
-# ex:  config/initializers/enhanced_errors.rb
-
+# For a rails app, you may put this in an initializer, or spec_helper.rb
+# ex:  config/initializers/enhanced.rb
+# you should immediately see nice errors with variables in your logs
+ 
 require 'awesome_print' # Optional, for better output
-EnhancedErrors.enhance!
+EnhancedErrors.enhance_exceptions!(override_messages: true)
 
-# -> now your error messages will have variables and their values appended to them.
 
 ```
 
-This activates the TracePoint to start capturing exceptions and their surrounding context.
+The approach above activates the TracePoint to start capturing exceptions and their surrounding context.
+It also overrides the .message to have the variables.
 
+If modifying your exception handlers is an option, it is better *not* to use
+override_messages: true, but instead just use the exception.captured_variables, which is
+a string describing what was found, that is available regardless. 
+
+Note that a minimalistic approach is taken to generating the string--if no qualifying variables were present, you won't see any message!
 
 ### Configuration Options
 
-You can pass configuration options to `enhance!`:
+You can pass configuration options to `enhance_exceptions!`:
 
 ```ruby
-EnhancedErrors.enhance!(enabled: true, max_length: 2000) do
+
+EnhancedErrors.enhance_exceptions!(enabled: true, max_length: 2000) do
   # Additional configuration here
   add_to_skip_list :@instance_variable_to_skip, :local_to_skip
 end
@@ -145,7 +217,7 @@ end
 ```
 - `add_to_skip_list`: Variables to ignore, as symbols. ex:  :@instance_variable_to_skip, :local_to_skip`
 - `enabled`: Enables or disables the enhancement (default: `true`).
-- `max_length`: Sets the maximum length of the enhanced message (default: `2500`).
+- `max_length`: Sets the maximum length of the captured_variables string (default: `2500`).
 
 Currently, the first `raise` exception binding is presented. 
 This may be changed in the future to allow more binding data to be presented.
@@ -236,7 +308,7 @@ end
 
 #### Using `on_format`
 
-`on_format` is the last stop for the message string that will be appended to `exception.message`.
+`on_format` is the last stop for the message string that will be `exception.captured_variables`.
 
 Here it can be encrypted, rewritten, or otherwise modified.
 
@@ -257,7 +329,7 @@ You can add additional variables to the skip list as needed:
 
 ```ruby
  
-EnhancedErrors.enhance! do
+EnhancedErrors.enhance_exceptions! do
   add_to_skip_list :@variable_to_skip
 end
 
@@ -271,15 +343,11 @@ The skip list is pre-populated with common variables to exclude and can be exten
 These exceptions are always ignored:
 
 ```ruby
-SystemExit,
-NoMemoryError,
-SignalException,
-Interrupt,
-ScriptError,
-LoadError,
-NotImplementedError,
-SyntaxError,
-SystemStackError
+SystemExit NoMemoryError SignalException Interrupt
+ScriptError LoadError NotImplementedError SyntaxError
+RSpec::Expectations::ExpectationNotMetError
+RSpec::Matchers::BuiltIn::RaiseError
+SystemStackError Psych::BadAlias
 ```
 
 While this is close to "Things that don't descend from StandardError", it's not exactly that.
@@ -299,7 +367,6 @@ EnhancedErrors supports different capture levels to control the verbosity of the
 The info mode is recommended.
 
 
-
 ### Capture Types
 
 EnhancedErrors differentiates between two types of capture events:
@@ -307,8 +374,9 @@ EnhancedErrors differentiates between two types of capture events:
 - **`raise`**: Captures the context when an exception is initially raised.
 - **`rescue`**: Captures the context when an exception is last rescued.
 
-**Default Behavior**: By default, EnhancedErrors returns the first `raise` and the last `rescue` event for each exception. 
+**Default Behavior**: By default, EnhancedErrors starts with rescue capture off.
 The `rescue` exception is only available in Ruby 3.2+ as it was added to TracePoint events in Ruby 3.2.
+If enabled, it returns the first `raise` and the last `rescue` event for each exception. 
 
 
 ### Example: Redacting Sensitive Information
@@ -338,8 +406,13 @@ When an exception is raised or rescued, it captures:
 
 The captured data includes a `capture_event` field indicating whether the data was captured during a `raise` or `rescue` event. By default, EnhancedErrors returns the first `raise` and the last `rescue` event for each exception, providing a clear trace of the exception lifecycle.
 
-The captured data is then appended to the exception's message, providing rich context for debugging.
+The captured data is available in .captured_variables, to provide context for debugging.
 
+* EnhancedErrors does not persist captured data--it only keep it in memory for the lifetime of the exception.
+* There are benchmarks around Tracepoint in the benchmark folder. Targeted tracepoints
+seem to be very cheap--as in, you can hit them ten thousand+ times a second
+without heavy overhead.
+* 
 
 ## Awesome Print
 
@@ -353,6 +426,7 @@ if you want to use it.
 gem 'awesome_print'
 ```
 
+
 ## Alternatives
 
 Why not use:
@@ -384,8 +458,7 @@ Ruby's TracePoint binding capture very narrowly with no other C API or dependenc
 
 - **TBD**: Memory considerations. This does capture data when an exception happens. EnhancedErrors hides under the bed when it sees **NoMemoryError**.
 
-- **Goal: Production Safety**: The gem is designed to, once vetted, be safe for production use, giving you valuable insights without compromising performance.
-I suggest letting it get well-vetted before making the leap and testing it for both performance and memory under load internally, as well.
+- **Goal: Production Safety**: The gem is designed to, eventually, be made safe for production use, giving you valuable insights without compromising performance.
 I would not enable it in production *yet*.
 
 ## Contributing

data/benchmark/benchmark.rb

@@ -1,5 +1,5 @@
 require 'benchmark'
-require_relative '../lib/enhanced_errors' # Adjust the path if necessary
+require_relative '../lib/enhanced/enhanced' # Adjust the path if necessary
 
 # Define the number of iterations
 ITERATIONS = 10_000
@@ -13,7 +13,7 @@ def calculate_cost(time_in_seconds)
 end
 
 def with_enhanced_errors
-  EnhancedErrors.enhance!(debug: false)
+  EnhancedErrors.enhance_exceptions!(debug: false)
   ITERATIONS.times do
     begin
       foo = 'bar'
@@ -38,7 +38,7 @@ def without_enhanced_errors
 end
 
 def when_capture_only_regexp_matched
-  EnhancedErrors.enhance!(debug: false) do
+  EnhancedErrors.enhance_exceptions!(debug: false) do
     eligible_for_capture { |exception| !!/Boo/.match(exception.class.to_s) }
   end
 
@@ -54,7 +54,7 @@ def when_capture_only_regexp_matched
 end
 
 def when_capture_only_regexp_did_not_match
-  EnhancedErrors.enhance!(debug: false) do
+  EnhancedErrors.enhance_exceptions!(debug: false) do
     eligible_for_capture { |exception| !!/Baz/.match(exception.class.to_s) }
   end
 

data/benchmark/stackprofile.rb

@@ -1,10 +1,10 @@
 require 'stackprof'
-require_relative '../lib/enhanced_errors' # Adjust the path if necessary
+require_relative '../lib/enhanced/enhanced' # Adjust the path if necessary
 
 # gem install stackprof
 
 # adjust path as needed
-# ruby ./lib/core_ext/enhanced_errors/benchmark/stackprofile.rb
+# ruby ./lib/core_ext/enhanced/benchmark/stackprofile.rb
 # dumps to current folder. read the stackprof dump:
 # stackprof stackprof.dump
 
@@ -12,7 +12,7 @@ require_relative '../lib/enhanced_errors' # Adjust the path if necessary
 ITERATIONS = 10_000
 
 def run_with_enhanced_errors
-  EnhancedErrors.enhance!(debug: false)
+  EnhancedErrors.enhance_exceptions!(debug: false, override_messages: true)
   ITERATIONS.times do
     begin
       raise 'Test exception with EnhancedErrors'

data/enhanced_errors.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name = "enhanced_errors"
-  spec.version = "1.0.0"
+  spec.version = "2.0.0"
   spec.authors = ["Eric Beland"]
 
   spec.summary = "Automatically enhance your errors with messages containing variable values from the moment they were raised."
@@ -23,5 +23,5 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "awesome_print", "~> 1.0"
   spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "yard", "> 0.9"
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

data/examples/demo_spec.rb

@@ -0,0 +1,32 @@
+# spec/enhanced_errors_spec.rb
+
+require_relative '../lib/enhanced_errors'
+require_relative '../spec/spec_helper'
+
+RSpec.describe 'Demo' do
+  let(:baz) { 'bee'}
+
+  before do
+    @yo = 'sup'
+  end
+
+  it 'does something' do
+    foo = 'bar'
+    baz
+    expect(false).to eq(true)
+  end
+
+  it 'does something else' do
+    something = 'else'
+    expect(false).to eq(true)
+  end
+
+  it 'passes fine' do
+    expect(true).to eq(true)
+  end
+
+  it 'works if it raises an errors' do
+    hi = 'there'
+    raise StandardError.new('crud')
+  end
+end

data/examples/division_by_zero_example.rb

@@ -1,7 +1,7 @@
 require './lib/enhanced_errors'
 require 'awesome_print' # Optional, for better output
 
-EnhancedErrors.enhance!
+EnhancedErrors.enhance_exceptions!(override_messages: true, capture_events: [:raise, :rescue])
 
 def foo
   begin
@@ -20,7 +20,7 @@ end
 def boo
     seeme = 'youshould'
     baz
-  rescue => e
+rescue Exception => e
     puts e.message
 end
 

data/examples/example_spec.rb

@@ -7,7 +7,7 @@ require_relative '../lib/enhanced_errors'
 
 RSpec.describe 'Neo' do
   before(:each) do
-    EnhancedErrors.enhance!
+    EnhancedErrors.enhance_exceptions!(override_messages: true)
   end
 
   describe 'sees through' do
@@ -25,3 +25,23 @@ RSpec.describe 'Neo' do
     end
   end
 end
+
+# Note:
+# The approach above is unlikely to work in large codebases where there are many
+# exception-based specs that verify exception messages.
+#
+# Instead, take this (recommended) approach:
+#
+# RSpec.configure do |config|
+#   config.before(:suite) do
+#     RSpec::Core::Example.prepend(Enhanced::Integrations::RSpecErrorFailureMessage)
+#   end
+#
+#   config.before(:example) do |_example|
+#     EnhancedErrors.start_rspec_binding_capture
+#   end
+#
+#   config.after(:example) do |example|
+#     example.metadata[:expect_binding] = EnhancedErrors.stop_rspec_binding_capture
+#   end
+# end

data/lib/enhanced/colors.rb

@@ -0,0 +1,30 @@
+module Enhanced
+  class Colors
+    COLORS = { red: 31, green: 32, yellow: 33, blue: 34, purple: 35, cyan: 36, white: 0 }
+
+    class << self
+      def enabled?
+        @enabled
+      end
+
+      def enabled=(value)
+        @enabled = value
+      end
+
+      def color(num, string)
+        @enabled ? "#{code(num)}#{string}#{code(0)}" : string
+      end
+
+      def code(num)
+        "\e[#{num}m"
+      end
+
+      COLORS.each do |color, code|
+        define_method(color) do |str|
+          color(COLORS[color], str)
+        end
+      end
+    end
+  end
+
+end

data/lib/enhanced/exception.rb

@@ -0,0 +1,45 @@
+# exception.rb
+
+class Exception
+  def captured_variables
+    if binding_infos.any?
+      bindings_of_interest = select_binding_infos
+      EnhancedErrors.format(bindings_of_interest)
+    else
+      ''
+    end
+  rescue
+    ''
+  end
+
+  def binding_infos
+    @binding_infos ||= []
+  end
+
+  private
+
+  def select_binding_infos
+    # Preference:
+    # 1. First 'raise' binding that isn't from a library (gem).
+    # 2. If none, the first binding.
+    # 3. The last 'rescue' binding if available.
+
+    bindings_of_interest = []
+
+    first_app_raise = binding_infos.find do |info|
+      info[:capture_event] == 'raise' && !info[:library]
+    end
+    bindings_of_interest << first_app_raise if first_app_raise
+
+    if bindings_of_interest.empty? && binding_infos.first
+      bindings_of_interest << binding_infos.first
+    end
+
+    last_rescue = binding_infos.reverse.find do |info|
+      info[:capture_event] == 'rescue'
+    end
+    bindings_of_interest << last_rescue if last_rescue
+
+    bindings_of_interest.compact
+  end
+end

data/lib/enhanced/integrations/rspec_error_failure_message.rb

@@ -0,0 +1,13 @@
+module Enhanced
+  module Integrations
+    module RSpecErrorFailureMessage
+      def execution_result
+        result = super
+        if result.exception
+          EnhancedErrors.override_exception_message(result.exception, self.metadata[:expect_binding])
+        end
+        result
+      end
+    end
+  end
+end