enhanced_errors 2.0.6 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e6ed241407a54376e0c64f2c1adc087e3dae4980ac5b7e84c947d92ff787392
-  data.tar.gz: 4f949a5145869e73e7f795a9c009800433956162a6d25695c2a9e8ba3a39da05
+  metadata.gz: 636b9fff23b9913fd382737267930a6f33f17c30bd54fc889ac85b308b4a30c9
+  data.tar.gz: 5e786beb7ff2cf30e603ce7c1cc70b51734adb0217b36f0317187b937036cda7
 SHA512:
-  metadata.gz: 02312f5287c4214c59b4b4a53e723d53d4dff511f24c335a7f7a84f049bb06638f77ea22f488cba5682fba66f581116b2bb1a4b3a79d8b6a5a290f5f822f1ea8
-  data.tar.gz: 13d06fa670a3f34bb67624ec40bc9a87810536aace8c2867e64620092c13d8e48d25675241491d821491cb2f3a893c1d8faa2ede7ff2f22c45b50fb506fbbd74
+  metadata.gz: da7858a0bd808e2a69a25c4e986017fd43eb3c6db2e2c6767d809a47fcad40bf1a874b77c3a64b284c9e4ce7154fbbe3cf5b890b12d84285aa2fcb511d86e97b
+  data.tar.gz: dfc678ff9757f83b3ca8988c663ea72ed8fc4830412f6274bd8f2090ee020498ed28947b523aa7ff904951c10176aa0780dde744e2380f04deb3b6fdb6cd3425

data/.yardoc/checksums

@@ -1,4 +1,4 @@
-lib/colors.rb a4314ef9531d4713907c3fea22955c943fdb8cf3
-lib/binding.rb fdd7d5a2dd2edde22e3b10773510738dcdce4aeb
-lib/enhanced_errors.rb d12ce0629f2565e5179ae5076be8a495e19ecda2
-lib/error_enhancements.rb a97d0f139d35f6e1b5bf49386271b1f4cf71761c
+lib/enhanced/colors.rb ed3b11d00ff9ceed089d4a65f0be5b3fca64bbe6
+lib/enhanced_errors.rb c327aefb93959d7bf567c751292a7513da14a7c6
+lib/enhanced/exception.rb 72c62e85ce9cea875bc3e835240059bbf1b00f0b
+lib/enhanced/minitest_patch.rb c8c934389dfa3789de66eeeacc8402a48a34d5b4

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>
+EnhancedErrors captures exception context using either a test-framework integration (RSpec/Minitest) or a global enhancement for runtime exceptions.
 
-#### 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
-```
-
-##### 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,17 +32,13 @@ 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
 
@@ -83,27 +47,73 @@ RSpec.configure do |config|
     EnhancedErrors.start_rspec_binding_capture
   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, example.metadata[:expect_binding])
+    EnhancedErrors.override_rspec_message(example, EnhancedErrors.stop_rspec_binding_capture)
   end
 end
 ```
 
-## TODO: Minitest
+<br>
 
 
-## Enhancing .message
+## MiniTest Setup
 
