lumberjack_capture_device 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be90765c9b26b0ca9c501504e83c2a58cf1f2ce74edffe0b5e3d8e2515194277
-  data.tar.gz: '0825d9fa6621df4c5cdea31de794e1c8f263249d3f42f0e17945806ccb7f5f69'
+  metadata.gz: 3de3ac7d3bf941c8f6283c70f8bf55163eb36f91bea583836f296e7c5fa2cc3a
+  data.tar.gz: df6a39ef765975ff2f029d99e46aaef435c7675be707ea8effa08fc6a7369308
 SHA512:
-  metadata.gz: 5423feff017c2b44974d7e75268c39388353165128632d0b7533619b5271ff17aeb1e9250d7ceda017de56f272baf0bda9b6e2a180a98397b13520b128f5449b
-  data.tar.gz: 3bbdb6b6ca43683a3ec20ead94fa93e557b33194c4ee58d5f36c478e50b01e7ff5abed29a3001fce885f47f304f62d3bcbeec5cddd00708401f377db7d775bf1
+  metadata.gz: 8c08cdc46f06da187f942b449a0a15551aefd2c55891cbb93d17ab3b0c8f281e169bddc340bb43a9a6fdfb11aeb6cc43a4a639f3417ab3819bea002d91515e3c
+  data.tar.gz: dfa277bb83a2710a9df87f893a35eaf58c266c8eb1d73e00be6a4f8fb1cf6233f7f552a86329b84e85459de8b87963143197d46e07d47f4136a605f793f0136b

