hubbado-log 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49c303fe323be43f901ed8ef3958b87c79296af3a15efb11c9efb8a9b57156aa
-  data.tar.gz: 97bc2f947b3a4fc0cfd1845c34d722d6608cf36c1daf853334d3b3b03c4171b5
+  metadata.gz: c548a1c52601a45c8ffb53337dcfe28805e63cbe868d90692f5bff54b8fc4f82
+  data.tar.gz: da676bfa5ff5ee43efa7660412ea53da1c307e4fdadf8570cc6bd1251178c60b
 SHA512:
-  metadata.gz: fde7c3bf0995e34348f47a8441df1b95cf9505c909b08bac8fcc409f994ce8c8eb28cb05343e24b4066977a804434ced09cad3fb36e75908e375d3bddbc81304
-  data.tar.gz: 4f4cae84446c3d1bdf8a9ebb2b986f82a558c623af90a3278c62fa67ee8a23a55163129efc787758b5434faf101346e15187c9f112007333b7295cb26cf3648f
+  metadata.gz: d7a795d9bc507c468e12232058d413c916f8f6e155f68793e6305314c50c7bf8e5528a690280c9b9b265824cf6e8cb6e428741aaa4df0abe6550dcf9cc0fb636
+  data.tar.gz: 308912bee3a3af9ca487628ba15cadbe74f33fdce80ee329585229a34b7bae25f832167c2d7250189fa50b6d30c0ad4d7a3e07fdb78e8e207f0032f8f31d44b0

data/ChangeLog.md

@@ -4,6 +4,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+# [1.4.0 - 2026-08-16]
+## Added
+- A substitute for a logger. `Controls::Logger.example` returns one, and a spec
+  assigns it where a class's logger goes:
+
+  ```ruby
+  instance.logger = Hubbado::Log::Controls::Logger.example
+
+  instance.()
+
+  assert instance.logger.logged?(:error)
+  ```
+
+  It records what it was told rather than writing, so no handler is involved and
+  neither the level nor the tag list decides what a spec can read back.
+
+  Three questions, each taking an optional severity, and each answering in the
+  terms its name promises:
+
+  | Call | Answers |
+  |---|---|
+  | `logged?(:warn)` | whether anything was written at that severity |
+  | `messages(:warn)` | what it said — the message strings |
+  | `logged(:warn)` | everything about what it said — `severity`, `message`, `data` |
+
+  `messages` and `logged?` are both derived from `logged`, so the three cannot
+  disagree about what counts as written at a severity.
+
+  A severity reaches a logger two ways — as the generated method, or as `#log`'s
+  first argument — and both answer the same question, compared as symbols.
+
+- `evt-subst_attr` as a runtime dependency. The substitute is a mimic of `Logger`
+  extended with `Logger::Substitute`, so it answers `is_a?(Logger)` for a class
+  that checks, and gains any method `Logger` gains.
+
+## Deprecated
+- `Controls::LogHandler` as the way a consumer reads back what a class logged.
+  It builds a real `Logger` and then passes `level: :trace` and `tags: Tags::ALL`
+  to switch off the filtering it just built — which is a substitute, reached the
+  long way round. Use `Controls::Logger.example`. The handler control stays for
+  what it is good at: specs where a handler receiving, or not receiving, a
+  message is the subject, as `'A message the filter left out'` is.
+
+## Changed
+- `Controls::LogHandler` names `Log::Logger` where it said `Logger`. With
+  `Controls::Logger` defined, a bare `Logger` inside `Controls` resolves to the
+  control rather than to the class.
+
+## Compatibility
+Nothing that exists breaks. `Controls::LogHandler` keeps `.attach`, `.logger`,
+`messages`, `logged?`, `reset` and the attributes, unchanged.
+
 # [1.3.0 - 2026-08-15]
 ## Added
 - Tags, a second filtering axis beside the level. A message names its concern

data/README.md

@@ -111,6 +111,67 @@ knowing before adopting tags:
 list decides for both, and an application whose messages are all untagged goes silent unless the
 list contains `_untagged`.
 
+## Reading back what a class logged
+
+A spec assigns a substitute where the class's logger goes, and then asks what the class said:
+
+```ruby
+require 'hubbado/log/controls'
+
+instance.logger = Hubbado::Log::Controls::Logger.example
+
+instance.()
+
+assert instance.logger.logged?(:error)
+```
+
+For a class handed a logger rather than carrying one — the shape a CLI usually takes — it is the
+same object, passed in:
+
+```ruby
+logger = Hubbado::Log::Controls::Logger.example
+
+CLI.run(argv, logger: logger)
+
+assert logger.logged?(:error)
+```
+
+It records what it was told rather than writing, so no handler is involved and neither the
+configured level nor `LOG_TAGS` decides what can be read back.
+
+Three questions, each taking an optional severity:
+
+| Call | Answers |
+|---|---|
+| `logged?` / `logged?(:warn)` | whether anything was written, at all or at that severity |
+| `messages` / `messages(:warn)` | what it said — the message strings, in order |
+| `logged` / `logged(:warn)` | everything about what it said |
+
+`logged` answers with entries carrying `severity`, `message` and `data`, for the assertion that
+needs more than the text:
+
+```ruby
+assert logger.logged(:error).first.data.equal?(exception)
+```
+
+`messages` and `logged?` are both derived from `logged`, so the three cannot disagree about what
+counts as written at a severity.
+
+A severity reaches a logger two ways — `logger.warn('…')` names it as the method,
+`logger.log(:warn, '…')` as an argument — and both answer the same question, compared as symbols.
+
+The substitute is a mimic of `Logger`, so it answers `is_a?(Hubbado::Log::Logger)` for a class
+that checks, and gains any method `Logger` gains.
+
+Prefer `logged?` to reaching into `messages` where it will do. That a failure was reported is
+usually the contract; the wording of the line usually is not.
+
+### Testing a handler
+
+`Controls::LogHandler` is for specs where a handler receiving — or not receiving — a message is
+itself the subject, which in practice means this gem's own tests of level and tag filtering. A
+consumer asserting that its class logged something wants the substitute above.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/hubbado-log.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "hubbado-log"
-  s.version = "1.3.0"
+  s.version = "1.4.0"
   s.summary = "Lightweight pluggable logging system"
 
   s.authors = ["Hubbado Devs"]
