ears 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7786b24328603a3d9b231e06400194e69ab38b00de05ec0b0ee5424f0ec3a7b
-  data.tar.gz: 386cedcd1ed08364678da108e1c44e4142d5ba915478476b2d95b14afec3eff3
+  metadata.gz: d9d5a827ad0e368b8243e4e03b00695cd84cd57dbcbb09d4249e97aa84c41f08
+  data.tar.gz: ead5ad7a108d114400bb3819188db589e9d5841bd178efcc9333b4702e91de85
 SHA512:
-  metadata.gz: 841d1b043e68ebbcf850fab367e770e145cf3519d15e33f613db18c41e8df72d2c33d0337b50ba3c18d866894defe32d4584230d78447192eb2ac71b6dea134f
-  data.tar.gz: 7a2bb015f0f4175499c07609cc0ab923af8ecd2157df7a6a57c5c1233c68cfc2d5813ac2452c571551efb83658bfbb5642cf4373bb0efde0a6e9cd88a0530b31
+  metadata.gz: 50a91737737c9344011c0cd44970bb9cbe1aa8b5cc3d904ba1b4301e6076affaea338cbe68af1c4456f380b23d94b81b4f032fc26eda94c81b7b4b14b9777b43
+  data.tar.gz: 2b0644c8648c8bfc1f83349cb1f7342b302fe8b90ef67f76a9ec1013fed1bb0286fcc28c86267a904b281130a0015c20adf64c258a5c052caefcb9c6ff97ca43

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.22.0 (2025-09-11)
+
+- Support publisher confirms in `Ears::Publisher`
+
+## 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.22.0)
       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.22.0)
   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

@@ -197,6 +197,57 @@ rescue => e
 end
 ```
 
+### Publisher Confirms
+
+#### Basic Usage
+
+For guaranteed message delivery, use `publish_with_confirmation` which waits for broker acknowledgment:
+
+```ruby
+publisher = Ears::Publisher.new('events', :topic)
+
+# Publish with confirmation - blocks until broker acknowledges
+publisher.publish_with_confirmation(
+  { user_id: 123, action: 'payment_processed' },
+  routing_key: 'payment.processed',
+)
+```
+
+#### Configuration
+
+Publisher confirms use a separate channel pool with configurable settings:
+
+```ruby
+Ears.configure do |config|
+  # Confirms-specific channel pool size (default: 32)
+  config.publisher_confirms_pool_size = 32
+
+  # Timeout for waiting for confirms in seconds (default: 5.0)
+  config.publisher_confirms_timeout = 5.0
+
+  # Cleanup timeout after confirmation failure (default: 1.0)
+  config.publisher_confirms_cleanup_timeout = 1.0
+end
+```
+
+#### Error Handling
+
+Publisher confirms raise specific exceptions that are NOT automatically retried:
+
+```ruby
+begin
+  publisher.publish_with_confirmation(data, routing_key: 'important.event')
+rescue Ears::PublishConfirmationTimeout => e
+  # Message may or may not have reached broker
+  logger.error "Confirmation timed out: #{e.message}"
+rescue Ears::PublishNacked => e
+  # Broker explicitly rejected the message
+  logger.error "Message was nacked: #{e.message}"
+end
+```
+
+**Note:** Unlike regular publishing, confirmation errors are not retried to avoid message duplication.
+
 ### Basic consumer usage
 
 First, you should configure `Ears`.
@@ -548,6 +599,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/configuration.rb

@@ -17,6 +17,9 @@ module Ears
     DEFAULT_PUBLISHER_MAX_RETRIES = 3
     DEFAULT_PUBLISHER_RETRY_BASE_DELAY = 0.1
     DEFAULT_PUBLISHER_RETRY_BACKOFF_FACTOR = 2
+    DEFAULT_PUBLISHER_CONFIRMS_POOL_SIZE = 32
+    DEFAULT_PUBLISHER_CONFIRMS_TIMEOUT = 5.0
+    DEFAULT_PUBLISHER_CONFIRMS_CLEANUP_TIMEOUT = 1.0
 
     # @return [String] the connection string for RabbitMQ.
     attr_accessor :rabbitmq_url
@@ -57,7 +60,16 @@ module Ears
     # @return [Logger] the logger instance for Ears operations
     attr_accessor :logger
 
-    def initialize
+    # @return [Integer] the size of the publisher confirms channel pool
+    attr_accessor :publisher_confirms_pool_size
+
+    # @return [Float] the timeout in seconds for waiting for publisher confirms
+    attr_accessor :publisher_confirms_timeout
+
+    # @return [Float] the timeout in seconds for cleanup operations after confirmation timeout
+    attr_accessor :publisher_confirms_cleanup_timeout
+
+    def initialize # rubocop:disable Metrics/MethodLength
       @rabbitmq_url = DEFAULT_RABBITMQ_URL
       @recovery_attempts = DEFAULT_RECOVERY_ATTEMPTS
       @publisher_pool_size = DEFAULT_PUBLISHER_POOL_SIZE
@@ -69,6 +81,10 @@ module Ears
       @publisher_max_retries = DEFAULT_PUBLISHER_MAX_RETRIES
       @publisher_retry_base_delay = DEFAULT_PUBLISHER_RETRY_BASE_DELAY
       @publisher_retry_backoff_factor = DEFAULT_PUBLISHER_RETRY_BACKOFF_FACTOR
+      @publisher_confirms_pool_size = DEFAULT_PUBLISHER_CONFIRMS_POOL_SIZE
+      @publisher_confirms_timeout = DEFAULT_PUBLISHER_CONFIRMS_TIMEOUT
+      @publisher_confirms_cleanup_timeout =
+        DEFAULT_PUBLISHER_CONFIRMS_CLEANUP_TIMEOUT
       @logger = Logger.new(IO::NULL)
     end
 

data/lib/ears/errors.rb

@@ -2,4 +2,16 @@ module Ears
   # Error that is raised when the Bunny recovery attempts are exhausted.
   class MaxRecoveryAttemptsExhaustedError < StandardError
   end
+
+  # Base error class for publisher-related errors.
+  class PublishError < StandardError
+  end
+
+  # Error raised when a publisher confirmation times out.
+  class PublishConfirmationTimeout < PublishError
+  end
+
+  # Error raised when a message is nacked by the broker.
+  class PublishNacked < PublishError
+  end
 end

data/lib/ears/publisher.rb

@@ -1,6 +1,8 @@
 require 'bunny'
 require 'ears/publisher_channel_pool'
 require 'ears/publisher_retry_handler'
+require 'ears/publisher_confirmation_handler'
+require 'ears/errors'
 
 module Ears
   # Publisher for sending messages to RabbitMQ exchanges.
@@ -51,6 +53,50 @@ module Ears
       end
     end
 
+    # Publishes a message to the configured exchange with confirmation.
+    # Waits for RabbitMQ to confirm the message was received.
+    #
+    # @param [Hash, Array, Object] data The data to serialize as JSON and publish.
+    # @param [String] routing_key The routing key for the message.
+    #
+    # @option opts [String] :routing_key Routing key
+    # @option opts [Boolean] :persistent Should the message be persisted to disk?
+    # @option opts [Boolean] :mandatory Should the message be returned if it cannot be routed to any queue?
+    # @option opts [Integer] :timestamp A timestamp associated with this message
+    # @option opts [Integer] :expiration Expiration time after which the message will be deleted
+    # @option opts [String] :type Message type, e.g. what type of event or command this message represents. Can be any string
+    # @option opts [String] :reply_to Queue name other apps should send the response to
+    # @option opts [String] :content_type Message content type (e.g. application/json)
+    # @option opts [String] :content_encoding Message content encoding (e.g. gzip)
+    # @option opts [String] :correlation_id Message correlated to this one, e.g. what request this message is a reply for
+    # @option opts [Integer] :priority Message priority, 0 to 9. Not used by RabbitMQ, only applications
+    # @option opts [String] :message_id Any message identifier
+    # @option opts [String] :user_id Optional user ID. Verified by RabbitMQ against the actual connection username
+    # @option opts [String] :app_id Optional application ID
+    #
+    # @raise [PublishConfirmationTimeout] if confirmation times out
+    # @raise [PublishNacked] if message is nacked by the broker
+    # @return [void]
+    def publish_with_confirmation(data, routing_key:, **options)
+      publish_options = default_publish_options.merge(options)
+
+      retry_handler.run do
+        validate_connection!
+
+        PublisherChannelPool.with_channel(confirms: true) do |channel|
+          exchange = create_exchange(channel)
+
+          publisher_confirmation_handler.publish_with_confirmation(
+            channel: channel,
+            exchange: exchange,
+            data: data,
+            routing_key: routing_key,
+            options: publish_options,
+          )
+        end
+      end
+    end
+
     # Resets the channel pool, forcing new channels to be created.
     # This can be useful for connection recovery scenarios.
     #
@@ -68,12 +114,9 @@ module Ears
                 :logger
 
     def publish_with_channel(data:, routing_key:, publish_options:)
-      unless Ears.connection.open?
-        raise PublisherRetryHandler::PublishToStaleChannelError,
-              'Connection is not open'
-      end
+      validate_connection!
 
-      PublisherChannelPool.with_channel do |channel|
+      PublisherChannelPool.with_channel(confirms: false) do |channel|
         exchange = create_exchange(channel)
         exchange.publish(
           data,
@@ -82,6 +125,13 @@ module Ears
       end
     end
 
+    def validate_connection!
+      unless Ears.connection.open?
+        raise PublisherRetryHandler::PublishToStaleChannelError,
+              'Connection is not open'
+      end
+    end
+
     def create_exchange(channel)
       Bunny::Exchange.new(
         channel,
@@ -104,5 +154,10 @@ module Ears
     def retry_handler
       @retry_handler ||= PublisherRetryHandler.new(config, logger)
     end
+
+    def publisher_confirmation_handler
+      @publisher_confirmation_handler ||=
+        PublisherConfirmationHandler.new(config: config, logger: logger)
+    end
   end
 end

data/lib/ears/publisher_channel_pool.rb

@@ -3,50 +3,97 @@ require 'connection_pool'
 module Ears
   # Channel pool management for publishers.
   # Provides thread-safe channel pooling separate from consumer channels.
+  # Maintains two separate pools: one for standard publishing and one for confirmed publishing.
   class PublisherChannelPool
     class << self
-      # Executes the given block with a channel from the pool.
+      # Executes the given block with a channel from the appropriate pool.
       #
+      # @param [Boolean] confirms Whether to use a channel with publisher confirms enabled
       # @yieldparam [Bunny::Channel] channel The channel to use for publishing
       # @return [Object] The result of the block
-      def with_channel(&)
-        channel_pool.with(&)
+      def with_channel(confirms: false, &)
+        # CRITICAL: Preserve fork-safety at the entry point
+        reset! if @creator_pid && @creator_pid != Process.pid
+
+        pool = confirms ? confirms_pool : standard_pool
+        pool.with(&)
       end
 
-      # Resets the channel pool, forcing new channels to be created.
+      # Resets both channel pools, forcing new channels to be created.
       # This is useful for connection recovery scenarios.
       #
       # @return [void]
       def reset!
-        pool = @channel_pool
-        @channel_pool = nil
+        std_pool = @standard_pool
+        cnf_pool = @confirms_pool
+        @standard_pool = nil
+        @confirms_pool = nil
         @creator_pid = nil
 
-        pool&.shutdown(&:close)
+        std_pool&.shutdown(&:close)
+        cnf_pool&.shutdown(&:close)
         nil
       end
 
-      private
+      # Resets only the confirms channel pool, forcing new confirmed channels to be created.
+      # This is useful when confirmation failures occur and channels may have contaminated state.
+      #
+      # @return [void]
+      def reset_confirms_pool!
+        cnf_pool = @confirms_pool
+        @confirms_pool = nil
 
-      def channel_pool
-        # Recreate lazily after a fork
-        reset! if @creator_pid && @creator_pid != Process.pid
+        cnf_pool&.shutdown(&:close)
+        nil
+      end
 
-        return @channel_pool if @channel_pool
+      private
+
+      def standard_pool
+        # CRITICAL: Lazy-init must be thread-safe
+        return @standard_pool if @standard_pool
 
         init_mutex.synchronize do
-          @channel_pool ||=
+          # Double-check in case another thread was waiting
+          @standard_pool ||=
             begin
-              @creator_pid = Process.pid
+              @creator_pid ||= Process.pid
+              create_pool(confirms: false)
+            end
+        end
+      end
+
+      def confirms_pool
+        # CRITICAL: Lazy-init must be thread-safe
+        return @confirms_pool if @confirms_pool
 
-              ConnectionPool.new(
-                size: Ears.configuration.publisher_pool_size,
-                timeout: Ears.configuration.publisher_pool_timeout,
-              ) { Ears.connection.create_channel }
+        init_mutex.synchronize do
+          # Double-check in case another thread was waiting
+          @confirms_pool ||=
+            begin
+              @creator_pid ||= Process.pid
+              create_pool(confirms: true)
             end
         end
       end
 
+      def create_pool(confirms:)
+        ConnectionPool.new(
+          size: pool_size_for(confirms),
+          timeout: Ears.configuration.publisher_pool_timeout,
+        ) do
+          channel = Ears.connection.create_channel
+          channel.confirm_select if confirms
+          channel
+        end
+      end
+
+      def pool_size_for(confirms)
+        return Ears.configuration.publisher_confirms_pool_size if confirms
+
+        Ears.configuration.publisher_pool_size
+      end
+
       def init_mutex
         @init_mutex ||= Mutex.new
       end

data/lib/ears/publisher_confirmation_handler.rb

@@ -0,0 +1,91 @@
+require 'ears/errors'
+
+module Ears
+  # Handles publisher confirmations for RabbitMQ messages.
+  #
+  # This class encapsulates the logic for publishing messages with confirmations,
+  # including timeout handling, channel cleanup, and pool coordination.
+  class PublisherConfirmationHandler
+    # Creates a new confirmation handler.
+    #
+    # @param [Ears::Configuration] config The Ears configuration object.
+    # @param [Logger] logger The logger instance for warnings and errors.
+    def initialize(config:, logger:)
+      @config = config
+      @logger = logger
+    end
+
+    # Publishes a message with confirmation.
+    #
+    # @param [Bunny::Channel] channel The channel to use for publishing.
+    # @param [Bunny::Exchange] exchange The exchange to publish to.
+    # @param [Hash, Array, Object] data The data to publish.
+    # @param [String] routing_key The routing key for the message.
+    # @param [Hash] options The publish options.
+    #
+    # @raise [PublishConfirmationTimeout] if confirmation times out
+    # @raise [PublishNacked] if message is nacked by the broker
+    # @return [void]
+    def publish_with_confirmation(
+      channel:,
+      exchange:,
+      data:,
+      routing_key:,
+      options:
+    )
+      exchange.publish(data, { routing_key: routing_key }.merge(options))
+
+      timeout = config.publisher_confirms_timeout
+      unless wait_for_confirms_with_timeout(channel, timeout)
+        handle_confirmation_failure(channel, timeout)
+      end
+    end
+
+    private
+
+    attr_reader :config, :logger
+
+    def wait_for_confirms_with_timeout(channel, timeout)
+      return channel.wait_for_confirms if timeout.nil?
+
+      waiter = Thread.new { channel.wait_for_confirms }
+
+      return waiter.value if waiter.join(timeout)
+
+      begin
+        channel.close if channel.open?
+      rescue StandardError => e
+        warn("Failed closing channel on timeout: #{e.message}")
+      end
+
+      cleanup_timeout = config.publisher_confirms_cleanup_timeout
+      waiter.join(cleanup_timeout) ||
+        warn('Confirm waiter did not stop promptly after close')
+
+      false
+    end
+
+    def handle_confirmation_failure(channel, timeout)
+      begin
+        channel.close if channel&.open?
+      rescue StandardError => e
+        warn("Failed closing channel on failed confirmation: #{e.message}")
+      end
+
+      PublisherChannelPool.reset_confirms_pool!
+
+      if channel.nacked_set&.any?
+        warn('Publisher confirmation failed: message was nacked by broker.')
+        raise PublishNacked, 'Message was nacked by broker'
+      else
+        warn("Publisher confirmation failed: timeout after #{timeout}s.")
+        raise PublishConfirmationTimeout,
+              "Confirmation timeout after #{timeout}s"
+      end
+    end
+
+    def warn(message)
+      logger.warn(message)
+    end
+  end
+end

data/lib/ears/publisher_retry_handler.rb

@@ -19,6 +19,10 @@ module Ears
       Timeout::Error,
     ].freeze
 
+    # Confirmation errors should NOT be retried - they indicate the message
+    # was published but confirmation failed, so retrying could duplicate the message
+    NON_RETRYABLE_ERRORS = [PublishConfirmationTimeout, PublishNacked].freeze
+
     def initialize(config, logger)
       @config = config
       @logger = logger
@@ -28,6 +32,8 @@ module Ears
       attempt = 1
       begin
         block.call
+      rescue *NON_RETRYABLE_ERRORS => e
+        raise e
       rescue *CONNECTION_ERRORS => e
         attempt = handle_connection_error(e, attempt) # rubocop:disable Lint/UselessAssignment
         retry

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,111 @@
+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)
+          setup_publisher_confirms(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 setup_publisher_confirms(channel)
+        allow(channel).to receive(:confirm_select)
+        allow(channel).to receive(:wait_for_confirms).and_return(true)
+        allow(channel).to receive(:nacked_set).and_return(Set.new)
+        allow(channel).to receive(:open?).and_return(true)
+        allow(channel).to receive(:close)
+      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.22.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ears
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - InVision AG
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-08 00:00:00.000000000 Z
+date: 2025-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -89,8 +89,13 @@ files:
 - lib/ears/middlewares/max_retries.rb
 - lib/ears/publisher.rb
 - lib/ears/publisher_channel_pool.rb
+- lib/ears/publisher_confirmation_handler.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