lumberjack_capture_device 1.2.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9147e66264c0eeebb01f7c04df1b6e18ab64bc4db3337e968d6cd1d2201fef7f
-  data.tar.gz: f01bf2e332024e9ef26ef703b374956e5f17c6bb4f351cb4518b1591b62dd992
+  metadata.gz: be90765c9b26b0ca9c501504e83c2a58cf1f2ce74edffe0b5e3d8e2515194277
+  data.tar.gz: '0825d9fa6621df4c5cdea31de794e1c8f263249d3f42f0e17945806ccb7f5f69'
 SHA512:
-  metadata.gz: 5e5ae9f94313a18f793b299998c9760aaa8d7bf5d8f462f48b4519f83c8844893ff894e5b570e31b15d55dc1ad9d25ee723529dc72e51db83d5060a4bcf1597c
-  data.tar.gz: 06a11ff5e4c5f3afed7cda12fa2f5f9bf94369f6c5b382d7118622136b7f1507d67c1e68ca472c6c38d1bf38cd3aa6db66f4859a145f78b9b69a8f9f4024a634
+  metadata.gz: 5423feff017c2b44974d7e75268c39388353165128632d0b7533619b5271ff17aeb1e9250d7ceda017de56f272baf0bda9b6e2a180a98397b13520b128f5449b
+  data.tar.gz: 3bbdb6b6ca43683a3ec20ead94fa93e557b33194c4ee58d5f36c478e50b01e7ff5abed29a3001fce885f47f304f62d3bcbeec5cddd00708401f377db7d775bf1

data/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.0.0
+
+### Added
+
+- Captured log entries are now passed through to the underlying logging device when the capture block is finished. This can be disabled by passing `write_to_original: false` to the `capture` method. You can then write the captured entries to the underlying device manually by calling `write_to_underlying_device`.
+- Added `capture_logger_around_example` RSpec helper method to simplify capturing log entries in an `around` hook.
+
+### Changed
+
+- Depends on `lumberjack` 2.0 or greater.
+
+### Deprecated
+
+- The `:level` and `:tags` options on the matching methods (`include?`, `match`, `closest_match`, and `extract`) has been deprecated in favor of `:severity` and `:attributes`.
+
 ## 1.2.2
 
 ### Changed

data/README.md

@@ -44,17 +44,17 @@ logs = Lumberjack::CaptureDevice.capture(Rails.logger) { do_something }
 assert(logs.include?(level: :info, message: "Something happened"))
 ```
 
-You can filter the logs on level, message, and tags.
+You can filter the logs on level, message, and attributes.
 
 - The level option can take either a label (i.e. `:warn`) or a constant (i.e. `Logger::WARN`).
 - The message filter can be either an exact string or a regular expression, or any matcher supported by your test library.
-- The tags argument can match tags with a Hash mapping tag names to the matcher values. If tags are nested, you can use dot notation on tag names to reference nested tags.
+- The attributes argument can match attributes with a Hash mapping attribute names to the matcher values. If attributes are nested, you can use dot notation on attribute names to reference nested attributes.
 
 ```ruby
 expect(logs).to include(level: :info, message: /something/i)
-expect(logs).to include(level: Logger::INFO, tags: {foo: "bar"})
-expect(logs).to include(tags: {foo: anything, count: {one: 1}})
-expect(logs).to include(tags: {foo: anything, "count.one" => 1})
+expect(logs).to include(level: Logger::INFO, attributes: {foo: "bar"})
+expect(logs).to include(attributes: {foo: anything, count: {one: 1}})
+expect(logs).to include(attributes: {foo: anything, "count.one" => 1})
 ```
 
 You can also use the `Lumberjack::CaptureDevice#extract` method with the same arguments as used by `include?` to extract all log entries that match the filters. You can get all of the log entries with `Lumberjack::CaptureDevice#buffer`.
@@ -72,12 +72,32 @@ This will give you a `capture_logger` method and `include_log_entry` matcher. Th
 ```ruby
 describe MyClass do
   it "logs information" do
-    logs = capture_logger { MyClass.do_something }
+    logs = capture_logger(Rails.logger) { MyClass.do_something }
     expect(logs).to include_log_entry(message: "Something")
   end
 end
 ```
 
+You can also set up log capturing around each example with the `capture_logger_around_example` method.
+
+```ruby
+describe MyClass do
+  around do |example|
+    capture_logger_around_example(Rails.logger, example)
+  end
+
+  it "logs information" do
+    MyClass.do_something
+    expect(Rails.logger).to include_log_entry(message: "Something")
+  end
+end
+```
+
+> [!TIP]
+> Add `capture_logger_around_example` as a global `around` hook in your RSpec configuration to automatically capture log entries for every example.
+>
+> This will also suppress all log output during tests unless an example fails which can reduce noise in the logs from tests that don't fail. This is especially useful in CI environments where you can save the logs as an artifact for failed test runs.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-1.2.2
+2.0.0

data/lib/lumberjack/capture_device/entry_score.rb

@@ -1,14 +1,23 @@
 # frozen_string_literal: true
 
-# Class responsible for scoring and matching log entries against filters
+# Class responsible for scoring and matching log entries against filters.
+# This class provides fuzzy matching capabilities to find the best matching
+# log entry when exact matches are not available.
 class Lumberjack::CaptureDevice::EntryScore
   # Minimum score threshold for considering a match (30% match)
   MIN_SCORE_THRESHOLD = 0.3
 
   class << self
-    # Calculate the overall match score for an entry against all provided filters
-    # Returns a score between 0.0 and 1.0
-    def calculate_match_score(entry, message_filter, level_filter, tags_filter, progname_filter)
+    # Calculate the overall match score for an entry against all provided filters.
+    # Returns a score between 0.0 and 1.0, where 1.0 represents a perfect match.
+    #
+    # @param entry [Lumberjack::LogEntry] The log entry to score.
+    # @param message_filter [String, Regexp, nil] The message filter to match against.
+    # @param severity_filter [Integer, nil] The severity level to match against.
+    # @param attributes_filter [Hash, nil] The attributes hash to match against.
+    # @param progname_filter [String, nil] The program name to match against.
+    # @return [Float] A score between 0.0 and 1.0 indicating match quality.
+    def calculate_match_score(entry, message_filter, severity_filter, attributes_filter, progname_filter)
       scores = []
       weights = []
 