@@ -25,6 +25,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 3.2'
 
   s.add_runtime_dependency 'evt-dependency'
+  s.add_runtime_dependency 'evt-subst_attr'
 
   s.add_development_dependency "debug"
   s.add_development_dependency "hubbado-style"

data/lib/hubbado/log/controls/log_handler.rb

@@ -20,7 +20,7 @@ module Hubbado
           end
 
           new.tap do |handler|
-            instance.logger = Logger.new(logger.subject, [handler], level: level, tags: tags)
+            instance.logger = Log::Logger.new(logger.subject, [handler], level: level, tags: tags)
           end
         end
 
@@ -28,7 +28,7 @@ module Hubbado
         def self.logger(subject = Subject.example, level: :trace, tags: Tags::ALL)
           handler = new
 
-          [handler, Logger.new(subject, [handler], level: level, tags: tags)]
+          [handler, Log::Logger.new(subject, [handler], level: level, tags: tags)]
         end
 
         def log(subject, severity, message, data = nil, stacktrace = nil)

data/lib/hubbado/log/controls/logger.rb

@@ -0,0 +1,16 @@
+require 'subst_attr'
+
+module Hubbado
+  class Log
+    module Controls
+      module Logger
+        # A logger a spec assigns in place of a class's own, and then asks what the class said.
+        # Named here because the substitute is reached by building a mimic of Log::Logger, which
+        # is machinery a spec should not have to name.
+        def self.example
+          SubstAttr::Substitute.build(Log::Logger)
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/log/controls.rb

@@ -4,3 +4,4 @@ require_relative 'controls/message'
 require_relative 'controls/subject'
 
 require_relative 'controls/log_handler'
+require_relative 'controls/logger'

data/lib/hubbado/log/logger/substitute.rb

@@ -0,0 +1,50 @@
+module Hubbado
+  class Log
+    class Logger
+      # What a logger was told rather than what it wrote. Extended onto a mimic of Logger, so a
+      # class under test is handed something that answers as a logger and keeps what it was given.
+      module Substitute
+        Entry = Data.define(:severity, :message, :data)
+
+        # Everything about what a class said, in order. Named with a severity, only what it said
+        # at that one.
+        #
+        # A severity reaches a logger two ways: as the method, from the generated severity
+        # methods, or as #log's first argument. Both are compared as symbols, because #log takes
+        # a String as readily and passes on what it was given.
+        def logged(severity = nil)
+          entries = invocations.map { |invocation| entry(invocation) }
+
+          return entries if severity.nil?
+
+          entries.select { |entry| entry.severity == severity.to_s.to_sym }
+        end
+
+        # What a class said, where #logged is everything about it.
+        def messages(severity = nil) = logged(severity).map(&:message)
+
+        # Whether, where #logged and #messages ask what. Without a severity, whether anything was
+        # written at all.
+        def logged?(severity = nil) = !logged(severity).empty?
+
+        private
+
+        def entry(invocation)
+          arguments = invocation.arguments
+
+          Entry.new(
+            severity: severity(invocation).to_s.to_sym,
+            message: arguments[:msg],
+            data: arguments[:data]
+          )
+        end
+
+        def severity(invocation)
+          return invocation.arguments.fetch(:severity) if invocation.method_name == :log
+
+          invocation.method_name
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/log.rb

@@ -3,6 +3,7 @@ require "hubbado/log/tags"
 require "hubbado/log/configuration"
 require "hubbado/log/log"
 require "hubbado/log/logger"
+require "hubbado/log/logger/substitute"
 require "hubbado/log/log_handler"
 
 module Hubbado

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-log
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Hubbado Devs
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-subst_attr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -81,11 +95,13 @@ files:
 - lib/hubbado/log/controls/data.rb
 - lib/hubbado/log/controls/exception.rb
 - lib/hubbado/log/controls/log_handler.rb
+- lib/hubbado/log/controls/logger.rb
 - lib/hubbado/log/controls/message.rb
 - lib/hubbado/log/controls/subject.rb
 - lib/hubbado/log/log.rb
 - lib/hubbado/log/log_handler.rb
 - lib/hubbado/log/logger.rb
+- lib/hubbado/log/logger/substitute.rb
 - lib/hubbado/log/tags.rb
 homepage: https://www.github.com/hubbado/hubbado-log
 licenses: