ears 0.21.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7786b24328603a3d9b231e06400194e69ab38b00de05ec0b0ee5424f0ec3a7b
-  data.tar.gz: 386cedcd1ed08364678da108e1c44e4142d5ba915478476b2d95b14afec3eff3
+  metadata.gz: 3ffa13eeabb39addd2d5acb749c6edd32515770b357f7ef6cd3f944cc6aae182
+  data.tar.gz: 4aa87462141bd49cbc616dfff68e7d5b5bf24274b7a6c0430ca02182e15259c5
 SHA512:
-  metadata.gz: 841d1b043e68ebbcf850fab367e770e145cf3519d15e33f613db18c41e8df72d2c33d0337b50ba3c18d866894defe32d4584230d78447192eb2ac71b6dea134f
-  data.tar.gz: 7a2bb015f0f4175499c07609cc0ab923af8ecd2157df7a6a57c5c1233c68cfc2d5813ac2452c571551efb83658bfbb5642cf4373bb0efde0a6e9cd88a0530b31
+  metadata.gz: 45a3dffcf2f868f753fc985657bc24909c1bba97f1e633eb012ed4185c231d50edc98093f529b336f1e743dabe374a5ff6e662116d72f74ad5c166c0d81146ff
+  data.tar.gz: 020e285268b69f96269a45e70abdb2287f48ff4346eac060a3dd6c4cebc8c27248f49c045a1c0a0139ea5c8bfc6aafb959634a6c62f945328c9fb1056d71e875

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.21.1 (2025-09-09)
+
+- Add testing abstractions: `Ears::Testing::TestHelper`, `Ears::Testing::MessageCapture`, and `Ears::Testing::PublisherMock`
+
 ## 0.21.0 (2025-09-08)
 
 - Introduce Ears::Publisher with thread-safe channel pooling

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ears (0.21.0)
+    ears (0.21.1)
       bunny (>= 2.22.0)
       connection_pool (~> 2.4)
       multi_json
@@ -113,7 +113,7 @@ CHECKSUMS
   connection_pool (2.5.3) sha256=cfd74a82b9b094d1ce30c4f1a346da23ee19dc8a062a16a85f58eab1ced4305b
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
-  ears (0.21.0)
+  ears (0.21.1)
   json (2.13.2) sha256=02e1f118d434c6b230a64ffa5c8dee07e3ec96244335c392eaed39e1199dbb68
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87

data/README.md