@@ -19,14 +28,14 @@ class Lumberjack::CaptureDevice::EntryScore
         weights << 0.4  # Weight message matching highly
       end
 
-      # Check level match
-      if level_filter
-        level_score = if entry.severity == level_filter
-          1.0  # Exact level match
+      # Check severity match
+      if severity_filter
+        severity_score = if entry.severity == severity_filter
+          1.0  # Exact severity match
         else
-          level_proximity_score(entry.severity, level_filter)  # Partial level match
+          severity_proximity_score(entry.severity, severity_filter)  # Partial severity match
         end
-        scores << level_score
+        scores << severity_score
         weights << 0.3
       end
 
@@ -37,10 +46,10 @@ class Lumberjack::CaptureDevice::EntryScore
         weights << 0.2
       end
 
-      # Check tags match
-      if tags_filter.is_a?(Hash) && !tags_filter.empty?
-        tags_score = calculate_tags_score(entry.tags, tags_filter)
-        scores << tags_score
+      # Check attributes match
+      if attributes_filter.is_a?(Hash) && !attributes_filter.empty?
+        attributes_score = calculate_attributes_score(entry.attributes, attributes_filter)
+        scores << attributes_score
         weights << 0.3
       end
 
@@ -63,8 +72,12 @@ class Lumberjack::CaptureDevice::EntryScore
       base_score
     end
 
-    # Calculate score for any field value against a filter
-    # Returns a score between 0.0 and 1.0 based on how well the value matches the filter
+    # Calculate score for any field value against a filter.
+    # Returns a score between 0.0 and 1.0 based on how well the value matches the filter.
+    #
+    # @param value [Object] The value to match against the filter.
+    # @param filter [String, Regexp, Object] The filter to match the value against.
+    # @return [Float] A score between 0.0 and 1.0 indicating match quality.
     def calculate_field_score(value, filter)
       return 0.0 unless value && filter
 
@@ -92,10 +105,15 @@ class Lumberjack::CaptureDevice::EntryScore
       end
     end
 
-    # Calculate proximity score based on log level distance
-    def level_proximity_score(entry_level, filter_level)
-      level_diff = (entry_level - filter_level).abs
-      case level_diff
+    # Calculate proximity score based on log severity distance.
+    # Provides partial scoring for severities that are close to the target.
+    #
+    # @param entry_severity [Integer] The severity level of the log entry.
+    # @param filter_severity [Integer] The target severity level to match.
+    # @return [Float] A score between 0.0 and 1.0 based on severity proximity.
+    def severity_proximity_score(entry_severity, filter_severity)
+      severity_diff = (entry_severity - filter_severity).abs
+      case severity_diff
       when 0 then 1.0
       when 1 then 0.7
       when 2 then 0.4
@@ -103,24 +121,34 @@ class Lumberjack::CaptureDevice::EntryScore
       end
     end
 
-    # Calculate score for tag matching
-    def calculate_tags_score(entry_tags, tags_filter)
-      return 0.0 unless entry_tags && tags_filter.is_a?(Hash)
+    # Calculate score for attribute matching.
+    # Compares entry attributes against filter attributes and returns a score
+    # based on how many attributes match.
+    #
+    # @param entry_attributes [Hash] The attributes from the log entry.
+    # @param attributes_filter [Hash] The attributes filter to match against.
+    # @return [Float] A score between 0.0 and 1.0 based on attribute matches.
+    def calculate_attributes_score(entry_attributes, attributes_filter)
+      return 0.0 unless entry_attributes && attributes_filter.is_a?(Hash)
 
-      tags_filter = deep_stringify_keys(Lumberjack::Utils.expand_tags(tags_filter))
-      tags = deep_stringify_keys(Lumberjack::Utils.expand_tags(entry_tags))
+      attributes_filter = deep_stringify_keys(Lumberjack::Utils.expand_attributes(attributes_filter))
+      attributes = deep_stringify_keys(Lumberjack::Utils.expand_attributes(entry_attributes))
 
-      total_tag_filters = count_tag_filters(tags_filter)
-      return 0.0 if total_tag_filters == 0
+      total_attribute_filters = count_attribute_filters(attributes_filter)
+      return 0.0 if total_attribute_filters == 0
 
-      matched_tags = count_matched_tags(tags, tags_filter)
-      matched_tags.to_f / total_tag_filters
+      matched_attributes = count_matched_attributes(attributes, attributes_filter)
+      matched_attributes.to_f / total_attribute_filters
     end
 
     private
 
-    # Calculate string similarity using a simple Levenshtein distance-based approach
-    # Returns a score between 0.0 and 1.0 where 1.0 is an exact match
+    # Calculate string similarity using a simple Levenshtein distance-based approach.
+    # Returns a score between 0.0 and 1.0 where 1.0 is an exact match.
+    #
+    # @param str1 [String] The first string to compare.
+    # @param str2 [String] The second string to compare.
+    # @return [Float] A similarity score between 0.0 and 1.0.
     def string_similarity(str1, str2)
       return 1.0 if str1 == str2
       return 0.0 if str1.nil? || str2.nil? || str1.empty? || str2.empty?
@@ -142,10 +170,17 @@ class Lumberjack::CaptureDevice::EntryScore
 
       # Convert distance to similarity score
       return 0.0 if max_length == 0
+
       1.0 - (distance.to_f / max_length)
     end
 