-EnhancedErrors can also append the captured variable description into the Exception's
-.message method output if the override_messages argument is true. 
+```ruby
+require 'enhanced_errors'
+require 'enhanced/minitest_patch'
 
-This can be very convenient as it lets you capture and diagnose 
-the context of totally unanticipated exceptions without modifying all your error handlers. 
+# Once the patch is loaded, it should just work!
 
-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.
+```
+
+<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
+
+foo
+```
+
+
+### Enhancing .message
+
+EnhancedErrors can append the captured variable description onto every Exception's
+.message method with
+```ruby
+EnhancedErrors.enhance_exceptions(override_messages: true)
+```
+
+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 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.
 
@@ -112,6 +122,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.
@@ -124,26 +141,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
 
@@ -180,14 +184,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
 
@@ -205,9 +210,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
 
@@ -338,8 +340,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
 
@@ -398,7 +400,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
 
@@ -419,28 +420,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/doc/Enhanced/Colors.html

@@ -111,7 +111,12 @@
         <dt id="COLORS-constant" class="">COLORS =
           
         </dt>
-        <dd><pre class="code"><span class='lbrace'>{</span> <span class='label'>red:</span> <span class='int'>31</span><span class='comma'>,</span> <span class='label'>green:</span> <span class='int'>32</span><span class='comma'>,</span> <span class='label'>yellow:</span> <span class='int'>33</span><span class='comma'>,</span> <span class='label'>blue:</span> <span class='int'>34</span><span class='comma'>,</span> <span class='label'>purple:</span> <span class='int'>35</span><span class='comma'>,</span> <span class='label'>cyan:</span> <span class='int'>36</span><span class='comma'>,</span> <span class='label'>white:</span> <span class='int'>0</span> <span class='rbrace'>}</span></pre></dd>
+        <dd><pre class="code"><span class='lbrace'>{</span> <span class='label'>red:</span> <span class='int'>31</span><span class='comma'>,</span> <span class='label'>green:</span> <span class='int'>32</span><span class='comma'>,</span> <span class='label'>yellow:</span> <span class='int'>33</span><span class='comma'>,</span> <span class='label'>blue:</span> <span class='int'>34</span><span class='comma'>,</span> <span class='label'>purple:</span> <span class='int'>35</span><span class='comma'>,</span> <span class='label'>cyan:</span> <span class='int'>36</span><span class='comma'>,</span> <span class='label'>white:</span> <span class='int'>0</span> <span class='rbrace'>}</span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
+      
+        <dt id="RESET_CODE-constant" class="">RESET_CODE =
+          
+        </dt>
+        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>\e[0m</span><span class='tstring_end'>&quot;</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
       
     </dl>
   
@@ -242,15 +247,15 @@
       <pre class="lines">
 
 
-18
-19
-20</pre>
+20
+21
+22</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/enhanced/colors.rb', line 18</span>
+      <pre class="code"><span class="info file"># File 'lib/enhanced/colors.rb', line 20</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_code'>code</span><span class='lparen'>(</span><span class='id identifier rubyid_num'>num</span><span class='rparen'>)</span>
-  <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>\e[</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_num'>num</span><span class='embexpr_end'>}</span><span class='tstring_content'>m</span><span class='tstring_end'>&quot;</span></span>
+  <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>\e[</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_num'>num</span><span class='embexpr_end'>}</span><span class='tstring_content'>m</span><span class='tstring_end'>&quot;</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -272,15 +277,17 @@
       <pre class="lines">
 
 
-14
 15
-16</pre>
+16
+17
+18</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/enhanced/colors.rb', line 14</span>
+      <pre class="code"><span class="info file"># File 'lib/enhanced/colors.rb', line 15</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_color'>color</span><span class='lparen'>(</span><span class='id identifier rubyid_num'>num</span><span class='comma'>,</span> <span class='id identifier rubyid_string'>string</span><span class='rparen'>)</span>
-  <span class='ivar'>@enabled</span> <span class='op'>?</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_code'>code</span><span class='lparen'>(</span><span class='id identifier rubyid_num'>num</span><span class='rparen'>)</span><span class='embexpr_end'>}</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_string'>string</span><span class='embexpr_end'>}</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_code'>code</span><span class='lparen'>(</span><span class='int'>0</span><span class='rparen'>)</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span> <span class='op'>:</span> <span class='id identifier rubyid_string'>string</span>
+  <span class='kw'>return</span> <span class='id identifier rubyid_string'>string</span> <span class='kw'>unless</span> <span class='ivar'>@enabled</span>
+  <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_code'>code</span><span class='lparen'>(</span><span class='id identifier rubyid_num'>num</span><span class='rparen'>)</span><span class='embexpr_end'>}</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_string'>string</span><span class='embexpr_end'>}</span><span class='embexpr_beg'>#{</span><span class='const'><span class='object_link'><a href="#RESET_CODE-constant" title="Enhanced::Colors::RESET_CODE (constant)">RESET_CODE</a></span></span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -302,12 +309,12 @@
       <pre class="lines">
 
 
-10
 11
-12</pre>
+12
+13</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/enhanced/colors.rb', line 10</span>
+      <pre class="code"><span class="info file"># File 'lib/enhanced/colors.rb', line 11</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_enabled='>enabled=</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span>
   <span class='ivar'>@enabled</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span>
@@ -354,12 +361,12 @@
       <pre class="lines">
 
 
-6
 7
-8</pre>
+8
+9</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/enhanced/colors.rb', line 6</span>
+      <pre class="code"><span class="info file"># File 'lib/enhanced/colors.rb', line 7</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_enabled?'>enabled?</span>
   <span class='ivar'>@enabled</span>
@@ -374,7 +381,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Dec  9 19:51:26 2024 by
+  Generated on Sun Dec 15 22:33:19 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.1.3).
 </div>

data/doc/Enhanced.html

@@ -83,9 +83,7 @@
   
   <dl>
     <dt>Defined in:</dt>
-    <dd>lib/enhanced/colors.rb<span class="defines">,<br />
-  lib/enhanced/integrations/rspec_error_failure_message.rb</span>
-</dd>
+    <dd>lib/enhanced/colors.rb</dd>
   </dl>
   
 </div>
@@ -94,8 +92,6 @@
 <p class="children">
   
     
-      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Enhanced/Integrations.html" title="Enhanced::Integrations (module)">Integrations</a></span>
-    
   
     
       <strong class="classes">Classes:</strong> <span class='object_link'><a href="Enhanced/Colors.html" title="Enhanced::Colors (class)">Colors</a></span>
@@ -114,7 +110,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Dec  9 19:51:26 2024 by
+  Generated on Sun Dec 15 22:33:19 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.1.3).
 </div>