data/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.1.0
+
+### Changed
+
+- `include?` now symbolizes filter keys and raises an `ArgumentError` on unrecognized filter keys. Previously filters with string keys or misspelled keys were silently ignored, causing the method to match any captured entry.
+- `write_to_underlying_device` accepts an optional `attributes` keyword argument to add attributes to each entry as it is written.
+- The `include_log_entry` matcher failure message now shows a diff of the closest matching entry against the expectation instead of just printing the entry. Severity, message, progname, and each attribute are shown with the expected value on a `-` line and the logged value on a `+` line so it is obvious which ones prevented the match. The comparison is done with `Lumberjack::LogEntryMatcher#diff` using the device's entry formatter, so the diff always agrees with the match. The diff is also available directly from `Lumberjack::CaptureDevice::IncludeLogEntryMatcher#entry_diff`.
+
+### Fixed
+
+- `extract` now matches filters with the device `entry_formatter` like `include?`, `match`, and `closest_match` do. Previously filter values were only compared to the formatted values captured on the entries, so unformatted values in the filters did not match.
+- `capture_logger_around_example` now correctly adds the rspec metadata attributes to entries written to the underlying device when an example fails. Previously the attributes were silently dropped and building them raised a `NoMethodError` since `RSpec::Core::Example` does not have a `source_location` method; the example location is now recorded in the `rspec.location` attribute.
+- The `max_entries` option is no longer ignored when initializing a `Lumberjack::CaptureDevice`.
+- Fixed missing line break after "Closest match found:" in RSpec matcher failure messages.
+- The `include_log_entry` matcher description no longer omits the expected attributes when a matcher (i.e. RSpec's `hash_including`) is passed as the `attributes` option instead of a hash. Matcher objects are now rendered with their description rather than by inspecting them.
+- `each` and `length` now read from a thread safe copy of the entries buffer.
+
+### Removed
+
+- Removed the deprecated `:level` and `:tags` options from the matching methods (`include?`, `match`, `closest_match`, and `extract`) and from the `include_log_entry` RSpec matcher. Use `:severity` and `:attributes` instead.
+- Removed the `match` and `closest_match` methods. They only existed to translate the deprecated options and are now inherited unchanged from `Lumberjack::Device::Test`.
+- Removed unused internal `Lumberjack::CaptureDevice::EntryScore` class. It was never loaded and was replaced by the scoring logic in the lumberjack gem.
+
 ## 2.0.0
 
 ### Added
@@ -17,7 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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`.
+- The `:level` and `:tags` options on the matching methods (`include?`, `match`, `closest_match`, and `extract`) have been deprecated in favor of `:severity` and `:attributes`.
 
 ## 1.2.2
 

data/README.md

@@ -26,7 +26,7 @@ You can use the `include?` method on the log device to determine if specific log
 ```ruby
 Lumberjack::CaptureDevice.capture(Rails.logger) do |logs|
   do_something
-  expect(logs).to include(level: :info, message: "Something happened")
+  expect(logs).to include(severity: :info, message: "Something happened")
 end
 ```
 
@@ -34,30 +34,30 @@ You can also write that same test as:
 
 ```ruby
 logs = Lumberjack::CaptureDevice.capture(Rails.logger) { do_something }
-expect(logs).to include(level: :info, message: "Something happened")
+expect(logs).to include(severity: :info, message: "Something happened")
 ```
 
 For MiniTest, you could assert:
 
 ```ruby
 logs = Lumberjack::CaptureDevice.capture(Rails.logger) { do_something }
-assert(logs.include?(level: :info, message: "Something happened"))
+assert(logs.include?(severity: :info, message: "Something happened"))
 ```
 
-You can filter the logs on level, message, and attributes.
+You can filter the logs on severity, message, progname, and attributes.
 
-- The level option can take either a label (i.e. `:warn`) or a constant (i.e. `Logger::WARN`).
+- The severity 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 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, attributes: {foo: "bar"})
+expect(logs).to include(severity: :info, message: /something/i)
+expect(logs).to include(severity: 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`.
+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#entries`.
 
 ### RSpec Support
 
@@ -78,6 +78,26 @@ describe MyClass do
 end
 ```
 
+When the matcher fails, the failure message includes a diff between the expectation and the closest matching entry so you can see exactly which fields and attributes are off. Lines prefixed with `-` show what was expected and lines prefixed with `+` show what was actually logged.
+
+```
+expected logs to include entry:
+  severity: WARN
+  message: User logged out
+  attributes: request_id: "abc"
+              user.role: "admin"
+
+Closest match found (- expected, + actual):
+  - severity: WARN
+  + severity: INFO
+    message: "User logged out"
+  - attributes.user.role: "admin"
+  + attributes.user.role: "guest"
+    attributes.duration: 1.5
+  - attributes.request_id: "abc"
+  + attributes.request_id: (not set)
+```
+
 You can also set up log capturing around each example with the `capture_logger_around_example` method.
 
 ```ruby

data/VERSION

@@ -1 +1 @@
-2.0.0
+2.1.0

data/lib/lumberjack/capture_device/include_log_entry_matcher.rb

@@ -2,10 +2,16 @@
 
 # RSpec matcher for checking captured logs for specific entries.
 class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
+  # Displayed as the actual value for an expected attribute that the log entry does not have.
+  MISSING_VALUE = "(not set)"
+
+  private_constant :MISSING_VALUE
+
   # Initialize the matcher with expected log entry attributes.
   #
   # @param expected_hash [Hash] Expected log entry attributes to match against.
   def initialize(expected_hash)
+    # The keys are symbolized so the hash can be passed to any Lumberjack::Device::Test device.
     @expected_hash = expected_hash.transform_keys(&:to_sym)
     @logger = nil
   end
@@ -19,7 +25,6 @@ class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
     @logger = actual
     return false unless valid_logger?
 
-    device = @logger.is_a?(Lumberjack::Device::Test) ? @logger : @logger.device
     device.include?(@expected_hash)
   end
 
@@ -28,7 +33,7 @@ class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
   # @return [String] A formatted failure message.
   def failure_message
     if valid_logger?
-      formatted_failure_message(@logger, @expected_hash)
+      formatted_failure_message(@expected_hash)
     else
       wrong_object_type_message(@logger)
     end
@@ -39,7 +44,7 @@ class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
   # @return [String] A formatted failure message for negated expectations.
   def failure_message_when_negated
     if valid_logger?
-      formatted_negated_failure_message(@logger, @expected_hash)
+      formatted_negated_failure_message(@expected_hash)
     else
       wrong_object_type_message(@logger)
     end
@@ -52,6 +57,30 @@ class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
     "have logged entry with #{expectation_description(@expected_hash)}"
   end
 
+  # Generate a diff between a log entry and the expected log entry values. The severity,
+  # message, progname, and attributes of the entry are listed. Values that don't match the
+  # expectation are shown on a pair of lines with the expected value prefixed with "-" and
+  # the value from the log entry prefixed with "+". This is intended to make it easy to spot
+  # exactly which fields kept an entry from matching.
+  #
+  # The comparison is done by Lumberjack::LogEntryMatcher#diff so the diff always agrees
+  # with the result of the match.
+  #
+  # @param entry [Lumberjack::LogEntry] The log entry to compare to the expectation.
+  # @param indent [Integer] The number of spaces to indent each line.
+  # @return [String] A formatted diff of the entry and the expectation.
+  def entry_diff(entry, indent: 2)
+    indent_str = " " * indent
+
+    entry_differences(entry).collect do |name, expected, actual, matched|
+      if matched
+        "#{indent_str}  #{name}: #{actual}"
+      else
+        "#{indent_str}- #{name}: #{expected}#{Lumberjack::LINE_SEPARATOR}#{indent_str}+ #{name}: #{actual}"
+      end
+    end.join(Lumberjack::LINE_SEPARATOR)
+  end
+
   private
 
   # Check if the logger is using a valid Lumberjack::Device::Test device.
@@ -79,27 +108,16 @@ class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
 
   # 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
-
+  def formatted_failure_message(expected_hash)
     message = +"expected logs to include entry:\n" \
       "#{Lumberjack::Device::Test.formatted_expectation(expected_hash, indent: 2)}"
 
     closest_match = device.closest_match(**expected_hash)
     if closest_match
-      message << "\n\nClosest match found:" \
-        "#{Lumberjack::Device::Test.formatted_expectation(closest_match, indent: 2)}"
+      message << "\n\nClosest match found (- expected, + actual):\n" \
+        "#{entry_diff(closest_match, indent: 2)}"
     end
 
     entries = device.entries
@@ -117,11 +135,9 @@ class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
 
   # 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
+  def formatted_negated_failure_message(expected_hash)
     message = "expected logs not to include entry:\n" \
       "#{Lumberjack::Device::Test.formatted_expectation(expected_hash, indent: 2)}"
 
@@ -140,14 +156,133 @@ class Lumberjack::CaptureDevice::IncludeLogEntryMatcher
   # @return [String] A formatted description of the expected attributes.
   def expectation_description(expected_hash)
     info = []
-    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[: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}"
+    info << "severity: #{formatted_value(expected_hash[:severity])}" unless expected_hash[:severity].nil?
+    info << "message: #{formatted_value(expected_hash[:message])}" unless expected_hash[:message].nil?
+    info << "progname: #{formatted_value(expected_hash[:progname])}" unless expected_hash[:progname].nil?
+
+    expected_attributes = expected_hash[:attributes]
+    if expected_attributes.is_a?(Hash)
+      unless expected_attributes.empty?
+        attributes = Lumberjack::Utils.flatten_attributes(expected_attributes)
+        attributes_info = attributes.collect { |name, value| "#{name}=#{formatted_value(value)}" }.join(", ")
+        info << "attributes: #{attributes_info}"
+      end
+    elsif expected_attributes
+      # Matchers like RSpec's hash_including are matched against the attributes hash as a whole.
+      info << "attributes: #{formatted_value(expected_attributes)}"
     end
+
     info.join(", ")
   end
+
+  # Build the matcher used to compare log entries to the expectation. The entry formatter
+  # from the device is used so filter values are matched the same way they are by the
+  # device itself.
+  #
+  # @return [Lumberjack::LogEntryMatcher] The matcher for the expected values.
+  def log_entry_matcher
+    Lumberjack::LogEntryMatcher.new(
+      message: @expected_hash[:message],
+      severity: @expected_hash[:severity],
+      progname: @expected_hash[:progname],
+      attributes: @expected_hash[:attributes],
+      formatter: device&.entry_formatter
+    )
+  end
+
+  # Compare a log entry to the expected values one field at a time. The comparison itself is
+  # done by Lumberjack::LogEntryMatcher#diff which reports only the mismatched fields; the
+  # rest of the entry is filled in from the entry so it can be seen in full.
+  #
+  # @param entry [Lumberjack::LogEntry] The log entry to compare to the expectation.
+  # @return [Array<Array>] An array of [name, expected value, actual value, matched] tuples
+  #   in the order they should be displayed. The values are already formatted for display.
+  def entry_differences(entry)
+    diff = log_entry_matcher.diff(entry)
+    differences = []
+
+    mismatch = diff["severity"]
+    differences << if mismatch
+      # Severities are already reported as labels by the diff.
+      ["severity", mismatch[:expected].to_s, mismatch[:actual].to_s, false]
+    else
+      ["severity", nil, entry.severity_label, true]
+    end
+
+    differences << field_difference("message", diff["message"], entry.message)
+
+    unless diff["progname"].nil? && entry.progname.nil?
+      differences << field_difference("progname", diff["progname"], entry.progname)
+    end
+
+    differences.concat(attribute_differences(entry, diff["attributes"]))
+  end
+
+  # Build the display tuple for a single log entry field.
+  #
+  # @param name [String] The name of the field.
+  # @param mismatch [Hash, nil] The expected and actual values reported by the diff, or nil
+  #   if the field matched the expectation.
+  # @param value [Object] The value from the log entry, used when the field matched.
+  # @return [Array] A [name, expected value, actual value, matched] tuple.
+  def field_difference(name, mismatch, value)
+    if mismatch
+      [name, formatted_value(mismatch[:expected]), formatted_value(mismatch[:actual]), false]
+    else
+      [name, nil, formatted_value(value), true]
+    end
+  end
+
+  # Build the display tuples for the attributes of a log entry. Mismatches are reported by
+  # the diff per attribute using dot notation names. The remaining attributes on the entry
+  # are listed as well, followed by any expected attributes the entry does not have.
+  #
+  # @param entry [Lumberjack::LogEntry] The log entry being compared to the expectation.
+  # @param mismatches [Hash, nil] The attribute mismatches reported by the diff.
+  # @return [Array<Array>] An array of [name, expected value, actual value, matched] tuples.
+  def attribute_differences(entry, mismatches)
+    mismatches ||= {}
+
+    if mismatches.include?(:expected)
+      # Matchers like RSpec's hash_including are matched against the attributes hash as a whole.
+      return [field_difference("attributes", mismatches, nil)]
+    end
+
+    entry_attributes = Lumberjack::Utils.flatten_attributes(entry.attributes || {})
+
+    differences = entry_attributes.collect do |name, value|
+      field_difference("attributes.#{name}", mismatches[name], value)
+    end
+
+    (mismatches.keys - entry_attributes.keys).each do |name|
+      mismatch = mismatches[name]
+      actual = mismatch[:actual].nil? ? MISSING_VALUE : formatted_value(mismatch[:actual])
+      differences << ["attributes.#{name}", formatted_value(mismatch[:expected]), actual, false]
+    end
+
+    differences
+  end
+
+  # The Lumberjack::Device::Test the entries are being matched against.
+  #
+  # @return [Lumberjack::Device::Test, nil] The device, or nil if the logger is not valid.
+  def device
+    return nil unless valid_logger?
+
+    @logger.is_a?(Lumberjack::Device::Test) ? @logger : @logger.device
+  end
+
+  # Format a value for display in a description. Matcher objects (i.e. RSpec matchers)
+  # that implement a +description+ method are displayed using that description since
+  # inspecting them is not very informative.
+  #
+  # @param value [Object] The value to format.
+  # @return [String] The formatted value.
+  def formatted_value(value)
+    if value.respond_to?(:description) && !value.is_a?(Module)
+      value.description.to_s
+    else
+      value.inspect
+    end
+  end
 end

data/lib/lumberjack/capture_device/rspec.rb

@@ -9,15 +9,13 @@ module Lumberjack::CaptureDevice::RSpec
   # 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, Symbol, Integer] :severity The expected log severity.
   # @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")
+  #   expect(logs).to include_log_entry(severity: :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)
@@ -25,8 +23,9 @@ module Lumberjack::CaptureDevice::RSpec
   end
 
   # 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.
+  # replaces the logger's device with a CaptureDevice and sets the log level to debug.
+  # The logger's formatters remain active, so captured entries contain the same
+  # formatted values that would have been logged.
   #
   # @param logger [Lumberjack::Logger] The logger to capture entries from.
   # @yield [device] The block to execute while capturing log entries.
@@ -36,7 +35,7 @@ module Lumberjack::CaptureDevice::RSpec
   #   logs = capture_logger(Rails.logger) do
   #     Rails.logger.info("Test message")
   #   end
-  #   expect(logs).to include_log_entry(level: :info, message: "Test message")
+  #   expect(logs).to include_log_entry(severity: :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
@@ -62,9 +61,8 @@ module Lumberjack::CaptureDevice::RSpec
       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
+        rspec_attributes = {rspec: {location: example.location, description: example.metadata[:description]}}
+        captured_device.write_to_underlying_device(attributes: rspec_attributes)
       end
     end
   end

data/lib/lumberjack/capture_device.rb

@@ -15,9 +15,16 @@ module Lumberjack
     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
-      # the logger. In addition, all formatters will be removed and the log level will be set
-      # to debug. The device being written to be both yielded to the block as well as returned
-      # by the method call.
+      # the logger. In addition, the log level will be set to debug. The logger's formatters
+      # remain active, so captured entries contain the same formatted values that would have
+      # been logged. The device being written to be both yielded to the block as well as
+      # returned by the method call.
+      #
+      # This method is not thread safe. It swaps the device and log level on the logger
+      # itself, so concurrent calls on the same logger will interfere with each other and
+      # entries logged by other threads during the block will be captured as well. The log
+      # level is set on the current context, so threads spawned within the block may not
+      # log at the debug level.
       #
       # @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
@@ -64,11 +71,20 @@ module Lumberjack
     # @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))
+      super({max_entries: 1_000_000}.merge(options))
     end
 
-    # Return all the captured entries that match the specified filters. These filters are
-    # the same as described in the `include?` method.
+    # Return all the captured entries that match the specified filters. The device
+    # `entry_formatter` is used to match the filters, so unformatted values can be used in
+    # the filters if it is set.
+    #
+    # For severity, you can specify either a numeric constant (i.e. `Logger::WARN`) or a symbol
+    # (i.e. `:warn`).
+    #
+    # For message and progname 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.).
     #
     # @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.
@@ -78,21 +94,19 @@ module Lumberjack
     # @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)
+    # @example
+    #   logs.extract(severity: :warn, message: /something happened/, attributes: {user: "john"})
+    def extract(message: nil, severity: nil, attributes: nil, progname: nil, limit: 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
 
-      matcher = LogEntryMatcher.new(message: message, severity: severity, attributes: attributes, progname: progname)
+      matcher = LogEntryMatcher.new(
+        message: message,
+        severity: severity,
+        attributes: attributes,
+        progname: progname,
+        formatter: entry_formatter
+      )
 
       entries.each do |entry|
         matched << entry if matcher.match?(entry)
@@ -102,108 +116,53 @@ module Lumberjack
       matched
     end
 
-    # Return true if the captured log entries match the specified level, message, and attributes.
-    #
-    # For level, you can specify either a numeric constant (i.e. `Logger::WARN`) or a symbol
-    # (i.e. `:warn`).
+    # Return true if the captured log entries match the specified filters. The filters are the
+    # same as the ones used by the `extract` method.
     #
-    # 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 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.
+    # This must be redefined here because Enumerable#include? would otherwise shadow the
+    # implementation inherited from Lumberjack::Device::Test.
     #
     # @example
-    #   logs.include?(level: :warn, message: /something happened/, attributes: {user: "john"})
+    #   logs.include?(severity: :warn, message: /something happened/, attributes: {user: "john"})
     #
     # @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 [String, Symbol, Integer] :severity The severity 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?(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
-
-      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.")
+      filters = filters.transform_keys(&:to_sym)
+      unknown_keys = filters.keys - [:message, :severity, :attributes, :progname]
+      unless unknown_keys.empty?
+        raise ArgumentError, "unknown log filters: #{unknown_keys.map(&:inspect).join(", ")}"
       end
 
-      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 captured entry that matches the filters.
-    #
-    # @param message [String, Regexp, nil] The message 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.
-    # @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
-    # uses fuzzy matching logic to find the best match when no exact match exists.
-    # The matching score is calculated based on how many criteria are met and how closely
-    # 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 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, severity: nil, attributes: nil, progname: nil, level: nil, tags: nil)
-      return nil if length == 0
-
-      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
-      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
-
-      super(
-        message: message,
-        severity: severity || level,
-        attributes: attributes || tags,
-        progname: progname
-      )
+      !!match(**filters)
     end
 
     # Write the captured log entries to the underlying device.
     #
+    # @param attributes [Hash, nil] Additional attributes to add to each entry as it is
+    #   written. Attributes already set on an entry take precedence over these values.
     # @return [void]
-    def write_to_underlying_device
-      write_to(@underlying_device) if @underlying_device
+    def write_to_underlying_device(attributes: nil)
+      return unless @underlying_device
+
+      if attributes.nil? || attributes.empty?
+        write_to(@underlying_device)
+      else
+        extra_attributes = Lumberjack::Utils.expand_attributes(attributes)
+        entries.each do |entry|
+          copy = entry.dup
+          copy.attributes = extra_attributes.merge(Lumberjack::Utils.expand_attributes(entry.attributes || {}))
+          @underlying_device.write(copy)
+        end
+      end
+
+      nil
     end
 
     # Provide a detailed string representation showing all captured entries.
@@ -228,11 +187,20 @@ module Lumberjack
       "<##{self.class.name} #{length} #{(length == 1) ? "entry" : "entries"} captured>"
     end
 
+    # Return a thread-safe copy of all captured log entries. This must be redefined here
+    # because Enumerable#entries would otherwise shadow the thread-safe implementation
+    # inherited from Lumberjack::Device::Test.
+    #
+    # @return [Array<Lumberjack::LogEntry>] A copy of all captured log entries.
+    def entries
+      @lock.synchronize { @buffer.dup }
+    end
+
     # Return the number of captured log entries.
     #
     # @return [Integer] The number of captured entries.
     def length
-      @buffer.length
+      entries.length
     end
 
     alias_method :size, :length
@@ -243,7 +211,7 @@ module Lumberjack
     # @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)
+      entries.each(&block)
     end
   end
 end

data/lumberjack_capture_device.gemspec

@@ -33,6 +33,5 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 2.7"
 
-  spec.add_dependency "lumberjack", ">=2.0"
-  spec.add_development_dependency "bundler"
+  spec.add_dependency "lumberjack", ">= 2.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lumberjack_capture_device
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Brian Durand
@@ -15,28 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.1.0
 email:
 - bbdurand@gmail.com
 executables: []
@@ -48,7 +34,6 @@ files:
 - README.md
 - VERSION
 - lib/lumberjack/capture_device.rb
-- lib/lumberjack/capture_device/entry_score.rb
 - lib/lumberjack/capture_device/include_log_entry_matcher.rb
 - lib/lumberjack/capture_device/rspec.rb
 - lib/lumberjack_capture_device.rb
@@ -74,7 +59,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Testing device for the lumberjack gem that can be used for asserting messages
   have been logged in a test suite.

data/lib/lumberjack/capture_device/entry_score.rb

@@ -1,276 +0,0 @@
-# frozen_string_literal: true
-
-# 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, 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 = []
-
-      # Check message match
-      if message_filter
-        message_score = calculate_field_score(entry.message, message_filter)
-        scores << message_score
-        weights << 0.4  # Weight message matching highly
-      end
-
-      # Check severity match
-      if severity_filter
-        severity_score = if entry.severity == severity_filter
-          1.0  # Exact severity match
-        else
-          severity_proximity_score(entry.severity, severity_filter)  # Partial severity match
-        end
-        scores << severity_score
-        weights << 0.3
-      end
-
-      # Check progname match
-      if progname_filter
-        progname_score = calculate_field_score(entry.progname, progname_filter)
-        scores << progname_score
-        weights << 0.2
-      end
-
-      # 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
-
-      # Return 0 if no criteria were provided
-      return 0.0 if scores.empty?
-
-      # Calculate weighted average, but apply a penalty if any score is 0
-      # This ensures that completely failed criteria significantly impact the result
-      total_weighted_score = scores.zip(weights).map { |score, weight| score * weight }.sum
-      total_weight = weights.sum
-      base_score = total_weighted_score / total_weight
-
-      # Apply penalty for zero scores: reduce the score based on how many criteria completely failed
-      zero_scores = scores.count(0.0)
-      if zero_scores > 0
-        penalty_factor = 1.0 - (zero_scores.to_f / scores.length * 0.5)  # Up to 50% penalty
-        base_score *= penalty_factor
-      end
-
-      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.
-    #
-    # @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
-
-      case filter
-      when String
-        value_str = value.to_s
-        if value_str == filter
-          1.0
-        elsif value_str.include?(filter)
-          0.7
-        else
-          # Use string similarity for partial matching
-          similarity = string_similarity(value_str, filter)
-          (similarity > 0.5) ? similarity * 0.6 : 0.0
-        end
-      when Regexp
-        filter.match?(value.to_s) ? 1.0 : 0.0
-      else
-        # For other matchers (like RSpec matchers), try to use === operator
-        begin
-          (filter === value) ? 1.0 : 0.0
-        rescue
-          0.0
-        end
-      end
-    end
-
-    # 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
-      else 0.0
-      end
-    end
-
-    # 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)
-
-      attributes_filter = deep_stringify_keys(Lumberjack::Utils.expand_attributes(attributes_filter))
-      attributes = deep_stringify_keys(Lumberjack::Utils.expand_attributes(entry_attributes))
-
-      total_attribute_filters = count_attribute_filters(attributes_filter)
-      return 0.0 if total_attribute_filters == 0
-
-      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.
-    #
-    # @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?
-
-      # Convert to lowercase for case-insensitive comparison
-      s1 = str1.downcase
-      s2 = str2.downcase
-
-      # If one string contains the other, give it a good score
-      if s1.include?(s2) || s2.include?(s1)
-        shorter = [s1.length, s2.length].min
-        longer = [s1.length, s2.length].max
-        return shorter.to_f / longer * 0.8 + 0.2  # Boost score for containment
-      end
-
-      # Calculate Levenshtein distance
-      distance = levenshtein_distance(s1, s2)
-      max_length = [s1.length, s2.length].max
-
-      # Convert distance to similarity score
-      return 0.0 if max_length == 0
-
-      1.0 - (distance.to_f / max_length)
-    end
-
-    # 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?
-
-      matrix = Array.new(str1.length + 1) { Array.new(str2.length + 1, 0) }
-
-      # Initialize first row and column
-      (0..str1.length).each { |i| matrix[i][0] = i }
-      (0..str2.length).each { |j| matrix[0][j] = j }
-
-      # Fill the matrix
-      (1..str1.length).each do |i|
-        (1..str2.length).each do |j|
-          cost = (str1[i - 1] == str2[j - 1]) ? 0 : 1
-          matrix[i][j] = [
-            matrix[i - 1][j] + 1,     # deletion
-            matrix[i][j - 1] + 1,     # insertion
-            matrix[i - 1][j - 1] + cost # substitution
-          ].min
-        end
-      end
-
-      matrix[str1.length][str2.length]
-    end
-
-    # 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_attribute_filters(value_filter, count)
-        else
-          count += 1
-        end
-      end
-      count
-    end
-
-    # 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
-
-      attributes_filter.each do |name, value_filter|
-        name = name.to_s
-        attribute_values = attributes[name]
-
-        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|
-          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