-    # Simple Levenshtein distance implementation
+    # Simple Levenshtein distance implementation.
+    # Calculates the minimum number of single-character edits needed
+    # to change one string into another.
+    #
+    # @param str1 [String] The first string.
+    # @param str2 [String] The second string.
+    # @return [Integer] The Levenshtein distance between the strings.
     def levenshtein_distance(str1, str2)
       return str2.length if str1.empty?
       return str1.length if str2.empty?
@@ -171,10 +206,15 @@ class Lumberjack::CaptureDevice::EntryScore
       matrix[str1.length][str2.length]
     end
 
-    def count_tag_filters(tags_filter, count = 0)
-      tags_filter.each do |_name, value_filter|
+    # Count the total number of attribute filters in a nested hash structure.
+    #
+    # @param attributes_filter [Hash] The attributes filter hash to count.
+    # @param count [Integer] The current count (used for recursion).
+    # @return [Integer] The total number of filters.
+    def count_attribute_filters(attributes_filter, count = 0)
+      attributes_filter.each do |_name, value_filter|
         if value_filter.is_a?(Hash)
-          count = count_tag_filters(value_filter, count)
+          count = count_attribute_filters(value_filter, count)
         else
           count += 1
         end
@@ -182,27 +222,43 @@ class Lumberjack::CaptureDevice::EntryScore
       count
     end
 
-    def count_matched_tags(tags, tags_filter, count = 0)
-      return count unless tags && tags_filter
+    # Count the number of matched attributes in a nested structure.
+    #
+    # @param attributes [Hash] The log entry attributes to check.
+    # @param attributes_filter [Hash] The filter attributes to match against.
+    # @param count [Integer] The current count (used for recursion).
+    # @return [Integer] The number of matched attributes.
+    def count_matched_attributes(attributes, attributes_filter, count = 0)
+      return count unless attributes && attributes_filter
 
-      tags_filter.each do |name, value_filter|
+      attributes_filter.each do |name, value_filter|
         name = name.to_s
-        tag_values = tags[name]
+        attribute_values = attributes[name]
 
-        if value_filter.is_a?(Hash) && tag_values.is_a?(Hash)
-          count = count_matched_tags(tag_values, value_filter, count)
-        elsif tags.include?(name) && exact_match?(tag_values, value_filter)
+        if value_filter.is_a?(Hash) && attribute_values.is_a?(Hash)
+          count = count_matched_attributes(attribute_values, value_filter, count)
+        elsif attributes.include?(name) && exact_match?(attribute_values, value_filter)
           count += 1
         end
       end
       count
     end
 
+    # Check if a value exactly matches the filter using the === operator.
+    #
+    # @param value [Object] The value to match.
+    # @param filter [Object] The filter to match against.
+    # @return [Boolean] True if the value matches the filter.
     def exact_match?(value, filter)
       return true unless filter
+
       filter === value
     end
 
+    # Recursively convert all keys in a hash structure to strings.
+    #
+    # @param hash [Hash, Object] The hash to stringify or other object to return as-is.
+    # @return [Hash, Object] The hash with string keys or the original object.
     def deep_stringify_keys(hash)
       if hash.is_a?(Hash)
         hash.each_with_object({}) do |(key, value), result|

data/lib/lumberjack/capture_device/include_log_entry_matcher.rb

@@ -2,91 +2,151 @@
 
 # RSpec matcher for checking captured logs for specific entries.
 class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
+  # Initialize the matcher with expected log entry attributes.
+  #
+  # @param expected_hash [Hash] Expected log entry attributes to match against.
   def initialize(expected_hash)
     @expected_hash = expected_hash.transform_keys(&:to_sym)
-    @captured_logger = nil
+    @logger = nil
   end
 
+  # Check if the logger contains a log entry matching the expected attributes.
+  #
+  # @param actual [Lumberjack::Logger, Lumberjack::ForkedLogger] The logger to check. The logger must be using
+  #   a Lumberjack::Device::Test device.
+  # @return [Boolean] True if a matching log entry is found.
   def matches?(actual)
-    @captured_logger = actual
-    return false unless valid_captured_logger?
+    @logger = actual
+    return false unless valid_logger?
 
-    @captured_logger.include?(@expected_hash)
+    device = @logger.is_a?(Lumberjack::Device::Test) ? @logger : @logger.device
+    device.include?(@expected_hash)
   end
 
+  # Generate a failure message when the matcher fails.
+  #
+  # @return [String] A formatted failure message.
   def failure_message
-    if valid_captured_logger?
-      formatted_failure_message(@captured_logger, @expected_hash)
+    if valid_logger?
+      formatted_failure_message(@logger, @expected_hash)
     else
-      wrong_object_type_message(@captured_logger)
+      wrong_object_type_message(@logger)
     end
   end
 
+  # Generate a failure message when the negated matcher fails.
+  #
+  # @return [String] A formatted failure message for negated expectations.
   def failure_message_when_negated
-    if valid_captured_logger?
-      formatted_negated_failure_message(@captured_logger, @expected_hash)
+    if valid_logger?
+      formatted_negated_failure_message(@logger, @expected_hash)
     else
-      wrong_object_type_message(@captured_logger)
+      wrong_object_type_message(@logger)
     end
   end
 
+  # Provide a description of what this matcher checks.
+  #
+  # @return [String] A human-readable description of the matcher.
   def description
     "have logged entry with #{expectation_description(@expected_hash)}"
   end
 
   private
 
-  def valid_captured_logger?
-    @captured_logger.is_a?(Lumberjack::CaptureDevice)
+  # Check if the logger is using a valid Lumberjack::Device::Test device.
+  #
+  # @return [Boolean] True if the logger is a Lumberjack::Device::Test.
+  def valid_logger?
+    return true if @logger.is_a?(Lumberjack::Device::Test)
+    return false unless @logger.respond_to?(:device)
+
+    @logger.device.is_a?(Lumberjack::Device::Test)
   end
 
-  def wrong_object_type_message(captured_logger)
-    "Expected a Lumberjack::CaptureDevice object, but received a #{captured_logger.class}."
+  # Generate an error message for wrong object type.
+  #
+  # @param logger [Object] The object that was passed instead of a Lumberjack::Device::Test.
+  # @return [String] An error message describing the type mismatch.
+  def wrong_object_type_message(logger)
+    unless logger.respond_to?(:device)
+      return "Expected a Lumberjack::Logger object, but received a #{logger.class}."
+    end
+
+    device = logger.device
+    "Expected logger device to be a Lumberjack::Device::Test, but it is a #{device.class}."
   end
 
-  def formatted_failure_message(captured_logger, expected_hash)
+  # Generate a detailed failure message showing expected vs actual logs.
+  #
+  # @param logger_or_device [Lumberjack::Device::Test] The logger device.
+  # @param expected_hash [Hash] The expected log entry attributes.
+  # @return [String] A formatted failure message with context.
+  def formatted_failure_message(logger_or_device, expected_hash)
+    device = logger_or_device.respond_to?(:device) ? logger_or_device.device : logger_or_device
+
+    # Handle deprecated keys
+    if expected_hash.include?(:level) && !expected_hash.include?(:severity)
+      expected_hash = expected_hash.merge(severity: expected_hash[:level])
+    end
+    if expected_hash.include?(:tags) && !expected_hash.include?(:attributes)
+      expected_hash = expected_hash.merge(attributes: expected_hash[:tags])
+    end
+
     message = +"expected logs to include entry:\n" \
-      "#{Lumberjack::CaptureDevice.formatted_expectation(expected_hash, indent: 2)}\n\n" \
-      "Captured #{captured_logger.length} log #{(captured_logger.length == 1) ? "entry" : "entries"}"
+      "#{Lumberjack::Device::Test.formatted_expectation(expected_hash, indent: 2)}"
 
-    if captured_logger.length > 0
-      message << "\n----------------------\n"
-      captured_logger.each do |entry|
-        message << "#{Lumberjack::CaptureDevice.formatted_entry(entry)}\n"
-      end
+    closest_match = device.closest_match(**expected_hash)
+    if closest_match
+      message << "\n\nClosest match found:" \
+        "#{Lumberjack::Device::Test.formatted_expectation(closest_match, indent: 2)}"
     end
 
-    closest_match = captured_logger.closest_match(**expected_hash)
-    if closest_match
-      message = "#{message}\n\nClosest match found:" \
-        "#{Lumberjack::CaptureDevice.formatted_expectation(closest_match, indent: 2)}"
+    entries = device.entries
+    message << "\n\nLogged #{entries.length} #{(entries.length == 1) ? "entry" : "entries"}"
+    if entries.length > 0
+      message << "\n----------------------\n"
+      template = Lumberjack::LocalLogTemplate.new
+      entries.each do |entry|
+        message << "#{template.call(entry)}\n"
+      end
     end
 
     message
   end
 
-  def formatted_negated_failure_message(captured_logger, expected_hash)
+  # Generate a failure message for negated expectations.
+  #
+  # @param logger_or_device [Lumberjack::Device::Test] The logger to check.
+  # @param expected_hash [Hash] The expected log entry attributes that should not be present.
+  # @return [String] A formatted failure message for negated expectations.
+  def formatted_negated_failure_message(logger_or_device, expected_hash)
+    device = logger_or_device.respond_to?(:device) ? logger_or_device.device : logger_or_device
     message = "expected logs not to include entry:\n" \
-      "#{Lumberjack::CaptureDevice.formatted_expectation(expected_hash, indent: 2)}"
+      "#{Lumberjack::Device::Test.formatted_expectation(expected_hash, indent: 2)}"
 
-    match = captured_logger.match(**expected_hash)
+    match = device.match(**expected_hash)
     if match
       message = "#{message}\n\nFound entry:\n" \
-        "#{Lumberjack::CaptureDevice.formatted_expectation(match, indent: 2)}"
+        "#{Lumberjack::Device::Test.formatted_expectation(match, indent: 2)}"
     end
 
     message
   end
 
+  # Create a human-readable description of the expected log entry attributes.
+  #
+  # @param expected_hash [Hash] The expected log entry attributes.
+  # @return [String] A formatted description of the expected attributes.
   def expectation_description(expected_hash)
     info = []
-    info << "level: #{expected_hash[:level].inspect}" unless expected_hash[:level].nil?
+    info << "severity: #{expected_hash[:severity].inspect}" unless expected_hash[:severity].nil?
     info << "message: #{expected_hash[:message].inspect}" unless expected_hash[:message].nil?
     info << "progname: #{expected_hash[:progname].inspect}" unless expected_hash[:progname].nil?
-    if expected_hash[:tags].is_a?(Hash) && !expected_hash[:tags].empty?
-      tags = Lumberjack::Utils.flatten_tags(expected_hash[:tags])
-      tags_info = tags.collect { |name, value| "#{name}=#{value.inspect}" }.join(", ")
-      info << "tags: #{tags_info}"
+    if expected_hash[:attributes].is_a?(Hash) && !expected_hash[:attributes].empty?
+      attributes = Lumberjack::Utils.flatten_attributes(expected_hash[:attributes])
+      attributes_info = attributes.collect { |name, value| "#{name}=#{value.inspect}" }.join(", ")
+      info << "attributes: #{attributes_info}"
     end
     info.join(", ")
   end

data/lib/lumberjack/capture_device/rspec.rb

@@ -3,13 +3,70 @@
 require_relative "../capture_device"
 require "rspec"
 
+# RSpec helper methods for working with CaptureDevice.
 module Lumberjack::CaptureDevice::RSpec
+  # Create a matcher for checking if a log entry is included in the captured logs.
+  # This matcher provides better error messages than using the include? method directly.
+  #
+  # @param expected_hash [Hash] The expected log entry attributes to match.
+  # @option expected_hash [String, Symbol, Integer] :level The expected log level.
+  # @option expected_hash [String, Symbol, Integer] :severity Alias for :level.
+  # @option expected_hash [String, Regexp] :message The expected message content.
+  # @option expected_hash [Hash] :attributes Expected log entry attributes.
+  # @option expected_hash [Hash] :tags Alias for :attributes.
+  # @option expected_hash [String] :progname Expected program name.
+  # @return [Lumberjack::CaptureDevice::IncludeLogEntryMatcher] A matcher for the expected log entry.
+  # @example
+  #   expect(logs).to include_log_entry(level: :info, message: "User logged in")
+  # @example
+  #   expect(logs).to include_log_entry(message: /error/i, attributes: {user_id: 123})
   def include_log_entry(expected_hash)
     Lumberjack::CaptureDevice::IncludeLogEntryMatcher.new(expected_hash)
   end
 
-  def capture_logger(logger, &block)
-    Lumberjack::CaptureDevice.capture(logger, &block)
+  # Capture log entries from a logger within a block. This method temporarily
+  # replaces the logger's device with a CaptureDevice, sets the log level to debug,
+  # and removes formatters to capture raw log entries for testing.
+  #
+  # @param logger [Lumberjack::Logger] The logger to capture entries from.
+  # @yield [device] The block to execute while capturing log entries.
+  # @yieldparam device [Lumberjack::CaptureDevice] The device that will capture the log entries.
+  # @return [Lumberjack::CaptureDevice] The device that captured the log entries.
+  # @example
+  #   logs = capture_logger(Rails.logger) do
+  #     Rails.logger.info("Test message")
+  #   end
+  #   expect(logs).to include_log_entry(level: :info, message: "Test message")
+  def capture_logger(logger, write_to_original: true, &block)
+    Lumberjack::CaptureDevice.capture(logger, write_to_original: write_to_original, &block)
+  end
+
+  # RSpec around hook to automatically capture logs for each example. The captured logs are only
+  # written to the original logger if the example fails. This helps keep the logs more usable for
+  # debugging test failures since it removes all the noise from passing tests.
+  #
+  # This is designed for CI environments where you can save the logs as artifacts of the test run.
+  #
+  # @param logger [Lumberjack::Logger] The logger to capture entries for.
+  # @param example [RSpec::Core::Example] The current RSpec example.
+  #
+  # @example Capture logs for a Rails application
+  #  # In your spec_helper.rb or rails_helper.rb
+  #  RSpec.configure do |config|
+  #    config.around do |example|
+  #      capture_logger_around_example(Rails.logger, example)
+  #    end
+  #  end
+  def capture_logger_around_example(logger, example)
+    capture_logger(logger, write_to_original: false) do |captured_device|
+      example.run
+
+      if example.exception
+        logger.tag(rspec: {source_location: example.source_location, description: example.metadata[:description]}) do
+          captured_device.write_to_underlying_device
+        end
+      end
+    end
   end
 end
 

data/lib/lumberjack/capture_device.rb

@@ -5,12 +5,13 @@ require "lumberjack"
 module Lumberjack
   # Lumberjack device for capturing log entries into memory to allow them to be inspected
   # for testing purposes.
-  class CaptureDevice < Lumberjack::Device
-    VERSION = File.read(File.join(__dir__, "..", "..", "VERSION"))
+  class CaptureDevice < Lumberjack::Device::Test
+    VERSION = ::File.read(::File.join(__dir__, "..", "..", "VERSION")).strip.freeze
+
+    require_relative "capture_device/include_log_entry_matcher"
 
     include Enumerable
 
-    attr_reader :buffer
     class << self
       # Capture the entries written by the logger within a block. Within the block all log
       # entries will be written to a CaptureDevice rather than to the normal output for
@@ -19,169 +20,153 @@ module Lumberjack
       # by the method call.
       #
       # @param logger [Lumberjack::Logger] The logger to capture entries from.
+      # @param write_to_original [Boolean] If true (the default) the captured entries will be written
+      #   back to the original device when the block completes. If false, the captured entries
+      #   will not be written back.
       # @yield [device] The block to execute while capturing log entries.
       # @return [Lumberjack::CaptureDevice] The device that captured the log entries.
       # @yieldparam device [Lumberjack::CaptureDevice] The device that will capture the log entries.
       # @example
       #   Lumberjack::CaptureDevice.capture(logger) do |logs|
       #     logger.info("This will be captured")
-      #     expect(logs).to include(level: :info, message: "This will be captured")
+      #     expect(logs).to include(severity: :info, message: "This will be captured")
       #   end
       #
       # @example
       #   logs = Lumberjack::CaptureDevice.capture(logger) { logger.info("This will be captured") }
-      #   expect(logs).to include(level: :info, message: "This will be captured")
-      def capture(logger)
-        device = new
+      #   expect(logs).to include(severity: :info, message: "This will be captured")
+      def capture(logger, write_to_original: true)
         save_device = logger.device
         save_level = logger.level
-        save_formatter = logger.formatter
+        device = new(underlying_device: save_device)
+
         begin
           logger.device = device
           logger.level = :debug
-          logger.formatter = Lumberjack::Formatter.empty
           yield device
         ensure
           logger.device = save_device
           logger.level = save_level
-          logger.formatter = save_formatter
+          device.write_to_underlying_device if write_to_original
         end
-        device
-      end
 
-      # Helper method to format a log entry for display.
-      #
-      # @param entry [Lumberjack::LogEntry] The log entry to format.
-      # @param indent [Integer] The indentation to prefix on every line.
-      # @return [String] The formatted log entry.
-      def formatted_entry(entry, indent: 0)
-        indent_str = " " * indent
-        timestamp = entry.time.strftime("%Y-%m-%d %H:%M:%S")
-        formatted = +"#{indent_str}#{timestamp} #{entry.severity_label}: #{entry.message}"
-        formatted << "\n#{indent_str}  progname: #{entry.progname}" if entry.progname.to_s != ""
-        if entry.tags && !entry.tags.empty?
-          Lumberjack::Utils.flatten_tags(entry.tags).to_a.sort_by(&:first).each do |name, value|
-            formatted << "\n#{indent_str}  #{name}: #{value}"
-          end
-        end
-        formatted
+        device
       end
+    end
 
-      # Format a log entry or expectation hash into a more human readable format.
-      #
-      # @param expectation [Hash, Lumberjack::LogEntry] The expectation or log entry to format.
-      # @return [String] A formatted string representation of the expectation or log entry.
-      def formatted_expectation(expectation, indent: 0)
-        if expectation.is_a?(Lumberjack::LogEntry)
-          expectation = {
-            "level" => expectation.severity_label,
-            "message" => expectation.message,
-            "progname" => expectation.progname,
-            "tags" => expectation.tags
-          }
-        end
+    # The original device from the logger before capture started.
+    #
+    # @return [Lumberjack::Device, nil] The original device, or nil if none was set.
+    attr_reader :underlying_device
 
-        expectation = expectation.transform_keys(&:to_s).compact
+    # Initialize a new CaptureDevice.
+    #
+    # @param options [Hash] Options to pass to the parent Test device.
+    def initialize(options = {})
+      @underlying_device = options[:underlying_device]
+      super(options.merge(max_entries: 1_000_000))
+    end
 
-        message = []
-        indent_str = " " * indent
-        message << "#{indent_str}level: #{expectation["level"].inspect}" if expectation.include?("level")
-        message << "#{indent_str}message: #{expectation["message"].inspect}" if expectation.include?("message")
-        message << "#{indent_str}progname: #{expectation["progname"].inspect}" if expectation.include?("progname")
-        if expectation["tags"].is_a?(Hash) && !expectation["tags"].empty?
-          tags = Lumberjack::Utils.flatten_tags(expectation["tags"])
-          prefix = "tags: "
-          tags.sort_by(&:first).each do |name, value|
-            message << "#{prefix} #{name}: #{value.inspect}"
-            prefix = "#{indent_str}      "
-          end
-        end
-        message.join("\n")
+    # Return all the captured entries that match the specified filters. These filters are
+    # the same as described in the `include?` method.
+    #
+    # @param message [String, Regexp, nil] The message to match against the log entries.
+    # @param severity [String, Symbol, Integer, nil] The severity to match against the log entries.
+    # @param attributes [Hash, nil] A hash of attribute names to values to match against the log entries. The attributes
+    #   will match nested attributes using dot notation (e.g. `foo.bar` will match an attribute with the structure
+    #   +{foo: {bar: "value"}}+).
+    # @param progname [String, nil] The program name to match against the log entries.
+    # @param limit [Integer, nil] The maximum number of entries to return. If nil, all matching entries
+    #   will be returned.
+    # @param level [String, Symbol, Integer, nil] Alias for the `severity` parameter.
+    # @param tags [Hash, nil] Alias for the `attributes` parameter.
+    # @return [Array<Lumberjack::LogEntry>] An array of log entries that match the specified filters.
+    def extract(message: nil, severity: nil, attributes: nil, progname: nil, limit: nil, level: nil, tags: nil)
+      matched = []
+      if severity.nil? && !level.nil?
+        Lumberjack::Utils.deprecated("Lumberjack::CaptureDevice#extract(level)", "Lumberjack::CaptureDevice#extract level parameter has been renamed to severity; it will be removed in version 2.1.")
+        severity = level
+      end
+      if attributes.nil? && !tags.nil?
+        Lumberjack::Utils.deprecated("Lumberjack::CaptureDevice#extract(tags)", "Lumberjack::CaptureDevice#extract tags parameter has been renamed to attributes; it will be removed in version 2.1.")
+        attributes = tags
       end
-    end
 
-    def initialize
-      @buffer = []
-    end
+      matcher = LogEntryMatcher.new(message: message, severity: severity, attributes: attributes, progname: progname)
 
-    def write(entry)
-      @buffer << entry
-    end
+      entries.each do |entry|
+        matched << entry if matcher.match?(entry)
+        break if limit && matched.size >= limit
+      end
 
-    # Clear all entries that have been written to the buffer.
-    def clear
-      @buffer.clear
+      matched
     end
 
-    # Return true if the captured log entries match the specified level, message, and tags.
+    # Return true if the captured log entries match the specified level, message, and attributes.
     #
-    # For level, you can specified either a numeric constant (i.e. `Logger::WARN`) or a symbol
+    # For level, you can specify either a numeric constant (i.e. `Logger::WARN`) or a symbol
     # (i.e. `:warn`).
     #
     # For message you can specify a string to perform an exact match or a regular expression
     # to perform a partial or pattern match. You can also supply any matcher value available
     # in your test library (i.e. in rspec you could use `anything` or `instance_of(Error)`, etc.).
     #
-    # For tags, you can specify a hash of tag names to values to match. You can use
-    # regular expression or matchers as the values here as well. Tags can also be nested to match
-    # nested tags.
+    # For attributes, you can specify a hash of attribute names to values to match. You can use
+    # regular expression or matchers as the values here as well. attributes can also be nested to match
+    # nested attributes.
     #
-    # Example:
+    # @example
+    #   logs.include?(level: :warn, message: /something happened/, attributes: {user: "john"})
     #
-    # ```
-    # logs.include(level: :warn, message: /something happened/, tags: {duration: instance_of(Float)})
-    # ```
-    #
-    # @param args [Hash] The filters to apply to the captured entries.
-    # @option args [String, Regexp] :message The message to match against the log entries.
-    # @option args [String, Symbol, Integer] :level The log level to match against the log entries.
-    # @option args [Hash] :tags A hash of tag names to values to match against the log entries. The tags
-    #   will match nested tags using dot notation (e.g. `foo.bar` will match a tag with the structure
-    #   `{foo: {bar: "value"}}`).
-    # @option args [String] :progname The program name to match against the log entries.
+    # @param filters [Hash] The filters to apply to the captured entries.
+    # @option filters [String, Regexp] :message The message to match against the log entries.
+    # @option filters [String, Symbol, Integer] :severity The log level to match against the log entries.
+    # @option filters [Hash] :attributes A hash of attribute names to values to match against the log entries. The attributes
+    #   will match nested attributes using dot notation (e.g. `foo.bar` will match an attribute with the structure
+    #   +{foo: {bar: "value"}}+).
+    # @option filters [String] :progname The program name to match against the log entries.
+    # @option filters [String, Symbol, Integer, nil] :level Alias for the `severity` option. This option is deprecated.
+    # @option filters [Hash, nil] :tags Alias for the `attributes` option. This option is deprecated.
     # @return [Boolean] True if any entries match the specified filters, false otherwise.
