enhanced_errors 2.0.5 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3897d29e868998ef225633f9f0f0f99a994b55563d65bff843ade348e7229bb9
-  data.tar.gz: 37f1db45f0c18c64846d396088f71bab2312b89da1a375b4d325309832983efc
+  metadata.gz: 03cd9eda304184a474e2cccf59199027d622d2a32f5b90e93f75a0d1dbed4530
+  data.tar.gz: 48d4974d2b53c00155a6768d22f814ce072fd0d407051fab955d72f156fa81cc
 SHA512:
-  metadata.gz: b156387888d9479f5d474808a922127fbfc5c6ed7035c6d8ef552dabca39b550655e191bfc6f0f11d64db36ded66fe03619cca7eaff2f5b725abb3d106f07d87
-  data.tar.gz: ce0fcadb20a8be1f0b53921cf990e5c458ce6ba1099dc5b9ceff1c8459ab82b707234bfbf964b10036a5b37a33b0248337d0289005b0f32c61933efa25ef44de
+  metadata.gz: 03c169ed6955512bd4ce743d9343199f4a0f833a3d663be47f366fe8be0a46b8b749fc7f6e326f07a008e16f26cfbed790f561829068e61eecb6510ae95a3b20
+  data.tar.gz: 38ef1f2cb5daa334fa067cdbffd873046e7936688556d1393a5e10a7e7992eb677e47b1fd6c91a97f2d511b76a5e8acd3bbcd4118505a5b4180c944c4627bf00

data/README.md

@@ -2,45 +2,13 @@
 
 ## Overview
 
-**EnhancedErrors** is a pure Ruby gem that enhances exceptions by capturing variables and their values from the scope where the error was raised.
+**EnhancedErrors** is a lightweight Ruby gem that enhances exceptions by capturing variables and their values from the scope where the exception 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.
 
-When an exception is raised, EnhancedErrors captures the surrounding context.  It works like this:
-<br>
-
-#### Enhanced Exception In Code:
-
-```ruby
-
-require 'enhanced_errors'
-require 'awesome_print' # Optional, for better output
-
-# 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
-    myvar = 0
-    @myinstance = 10
-    foo = @myinstance / myvar
-  rescue => e
-    puts e.captured_variables
-  end
-end
-
-foo
-```
+EnhancedErrors captures exception context using either a test-framework integration (RSpec/Minitest) or a global enhancement for runtime exceptions.
 
-##### Output:
-
-<img src="./doc/images/enhanced-error.png" style="height: 215px; width: 429px;"></img>
-<br>
-
-
-#### Enhanced Exception In Specs:
+### Enhanced Errors In RSpec:
 
 ```ruby
 describe 'sees through' do
@@ -64,60 +32,84 @@ 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.
+The RSpec test-time only approach constrained only to test-time.
+
+### RSpec Setup
+
+Use EnhancedErrors with RSpec for test-specific exception capturing, ideal for CI and local testing without impacting production.
 
 ```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
+    EnhancedErrors.override_exception_message(example.exception, EnhancedErrors.stop_rspec_binding_capture)
   end
-  
 end
+```
+
+<br>
+
+
+## MiniTest Setup
+
+```ruby
+require 'enhanced_errors'
+require 'enhanced/minitest_patch'
+
+# Once the patch is loaded, it should just work!
 
 ```
 
-## Minitest
+<br>
+
+### Enhanced Errors In Everyday Ruby Exceptions:
+
+```ruby
+
+require 'enhanced_errors'
+require 'awesome_print' # Optional, for better output
+
+# 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
+    myvar = 0
+    @myinstance = 10
+    foo = @myinstance / myvar
+  rescue => e
+    puts e.captured_variables
+  end
+end
 
