lumberjack_capture_device 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a0dc972c9f7b08468a2c96f2535637fa81bb1ef826123c9f6c582f81fee3b0cd
+  data.tar.gz: 8548fda4d9fcecd7791b948e8922b9394abe0e4fbadd0668a1cb8d15053941e9
+SHA512:
+  metadata.gz: c9d4da5e4da9081d9cd900467b1baa96b7316726fe28c080c1efeb06eaa64f96bc5797fe0fe0a4595c96ddc66105cfe63d30384546718ae690dc3166cff6a871
+  data.tar.gz: d50a5ad769cabe38705f3a9c169e6f7203be84130d2dc008109ca06b704afc176731b46c0d709a2c3085550bf07d1d4763a5012dd214bbfb274c7db3d7a0c311

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+* Initial release.

data/MIT_LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2021 Brian Durand
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,55 @@
+[![Continuous Integration](https://github.com/bdurand/lumberjack_capture_device/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/lumberjack_capture_device/actions/workflows/continuous_integration.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+
+# Lumberjack Capture Device
+
+This is a plugin device for the [lumberjack gem](https://github.com/bdurand/lumberjack) that enables capturing log messages in a test suite so that assertions can be made against them. It provides and easy and stable method of testing that specific log messages are being sent to a logger.
+
+Using mocks and stubs on a logger to test that it receives messages can make for a brittle test suite since there can a wide variety of code writing messages to logs and your test suite may have a higher log level turned on causing it skip messages at a lower level.
+
+For instance, this rspec code can break if any of the code called by the `do_something` writes a different info log message:
+
+```ruby
+do_something
+expect(Rail.logger).to receive(:info).with("Something happened")
+```
+
+It will also break if the test suite logger has the log level set to `warn` or higher since it will then skip all info and debug messages.
+
+## Usage
+
+You can call the `Lumberjack::CaptureDevice.capture` method to override a logger so that it will capture log entries within a block to an in memory buffer. This method will yield the capturing log device as well as return it as the result of the method. The log level will also be temporarily set to debug within the block, so you can capture all log messages without having to change the log level for the entire test suite.
+
+You can use the `include?` method on the log device to determine if specific log entries were made. This would be the equivalent code to the above rspec test, but without the brittleness of mocking method calls:
+
+```ruby
+Lumberjack::CaptureDevice.capture(Rails.logger) do |logs|
+  do_something
+  expect(logs).to include(level: :info, message: "Something happened")
+end
+```
+
+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")
+```
+
+For MiniTest, you could assert:
+
+```ruby
+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. 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.
+
+```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}})
+```
+
+You can also use the `Lumberjack::CaptureDevice#extract` method with the same arguments as used by `include?` to grab all lines that match the filters. And finally, you can access all the log entries with `Lumberjack::CaptureDevice#buffer`.

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/lumberjack_capture_device.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+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
+    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
+      # 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.
+      def capture(logger)
+        device = new
+        save_device = logger.device
+        save_level = logger.level
+        save_formatter = logger.formatter
+        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
+        end
+        device
+      end
+    end
+
+    def initialize
+      @buffer = []
+    end
+
+    def write(entry)
+      @buffer << entry
+    end
+
+    # Clear all entries that have been written to the buffer.
+    def clear
+      @buffer.clear
+    end
+
+    # Return true if the captured log entries match the specified level, message, and tags.
+    #
+    # For level, you can specified 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.
+    #
+    # Example:
+    #
+    # ```
+    # logs.include(level: :warn, message: /something happened/, tags: {duration: instance_of(Float)})
+    # ```
+    def include?(message: nil, level: nil, tags: nil)
+      !extract(message: message, level: level, tags: tags, limit: 1).empty?
+    end
+
+    # Return all the captured entries that match the specified filters. These filters are
+    # the same as described in the `include?` method.
+    def extract(message: nil, level: nil, tags: 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))
+      end
+      @buffer.each do |entry|
+        if matched?(entry, message, level, tags)
+          matches << entry
+          break if limit && matches.size >= limit
+        end
+      end
+      matches
+    end
+
+    private
+
+    def matched?(entry, message_filter, level_filter, tags_filter)
+      match?(entry.message, message_filter) && match?(entry.severity, level_filter) && match_tags?(entry.tags, tags_filter)
+    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?(Lumberjack::Tags.stringify_keys(tag_values), value_filter)
+          else
+            false
+          end
+        elsif tag_values || tags.include?(name)
+          match?(tag_values, value_filter)
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lumberjack_capture_device.gemspec

@@ -0,0 +1,32 @@
+Gem::Specification.new do |spec|
+  spec.name = "lumberjack_capture_device"
+  spec.version = File.read(File.join(__dir__, "VERSION")).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
+
+  spec.summary = "Testing device for the lumberjack gem that can be used for asserting messages have been logged in a test suite."
+  spec.homepage = "https://github.com/bdurand/lumberjack_capture_device"
+  spec.license = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  ignore_files = %w[
+    .
+    Appraisals
+    Gemfile
+    Gemfile.lock
+    Rakefile
+    gemfiles/
+    spec/
+  ]
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.4.0"
+
+  spec.add_dependency "lumberjack", ">=1.1.0"
+  spec.add_development_dependency "bundler"
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lumberjack_capture_device
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brian Durand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-02-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lumberjack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.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'
+description: 
+email:
+- bbdurand@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT_LICENSE.txt
+- README.md
+- VERSION
+- lib/lumberjack_capture_device.rb
+- lumberjack_capture_device.gemspec
+homepage: https://github.com/bdurand/lumberjack_capture_device
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Testing device for the lumberjack gem that can be used for asserting messages
+  have been logged in a test suite.
+test_files: []