-    def include?(args)
-      !!match(**args)
-    end
-
-    # Return all the captured entries that match the specified filters. These filters are
-    # the same as described in the `include?` method.
-    #
-    # @param message [String, Regexp, nil] The message to match against the log entries.
-    # @param level [String, Symbol, Integer, nil] The log level to match against the log entries.
-    # @param tags [Hash, nil] A hash of tag names to values to match against the log entries. The tags
-    #   will match nested tags using dot notation (e.g. `foo.bar` will match a tag with the structure
-    #   `{foo: {bar: "value"}}`).
-    # @param limit [Integer, nil] The maximum number of entries to return. If nil, all matching entries
-    #   will be returned.
-    # @return [Array<Lumberjack::LogEntry>] An array of log entries that match the specified filters.
-    def extract(message: nil, level: nil, tags: nil, progname: nil, limit: nil)
-      matches = []
-
-      if level
-        # Normalize the level filter to numeric values.
-        level = (level.is_a?(Integer) ? level : Lumberjack::Severity.label_to_level(level))
+    def include?(filters)
+      if filters.include?(:level)
+        Lumberjack::Utils.deprecated("Lumberjack::CaptureDevice#include?(level)", "Lumberjack::CaptureDevice#include? level option has been renamed to severity; it will be removed in version 2.1.")
       end
 
-      @buffer.each do |entry|
-        if matched?(entry, message, level, tags, progname)
-          matches << entry
-          break if limit && matches.size >= limit
-        end
+      if filters.include?(:tags)
+        Lumberjack::Utils.deprecated("Lumberjack::CaptureDevice#include?(tags)", "Lumberjack::CaptureDevice#include? tags option has been renamed to attributes; it will be removed in version 2.1.")
       end
 
-      matches
+      munged_filters = {
+        message: filters[:message],
+        severity: filters[:severity] || filters[:level],
+        attributes: filters[:attributes] || filters[:tags],
+        progname: filters[:progname]
+      }.compact
+
+      !!match(**munged_filters)
     end
 
-    # Return the first entry that matches the specified filters.
+    # Return the first captured entry that matches the filters.
     #
     # @param message [String, Regexp, nil] The message to match against the log entries.
-    # @param level [String, Symbol, Integer, nil] The log level to match against the log entries.
-    # @param tags [Hash, nil] A hash of tag names to values to match against the log entries.
+    # @param severity [String, Symbol, Integer, nil] The log level to match against the log entries.
+    # @param attributes [Hash, nil] A hash of attribute names to values to match against the log entries. The attributes
+    #   will match nested attributes using dot notation (e.g. `foo.bar` will match an attribute with the structure
+    #   +{foo: {bar: "value"}}+).
     # @param progname [String, nil] The program name to match against the log entries.
-    # @return [Lumberjack::LogEntry, nil] The log entry that most closely matches the filters, or nil if no entry meets minimum criteria.
-    def match(message: nil, level: nil, tags: nil, progname: nil)
-      extract(message: message, level: level, tags: tags, progname: progname, limit: 1).first
+    # @param level [String, Symbol, Integer, nil] Alias for the `severity` parameter. This parameter is deprecated.
+    # @param tags [Hash, nil] Alias for the `attributes` parameter. This parameter is deprecated.
+    # @return [Lumberjack::LogEntry, nil] The first matching log entry, or nil if no match is found.
+    def match(message: nil, severity: nil, attributes: nil, progname: nil, level: nil, tags: nil)
+      unless level.nil?
+        Lumberjack::Utils.deprecated("Lumberjack::CaptureDevice#match(level)", "Lumberjack::CaptureDevice#match level parameter has been renamed to severity; it will be removed in version 2.1.")
+      end
+      unless tags.nil?
+        Lumberjack::Utils.deprecated("Lumberjack::CaptureDevice#match(tags)", "Lumberjack::CaptureDevice#match tags parameter has been renamed to attributes; it will be removed in version 2.1.")
+      end
+
+      super(message: message, severity: severity || level, attributes: attributes || tags, progname: progname)
     end
 
     # Return the log entry that most closely matches the specified filters. This method
@@ -190,119 +175,75 @@ module Lumberjack
     # they match. Returns nil if no entry meets the minimum matching criteria.
     #
     # @param message [String, Regexp, nil] The message to match against the log entries.
-    # @param level [String, Symbol, Integer, nil] The log level to match against the log entries.
-    # @param tags [Hash, nil] A hash of tag names to values to match against the log entries.
+    # @param severity [String, Symbol, Integer, nil] The severity to match against the log entries.
+    # @param attributes [Hash, nil] A hash of attribute names to values to match against the log entries.
     # @param progname [String, nil] The program name to match against the log entries.
+    # @param level [String, Symbol, Integer, nil] Alias for the `severity` parameter.
+    # @param tags [Hash, nil] Alias for the `attributes` parameter.
     # @return [Lumberjack::LogEntry, nil] The log entry that most closely matches the filters, or nil if no entry meets minimum criteria.
-    def closest_match(message: nil, level: nil, tags: nil, progname: nil)
-      return nil if @buffer.empty?
-
-      exact_match = match(message: message, level: level, tags: tags, progname: progname)
-      return exact_match if exact_match
+    def closest_match(message: nil, severity: nil, attributes: nil, progname: nil, level: nil, tags: nil)
+      return nil if length == 0
 