-Untested as of yet, but enhance_exceptions!(override_messages: true) is likely to work.
+foo
+```
 
-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
+### Enhancing .message
 
-EnhancedErrors can also append the captured variable description into the Exception's
-.message method output if the override_messages argument is true. 
+EnhancedErrors can append the captured variable description onto every Exception's
+.message method with
+```ruby
+EnhancedErrors.enhance_exceptions(override_messages: 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. 
+This captures unanticipated exceptions without modifying all your error handlers. 
+This approach can be used to get detailed logs when problems happen in something like a cron-job.
 
-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.
+The tradeoff of this approach is that if you have expectations in your tests/specs around 
+exception messages, those may break. Also, if you are doing something like storing the errors
+in a database, they could be *much* longer and that may pose an issue on field lengths.
+Or if you are writing your logs to Datadog, New Relic, Splunk, etc, log messages for 
+errors will be longer, and you should consider what data/PII you are sharing.
 
 Ideally, use exception.captured_variables instead.
 
@@ -126,6 +118,13 @@ EnhancedErrors.enhance_exceptions!(override_messages: true)
 ```
 
 
+#### Output:
+
+<img src="./doc/images/enhanced-error.png" style="height: 215px; width: 429px;"></img>
+<br>
+
+
+
 ## Features
 
 - **Pure Ruby**: No external dependencies, C extensions, or C API calls.
@@ -138,26 +137,13 @@ EnhancedErrors.enhance_exceptions!(override_messages: true)
 - **No dependencies**:  EnhancedErrors does not ___require___ any dependencies--it uses [awesome_print](https://github.com/awesome-print/awesome_print) for nicer output if it is installed and available.
 - **Lightweight**: Minimal performance impact, as tracing is only active during exception raising.
 
-EnhancedErrors has a few big use-cases:
-
-* **Catch Data-driven bugs**. For example, if, while processing a 10 gig file, you get an error, you can't just re-run the code with a debugger.
-You also can't just print out all the data, because it's too big. You want to know what the data was the cause of the error.
-Ideally, without long instrument-re-run-fix loops. If your logging didn't capture the data, normally, you'd be stuck. 
-
-* **Debug** a complex application erroring deep in the stack when you can't tell where the error originates.
-
-* **Reduce MTTR** Reduce mean time to resolution.
-
-* **Faster CI -> Fix loop**. When a bug happens in CI, usually there's a step where you first reproduce it locally.
-  EnhancedErrors can help you skip that step.
+EnhancedErrors use-cases:
 
-* **Faster TDD**. In general, you can skip the add-instrumentation step and jump to the fix. Usually, you won't have to re-run to see an error.
-
-* **Heisenbugs** - bugs that disappear when you try to debug them. EnhancedErrors can help you capture the data that causes the bug before it disappears.
-
-* **Unknown Unknowns** - you can't pre-emptively log variables from failure cases you never imagined.
-
-* **Cron jobs** and **daemons** - when it fails for unknown reasons at 4am, check the log and fix--it probably has what you need. Note that 
+* Catch data-driven bugs without needing re-runs or extensive logging.
+* Debug deep-stack errors and reduce mean time to resolution (MTTR).
+* Handle CI failures faster by skipping reproduction steps.
+* Address elusive "Heisenbugs" by capturing error context preemptively.
+* Debug cron jobs and daemons with rich, failure-specific logs.
 
 ## Installation
 
@@ -194,14 +180,15 @@ EnhancedErrors.enhance_exceptions!(override_messages: true)
 
 ```
 
-The approach above activates the TracePoint to start capturing exceptions and their surrounding context.
-It also overrides the .message to have the variables.
+This captures all exceptions and their surrounding context.
+It also overrides the .message to display 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. 
+but instead just use the exception.captured_variables, which is
+a string describing what was found. 
 
-Note that a minimalistic approach is taken to generating the string--if no qualifying variables were present, you won't see any message!
+Note: a minimalistic approach is taken to generating the capture string.
+If no qualifying variables were present, you won't see any message additions!
 
 ### Configuration Options
 
@@ -219,9 +206,6 @@ end
 - `enabled`: Enables or disables the enhancement (default: `true`).
 - `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.
-
 
 ### Environment-Based Defaults
 
@@ -352,8 +336,8 @@ SystemStackError Psych::BadAlias
 
 While this is close to "Things that don't descend from StandardError", it's not exactly that.
 
-In Info mode, variables starting with @_ are also ignored.
-
+By default, many noisy instance variables are ignored in the default skip list.
+If you want to see every instance variable, you'll need to clear out the skip list.
 
 ### Capture Levels
 
@@ -412,7 +396,6 @@ The captured data is available in .captured_variables, to provide context for de
 * 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
 
@@ -433,28 +416,30 @@ Why not use:
 
 [binding_of_caller](https://github.com/banister/binding_of_caller) or [Pry](https://github.com/pry/pry) or [better_errors](https://github.com/BetterErrors/better_errors)?
 
-First off, these gems are, I cannot stress this enough, a-m-a-z-i-n-g!!! I use them every day--kudos to their creators and maintainers!
+First off, these gems are a-m-a-z-i-n-g!!! I use them every day--kudos to their creators and maintainers!
 
-This is intended for different use-cases. In sum, the goal of this gem is an every-day driver for __non-interactive__ variable inspection. 
+EnhancedErrors is intended as an every-day driver for __non-interactive__ variable inspection. 
 
-With EnhancedErrors is that I want extra details when I run into a problem I __didn't anticipate ahead of time__.
-To make that work, it has to be able to safely be 'on' all the time, and it has to gather the data in
-a way I naturally will see it without requiring extra preparation I obviously didn't know to do.
+I want extra details when I run into a problem I __didn't anticipate ahead of time__.
+To make that work, it has to be able to safely be 'on' ahead of time, and gather data in
+a way I naturally will retain without requiring extra preparation I obviously didn't know to do.
 
-- That won't interrupt CI, but also, that lets me know what happened without reproduction
-- That could, theoretically, also be fine in production (if data security, redaction, access, and encryption concerns were all addressed--Ok, big
-list, but another option is to selectively enable targeted capture)
+- EnhancedErrors won't interrupt CI, but it lets me know what happened _without_ reproduction steps
+- EnhancedErrors could, theoretically, also be fine in production (if data security, redaction, 
+PII, access, and encryption concerns were all addressed. 
+Big list, but another option is to selectively enable targeted capture.
 - Has decent performance characteristics
 - **Only** becomes active in exception raise/rescue scenarios
 
 This gem could have been implemented using binding_of_caller, or the gem it depends on, [debug_inspector](https://rubygems.org/gems/debug_inspector/versions/1.1.0?locale=en). 
-However, the recommendation is not to use those in production as they use C API extensions. This doesn't. This selectively uses 
-Ruby's TracePoint binding capture very narrowly with no other C API or dependencies, and only to target Exceptions--not to allow universal calls to the prior binding. It doesn't work as a debugger, but that also means it can, with care, operate safely in a narrow scope--becoming active only when exceptions are raised.
+However, the recommendation is not to use those in production as they use C API extensions. This doesn't. 
+EnhancedErrors selectively uses Ruby's TracePoint binding capture very narrowly with no other C API or dependencies, and only to target 
+Exceptions. It operates in a narrow scope--becoming active only when exceptions are raised.
 
 
 ## Performance Considerations
 
-- **Minimal Overhead**: Since TracePoint is only activated during exception raising and rescuing, the performance impact is negligible during normal operation. (Benchmark included)
+- **Small Overhead**: Since TracePoint is only activated during exception raising and rescuing, the performance impact is negligible during normal operation. (Benchmark included)
 
 - **TBD**: Memory considerations. This does capture data when an exception happens. EnhancedErrors hides under the bed when it sees **NoMemoryError**.
 

data/enhanced_errors.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name = "enhanced_errors"
-  spec.version = "2.0.5"
+  spec.version = "2.1.0"
   spec.authors = ["Eric Beland"]
 
   spec.summary = "Automatically enhance your errors with messages containing variable values from the moment they were raised."
@@ -21,7 +21,10 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ["lib"]
 
+  # For development on this gem
   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 'minitest'
+
 end

data/examples/{division_by_zero_example.rb → demo_exception_enhancement.rb}

@@ -1,6 +1,9 @@
 require './lib/enhanced_errors'
 require 'awesome_print' # Optional, for better output
 
+# Demonstrates enhancing exceptions in normal day to day Ruby usage
+# from this folder:  ruby demo_exception_enhancement.rb
+
 EnhancedErrors.enhance_exceptions!(override_messages: true, capture_events: [:raise, :rescue])
 
 def foo
@@ -24,7 +27,6 @@ rescue Exception => e
     puts e.message
 end
 
-
 puts "\n--- Example with raise ---\n\n\n"
 
 foo

data/examples/demo_minitest.rb

@@ -0,0 +1,22 @@
+require 'minitest/autorun'
+require 'enhanced_errors'
+require 'enhanced/minitest_patch'
+
+# You must install minitest and load it first to run this demo.
+# EnhancedErrors does NOT ship with minitest as a dependency.
+
+class MagicBallTest < Minitest::Test
+  def setup
+    @foo = 'bar'
+  end
+
+  def test_boo_capture
+    bee = 'fee'
+    assert false
+  end
+
+  def test_i_raise
+    zoo = 'zee'
+    raise "Crud"
+  end
+end

data/examples/demo_rspec.rb

@@ -0,0 +1,41 @@
+# spec/enhanced_errors_spec.rb
+
+# INSTRUCTIONS:  Install rspec
+# gem install rspec
+# rspec examples/example_spec.rb
+
+require 'rspec'
+require_relative '../lib/enhanced_errors'
+
+RSpec.configure do |config|
+
+  # -- Add to your RSPec config in your spec_helper.
+  config.before(:example) do |_example|
+    EnhancedErrors.start_rspec_binding_capture
+  end
+
+  config.after(:example) do |example|
+    EnhancedErrors.override_exception_message(example.exception, EnhancedErrors.stop_rspec_binding_capture)
+  end
+  # -- End EnhancedErrors config
+
+end
+
+
+RSpec.describe 'Neo' do
+  describe 'sees through' do
+    let(:the_matrix) { 'code rains, dramatically' }
+
+    before(:each) do
+      @spoon = 'there is no spoon'
+    end
+
+    it 'the matrix' do
+      #activate memoized item
+      the_matrix
+      stop = 'bullets'
+      raise 'No!'
+    end
+  end
+end
+

data/lib/enhanced/minitest_patch.rb

@@ -0,0 +1,17 @@
+module Minitest
+  class << self
+    alias_method :original_run_one_method, :run_one_method
+
+    def run_one_method(klass, method_name)
+      EnhancedErrors.start_minitest_binding_capture
+      result = original_run_one_method(klass, method_name)
+    ensure
+      begin
+        binding_infos = EnhancedErrors.stop_minitest_binding_capture
+        EnhancedErrors.override_exception_message(result.failures.last, binding_infos) if result.failures.any?
+      rescue => e
+        puts "Ignored error during error enhancement: #{e}"
+      end
+    end
+  end
+end