@@ -548,6 +548,115 @@ ensure
 end
 ```
 
+## Testing
+
+Ears provides testing helpers to easily test your message publishing without connecting to RabbitMQ.
+
+### Basic Setup
+
+Include the test helper in your RSpec tests and mock the exchanges you want to test:
+
+```ruby
+require 'ears/testing'
+
+RSpec.describe MyService do
+  include Ears::Testing::TestHelper
+
+  before do
+    # Mock exchanges that your code will publish to
+    mock_ears('events', 'notifications')
+  end
+
+  after do
+    # Clean up mocks and captured messages
+    ears_reset!
+  end
+end
+```
+
+### Capturing and Inspecting Messages
+
+Use the helper methods to inspect published messages:
+
+```ruby
+it 'publishes user creation event' do
+  service = UserService.new
+  service.create_user(name: 'John', email: 'john@example.com')
+
+  # Get all messages published to 'events' exchange
+  messages = published_messages('events')
+  expect(messages.size).to eq(1)
+
+  # Inspect the message
+  message = messages.first
+  expect(message.routing_key).to eq('user.created')
+  expect(message.data).to include(name: 'John')
+  expect(message.options[:headers]).to include(version: '1.0')
+end
+```
+
+### Available Helper Methods
+
+- `published_messages(exchange_name = nil)` - Get messages for a specific exchange or all messages
+- `last_published_message(exchange_name = nil)` - Get the most recent message
+- `clear_published_messages` - Clear captured messages during a test
+
+### Message Properties
+
+Each captured message has the following properties:
+
+- `exchange_name` - Name of the exchange
+- `routing_key` - Message routing key
+- `data` - The message payload
+- `options` - Publishing options (headers, persistent, etc.)
+- `timestamp` - When the message was captured
+- `thread_id` - Thread that published the message
+
+### Error Handling
+
+By default, publishing to unmocked exchanges raises an error:
+
+```ruby
+it 'raises error for unmocked exchanges' do
+  publisher = Ears::Publisher.new('unmocked_exchange')
+
+  expect {
+    publisher.publish({ data: 'test' }, routing_key: 'test')
+  }.to raise_error(Ears::Testing::UnmockedExchangeError)
+end
+```
+
+### Complete Example
+
+```ruby
+require 'ears/testing'
+
+RSpec.describe OrderProcessor do
+  include Ears::Testing::TestHelper
+
+  before { mock_ears('events', 'notifications') }
+  after { ears_reset! }
+
+  it 'publishes events when processing order' do
+    processor = OrderProcessor.new
+    order = { id: 123, items: ['item1'], total: 99.99 }
+
+    processor.process(order)
+
+    # Check event was published
+    events = published_messages('events')
+    expect(events.size).to eq(1)
+    expect(events.first.routing_key).to eq('order.processed')
+    expect(events.first.data[:order_id]).to eq(123)
+
+    # Check notification was sent
+    notifications = published_messages('notifications')
+    expect(notifications.size).to eq(1)
+    expect(notifications.first.routing_key).to eq('email.order_confirmation')
+  end
+end
+```
+
 ## Documentation
 
 If you need more in-depth information, look at [our API documentation](https://www.rubydoc.info/gems/ears).

data/lib/ears/testing/message_capture.rb

@@ -0,0 +1,89 @@
+module Ears
+  module Testing
+    class MessageCapture
+      Message =
+        Struct.new(
+          :exchange_name,
+          :routing_key,
+          :data,
+          :options,
+          :timestamp,
+          :thread_id,
+          keyword_init: true,
+        )
+
+      def initialize
+        @messages = {}
+        @mutex = Mutex.new
+      end
+
+      def add_message(exchange_name, data, routing_key, options = {})
+        @mutex.synchronize do
+          @messages[exchange_name] ||= []
+
+          message =
+            Message.new(
+              exchange_name: exchange_name,
+              routing_key: routing_key,
+              data: data,
+              options: options,
+              timestamp: Time.now,
+              thread_id: Thread.current.object_id.to_s,
+            )
+
+          @messages[exchange_name] << message
+
+          shift_messages(exchange_name)
+
+          message
+        end
+      end
+
+      def messages_for(exchange_name)
+        @mutex.synchronize { (@messages[exchange_name] || []).dup }
+      end
+
+      def all_messages
+        @mutex.synchronize { @messages.values.flatten }
+      end
+
+      def clear
+        @mutex.synchronize { @messages.clear }
+      end
+
+      def count(exchange_name = nil)
+        @mutex.synchronize do
+          return (@messages[exchange_name] || []).size if exchange_name
+
+          @messages.values.sum(&:size)
+        end
+      end
+
+      def empty?
+        @mutex.synchronize do
+          @messages.empty? || @messages.values.all?(&:empty?)
+        end
+      end
+
+      def find_messages(exchange_name: nil, routing_key: nil, data: nil)
+        messages = exchange_name ? messages_for(exchange_name) : all_messages
+
+        messages.select do |msg|
+          next false if routing_key && msg.routing_key != routing_key
+          next false if data && msg.data != data
+
+          true
+        end
+      end
+
+      private
+
+      def shift_messages(exchange_name)
+        max_messages = Ears::Testing.configuration.max_captured_messages
+        if @messages[exchange_name].size > max_messages
+          @messages[exchange_name].shift
+        end
+      end
+    end
+  end
+end

data/lib/ears/testing/publisher_mock.rb

@@ -0,0 +1,102 @@
+require 'rspec/mocks'
+
+module Ears
+  module Testing
+    class UnmockedExchangeError < StandardError
+    end
+
+    class PublisherMock
+      include RSpec::Mocks::ExampleMethods
+
+      def initialize(exchange_names, message_capture)
+        @exchange_names = Array(exchange_names)
+        @message_capture = message_capture
+        @mock_exchanges = {}
+      end
+
+      def setup_mocks
+        setup_connection
+        setup_channel_pool
+      end
+
+      private
+
+      attr_reader :exchange_names, :message_capture, :mock_exchanges
+
+      def setup_connection
+        mock_connection = instance_double(Bunny::Session, open?: true)
+        Ears.instance_variable_set(:@connection, mock_connection)
+      end
+
+      def setup_channel_pool
+        mock_channel = create_mock_channel
+        allow(Ears::PublisherChannelPool).to receive(:with_channel).and_yield(
+          mock_channel,
+        )
+        mock_channel
+      end
+
+      def create_mock_channel
+        instance_double(Bunny::Channel).tap do |channel|
+          setup_exchange_declare(channel)
+          setup_register_exchange(channel)
+          setup_basic_publish(channel)
+        end
+      end
+
+      def setup_exchange_declare(channel)
+        allow(channel).to receive(:exchange_declare) do |name, type, options|
+          create_or_get_mock_exchange(name, type, options)
+        end
+      end
+
+      def setup_register_exchange(channel)
+        allow(channel).to receive(:register_exchange)
+      end
+
+      def setup_basic_publish(channel)
+        allow(channel).to receive(
+          :basic_publish,
+        ) do |data, exchange, routing_key, options|
+          if exchange_names.include?(exchange)
+            capture_message(exchange, data, routing_key, options)
+          elsif strict_mocking?
+            raise_unmocked_exchange_error(exchange)
+          end
+        end
+      end
+
+      def create_or_get_mock_exchange(name, type, _options)
+        mock_exchanges[name] ||= create_mock_exchange(name, type)
+      end
+
+      def create_mock_exchange(name, type)
+        exchange = instance_double(Bunny::Exchange, name: name, type: type)
+
+        setup_exchange_publish(exchange, name)
+
+        exchange
+      end
+
+      def setup_exchange_publish(exchange, name)
+        allow(exchange).to receive(:publish) do |data, routing_options|
+          routing_key = routing_options[:routing_key]
+          capture_message(name, data, routing_key, routing_options)
+        end
+      end
+
+      def capture_message(exchange_name, data, routing_key, options)
+        message_capture.add_message(exchange_name, data, routing_key, options)
+      end
+
+      def strict_mocking?
+        Ears::Testing.configuration.strict_exchange_mocking
+      end
+
+      def raise_unmocked_exchange_error(exchange)
+        raise UnmockedExchangeError,
+              "Exchange '#{exchange}' has not been mocked. Add mock_ears('#{exchange}') to your test setup."
+      end
+    end
+  end
+end

data/lib/ears/testing/test_helper.rb

@@ -0,0 +1,50 @@
+require 'rspec/mocks'
+
+module Ears
+  module Testing
+    module TestHelper
+      include RSpec::Mocks::ExampleMethods
+
+      def mock_ears(*exchange_names)
+        Ears::Testing.message_capture ||= MessageCapture.new
+
+        @original_connection = Ears.instance_variable_get(:@connection)
+
+        publisher_mock =
+          PublisherMock.new(exchange_names, Ears::Testing.message_capture)
+        publisher_mock.setup_mocks
+      end
+
+      def ears_reset!
+        Ears::Testing.message_capture = nil
+
+        if instance_variable_defined?(:@original_connection)
+          Ears.instance_variable_set(:@connection, @original_connection)
+          remove_instance_variable(:@original_connection)
+        end
+
+        if defined?(Ears::PublisherChannelPool)
+          Ears::PublisherChannelPool.reset!
+        end
+      end
+
+      def published_messages(exchange_name = nil)
+        return [] unless Ears::Testing.message_capture
+
+        if exchange_name
+          return Ears::Testing.message_capture.messages_for(exchange_name)
+        end
+
+        Ears::Testing.message_capture.all_messages
+      end
+
+      def last_published_message(exchange_name = nil)
+        published_messages(exchange_name).last
+      end
+
+      def clear_published_messages
+        Ears::Testing.message_capture&.clear
+      end
+    end
+  end
+end

data/lib/ears/testing.rb

@@ -0,0 +1,37 @@
+require 'ears'
+require 'ears/testing/test_helper'
+require 'ears/testing/message_capture'
+require 'ears/testing/publisher_mock'
+
+module Ears
+  module Testing
+    class << self
+      attr_accessor :message_capture
+
+      def configure
+        yield(configuration) if block_given?
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def reset!
+        @message_capture = nil
+        @configuration = nil
+      end
+    end
+
+    class Configuration
+      attr_accessor :max_captured_messages,
+                    :auto_cleanup,
+                    :strict_exchange_mocking
+
+      def initialize
+        @max_captured_messages = 1000
+        @auto_cleanup = true
+        @strict_exchange_mocking = true
+      end
+    end
+  end
+end

data/lib/ears/version.rb

@@ -1,3 +1,3 @@
 module Ears
-  VERSION = '0.21.0'
+  VERSION = '0.21.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ears
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.21.1
 platform: ruby
 authors:
 - InVision AG
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-08 00:00:00.000000000 Z
+date: 2025-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -91,6 +91,10 @@ files:
 - lib/ears/publisher_channel_pool.rb
 - lib/ears/publisher_retry_handler.rb
 - lib/ears/setup.rb
+- lib/ears/testing.rb
+- lib/ears/testing/message_capture.rb
+- lib/ears/testing/publisher_mock.rb
+- lib/ears/testing/test_helper.rb
 - lib/ears/version.rb
 - package-lock.json
 - package.json