-      # Normalize level filter
-      if level
-        level = (level.is_a?(Integer) ? level : Lumberjack::Severity.label_to_level(level))
+      unless level.nil?
+        Lumberjack::Utils.deprecated("Lumberjack::CaptureDevice#closest_match(level)", "Lumberjack::CaptureDevice#closest_match level parameter has been renamed to severity; it will be removed in version 2.1.")
       end
-
-      best_entry = nil
-      best_score = 0
-
-      @buffer.each do |entry|
-        score = Lumberjack::CaptureDevice::EntryScore.calculate_match_score(entry, message, level, tags, progname)
-        if score > best_score && score >= Lumberjack::CaptureDevice::EntryScore::MIN_SCORE_THRESHOLD
-          best_score = score
-          best_entry = entry
-        end
+      unless tags.nil?
+        Lumberjack::Utils.deprecated("Lumberjack::CaptureDevice#closest_match(tags)", "Lumberjack::CaptureDevice#closest_match tags parameter has been renamed to attributes; it will be removed in version 2.1.")
       end
 
-      best_entry
+      super(
+        message: message,
+        severity: severity || level,
+        attributes: attributes || tags,
+        progname: progname
+      )
     end
 
+    # Write the captured log entries to the underlying device.
+    #
+    # @return [void]
+    def write_to_underlying_device
+      write_to(@underlying_device) if @underlying_device
+    end
+
+    # Provide a detailed string representation showing all captured entries.
+    #
+    # @return [String] A formatted string showing all captured log entries.
     def inspect
-      message = +"<##{self.class.name} #{@buffer.size} #{(@buffer.size == 1) ? "entry" : "entries"} captured:"
-      @buffer.each do |entry|
-        message << "\n  #{Lumberjack::CaptureDevice.formatted_entry(entry)}"
+      message = +"<##{self.class.name} #{length} #{(length == 1) ? "entry" : "entries"} captured:\n"
+      template = Lumberjack::LocalLogTemplate.new
+      entries.each do |entry|
+        formatted = template.call(entry).split("\n").collect { |line| "  #{line}" }.join("\n")
+        message << formatted
+        message << "\n"
       end
-      message << "\n>"
+      message << ">"
       message
     end
 
+    # Provide a simple string representation showing the count of captured entries.
+    #
+    # @return [String] A brief description of the captured entries count.
     def to_s
-      "<##{self.class.name} #{@buffer.size} #{(@buffer.size == 1) ? "entry" : "entries"} captured>"
+      "<##{self.class.name} #{length} #{(length == 1) ? "entry" : "entries"} captured>"
     end
 
+    # Return the number of captured log entries.
+    #
+    # @return [Integer] The number of captured entries.
     def length
       @buffer.length
     end
 
     alias_method :size, :length
 
+    # Iterate over each captured log entry.
+    #
+    # @yield [entry] Block to execute for each captured entry.
+    # @yieldparam entry [Lumberjack::LogEntry] A captured log entry.
+    # @return [Array<Lumberjack::LogEntry>] The captured entries (when no block given).
     def each(&block)
       @buffer.each(&block)
     end
-
-    private
-
-    def matched?(entry, message_filter, level_filter, tags_filter, progname_filter)
-      return false unless match?(entry.message, message_filter)
-      return false unless match?(entry.severity, level_filter)
-      return false unless match?(entry.progname, progname_filter)
-
-      if tags_filter.is_a?(Hash)
-        tags_filter = deep_stringify_keys(Lumberjack::Utils.expand_tags(tags_filter))
-      end
-      tags = deep_stringify_keys(Lumberjack::Utils.expand_tags(entry.tags))
-
-      return false unless match_tags?(tags, tags_filter)
-
-      true
-    end
-
-    def match?(value, filter)
-      return true unless filter
-
-      filter === value
-    end
-
-    def match_tags?(tags, filter)
-      return true unless filter
-      return false unless tags
-
-      filter.all? do |name, value_filter|
-        name = name.to_s
-        tag_values = tags[name]
-        if tag_values.is_a?(Hash)
-          if value_filter.is_a?(Hash)
-            match_tags?(tag_values, value_filter)
-          else
-            false
-          end
-        elsif value_filter.nil? || (value_filter.is_a?(Enumerable) && value_filter.empty?)
-          tag_values.nil? || (tag_values.is_a?(Array) && tag_values.empty?)
-        elsif tags.include?(name)
-          match?(tag_values, value_filter)
-        else
-          false
-        end
-      end
-    end
-
-    def deep_stringify_keys(hash)
-      if hash.is_a?(Hash)
-        hash.each_with_object({}) do |(key, value), result|
-          new_key = key.to_s
-          new_value = deep_stringify_keys(value)
-          result[new_key] = new_value
-        end
-      elsif hash.is_a?(Enumerable)
-        hash.collect { |item| deep_stringify_keys(item) }
-      else
-        hash
-      end
-    end
   end
 end
-
-require_relative "capture_device/entry_score"
-require_relative "capture_device/include_log_entry_matcher"

data/lumberjack_capture_device.gemspec

@@ -31,8 +31,8 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 2.7"
 
-  spec.add_dependency "lumberjack", ">=1.3.3"
+  spec.add_dependency "lumberjack", ">=2.0"
   spec.add_development_dependency "bundler"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: lumberjack_capture_device
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Brian Durand
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lumberjack
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.3
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.3
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -38,7 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - bbdurand@gmail.com
 executables: []
@@ -62,7 +60,6 @@ metadata:
   homepage_uri: https://github.com/bdurand/lumberjack_capture_device
   source_code_uri: https://github.com/bdurand/lumberjack_capture_device
   changelog_uri: https://github.com/bdurand/lumberjack_capture_device/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -70,15 +67,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Testing device for the lumberjack gem that can be used for asserting messages
   have been logged in a test suite.