nats_pubsub 1.0.0

data/lib/nats_pubsub/testing/helpers.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Testing
+    # Helper methods for RSpec tests
+    #
+    # Include this module in your RSpec configuration:
+    #
+    # @example
+    #   RSpec.configure do |config|
+    #     config.include NatsPubsub::Testing::Helpers
+    #   end
+    module Helpers
+      # Setup fake mode for testing (records events without processing)
+      #
+      # @example
+      #   before do
+      #     setup_nats_fake
+      #   end
+      def setup_nats_fake
+        NatsPubsub::Testing.fake!
+      end
+
+      # Setup inline mode for testing (executes subscribers immediately)
+      #
+      # @example
+      #   before do
+      #     setup_nats_inline
+      #   end
+      def setup_nats_inline
+        NatsPubsub::Testing.inline!
+      end
+
+      # Clear published events
+      #
+      # @example
+      #   after do
+      #     clear_nats_events
+      #   end
+      def clear_nats_events
+        NatsPubsub::Testing.clear!
+      end
+
+      # Get all published events
+      #
+      # @return [Array<Hash>] All published events
+      def nats_published_events
+        NatsPubsub::Testing.published_events
+      end
+
+      # Check if an event was published
+      #
+      # @param domain [String] Domain of the event
+      # @param resource [String] Resource type
+      # @param action [String] Action performed
+      # @return [Boolean] true if event was published
+      def nats_event_published?(domain, resource, action)
+        NatsPubsub::Testing.published?(domain, resource, action)
+      end
+
+      # Find published events matching criteria
+      #
+      # @param domain [String, nil] Optional domain filter
+      # @param resource [String, nil] Optional resource filter
+      # @param action [String, nil] Optional action filter
+      # @return [Array<Hash>] Matching published events
+      def find_nats_events(**criteria)
+        NatsPubsub::Testing.find_events(**criteria)
+      end
+
+      # Get the last published event
+      #
+      # @return [Hash, nil] Last published event or nil
+      def last_nats_event
+        NatsPubsub::Testing.last_event
+      end
+
+      # Get count of published events
+      #
+      # @return [Integer] Number of published events
+      def nats_event_count
+        NatsPubsub::Testing.event_count
+      end
+
+      # Create an outbox event for testing
+      #
+      # @param attributes [Hash] Event attributes
+      # @return [OutboxEvent] Created outbox event
+      #
+      # @example
+      #   event = create_outbox_event(
+      #     subject: 'development.app.users.user.created',
+      #     payload: { id: 1, email: 'test@example.com' },
+      #     status: 'pending'
+      #   )
+      def create_outbox_event(**attributes)
+        model = NatsPubsub.config.outbox_model.constantize
+        model.create!(default_outbox_attributes.merge(attributes))
+      end
+
+      # Create an inbox event for testing
+      #
+      # @param attributes [Hash] Event attributes
+      # @return [InboxEvent] Created inbox event
+      #
+      # @example
+      #   event = create_inbox_event(
+      #     subject: 'development.app.users.user.created',
+      #     payload: { id: 1, email: 'test@example.com' },
+      #     status: 'received'
+      #   )
+      def create_inbox_event(**attributes)
+        model = NatsPubsub.config.inbox_model.constantize
+        model.create!(default_inbox_attributes.merge(attributes))
+      end
+
+      # Stub NATS connection to avoid real connections in tests
+      #
+      # @example
+      #   before do
+      #     stub_nats_connection
+      #   end
+      def stub_nats_connection
+        return unless defined?(RSpec)
+
+        connection = instance_double(NatsPubsub::Connection)
+        allow(NatsPubsub::Connection).to receive(:instance).and_return(connection)
+        allow(connection).to receive(:nats).and_return(double('nats', jetstream: double('jetstream')))
+        allow(connection).to receive(:connected?).and_return(true)
+        connection
+      end
+
+      private
+
+      def default_outbox_attributes
+        {
+          event_id: SecureRandom.uuid,
+          subject: 'test.subject',
+          payload: '{}',
+          status: 'pending',
+          attempts: 0
+        }
+      end
+
+      def default_inbox_attributes
+        {
+          event_id: SecureRandom.uuid,
+          subject: 'test.subject',
+          payload: '{}',
+          status: 'received',
+          delivery_count: 1
+        }
+      end
+    end
+
+    # RSpec configuration block for automatic setup
+    #
+    # Add this to your spec_helper.rb or rails_helper.rb:
+    #
+    # @example
+    #   require 'nats_pubsub/testing/helpers'
+    #
+    #   RSpec.configure do |config|
+    #     config.include NatsPubsub::Testing::Helpers
+    #
+    #     config.before(:each, nats_fake: true) do
+    #       setup_nats_fake
+    #     end
+    #
+    #     config.before(:each, nats_inline: true) do
+    #       setup_nats_inline
+    #     end
+    #
+    #     config.after(:each) do
+    #       clear_nats_events if defined?(NatsPubsub::Testing)
+    #     end
+    #   end
+    module RSpecConfiguration
+      def self.configure(config)
+        config.include Helpers
+
+        # Automatically enable fake mode for tests tagged with nats_fake: true
+        config.before(:each, nats_fake: true) do
+          setup_nats_fake
+        end
+
+        # Automatically enable inline mode for tests tagged with nats_inline: true
+        config.before(:each, nats_inline: true) do
+          setup_nats_inline
+        end
+
+        # Clear events after each test
+        config.after(:each) do
+          clear_nats_events if defined?(NatsPubsub::Testing)
+        end
+      end
+    end
+  end
+end

data/lib/nats_pubsub/testing/matchers.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+if defined?(RSpec)
+  # RSpec matchers for NatsPubsub testing
+
+  # Matcher for checking if an event was published
+  #
+  # @example
+  #   expect { user.save }.to have_published_event('users', 'user', 'created')
+  RSpec::Matchers.define :have_published_event do |domain, resource, action|
+    match do |_actual|
+      NatsPubsub::Testing.published_events.any? do |event|
+        event[:domain] == domain &&
+          event[:resource] == resource &&
+          event[:action] == action
+      end
+    end
+
+    failure_message do
+      published = NatsPubsub::Testing.published_events
+                                     .map { |e| "#{e[:domain]}.#{e[:resource]}.#{e[:action]}" }
+                                     .join(', ')
+
+      if published.empty?
+        "expected to publish #{domain}.#{resource}.#{action}, but no events were published"
+      else
+        "expected to publish #{domain}.#{resource}.#{action}, but published: #{published}"
+      end
+    end
+
+    supports_block_expectations
+  end
+
+  # Matcher for checking event payload
+  #
+  # @example
+  #   expect { user.save }.to have_published_event_with_payload('users', 'user', 'created', id: 1)
+  RSpec::Matchers.define :have_published_event_with_payload do |domain, resource, action, expected_payload|
+    match do |_actual|
+      NatsPubsub::Testing.published_events.any? do |event|
+        next false unless event[:domain] == domain &&
+                          event[:resource] == resource &&
+                          event[:action] == action
+
+        # Check if expected payload is a subset of actual payload
+        expected_payload.all? do |key, value|
+          event[:payload][key] == value
+        end
+      end
+    end
+
+    failure_message do
+      matching_events = NatsPubsub::Testing.published_events.select do |e|
+        e[:domain] == domain && e[:resource] == resource && e[:action] == action
+      end
+
+      if matching_events.empty?
+        "expected to publish #{domain}.#{resource}.#{action} with payload #{expected_payload.inspect}, " \
+          "but no matching events were published"
+      else
+        "expected to publish #{domain}.#{resource}.#{action} with payload #{expected_payload.inspect}, " \
+          "but got: #{matching_events.map { |e| e[:payload] }.inspect}"
+      end
+    end
+
+    supports_block_expectations
+  end
+
+  # Matcher for checking outbox event creation
+  #
+  # @example
+  #   expect { publisher.publish('users', 'user', 'created', id: 1) }
+  #     .to enqueue_outbox_event
+  #
+  # @example with subject matching
+  #   expect { publisher.publish('users', 'user', 'created', id: 1) }
+  #     .to enqueue_outbox_event.with_subject_matching(/users\.user\.created/)
+  RSpec::Matchers.define :enqueue_outbox_event do
+    chain :with_subject_matching do |pattern|
+      @subject_pattern = pattern
+    end
+
+    chain :with_status do |status|
+      @status = status
+    end
+
+    chain :with_payload_including do |expected_payload|
+      @expected_payload = expected_payload
+    end
+
+    match do |block|
+      @outbox_model = NatsPubsub.config.outbox_model.constantize
+      @before_count = @outbox_model.count
+
+      block.call
+
+      @after_count = @outbox_model.count
+      @new_events = @outbox_model.last(@after_count - @before_count)
+
+      return false if @new_events.empty?
+
+      @matching_event = @new_events.find do |event|
+        matches_criteria?(event)
+      end
+
+      !@matching_event.nil?
+    end
+
+    def matches_criteria?(event)
+      return false if @subject_pattern && !event.subject.match?(@subject_pattern)
+      return false if @status && event.status != @status
+
+      if @expected_payload
+        payload = parse_payload(event.payload)
+        return false unless payload_matches?(payload, @expected_payload)
+      end
+
+      true
+    end
+
+    def parse_payload(payload)
+      case payload
+      when String
+        JSON.parse(payload).deep_symbolize_keys
+      when Hash
+        payload.deep_symbolize_keys
+      else
+        payload
+      end
+    rescue JSON::ParserError
+      payload
+    end
+
+    def payload_matches?(actual, expected)
+      expected.all? do |key, value|
+        actual[key] == value
+      end
+    end
+
+    failure_message do
+      if @new_events.empty?
+        "expected to enqueue outbox event, but no new events were created"
+      else
+        msg = "expected to enqueue outbox event"
+        msg += " with subject matching #{@subject_pattern.inspect}" if @subject_pattern
+        msg += " with status #{@status.inspect}" if @status
+        msg += " with payload including #{@expected_payload.inspect}" if @expected_payload
+        msg += ", but got:\n"
+        @new_events.each do |event|
+          msg += "  - subject: #{event.subject}, status: #{event.status}\n"
+        end
+        msg
+      end
+    end
+
+    supports_block_expectations
+  end
+
+  # Matcher for checking subscriber registration
+  #
+  # @example
+  #   expect(UserSubscriber).to subscribe_to('development.app.users.user.>')
+  RSpec::Matchers.define :subscribe_to do |subject_pattern|
+    match do |subscriber_class|
+      return false unless subscriber_class.respond_to?(:subjects)
+
+      @actual_subjects = subscriber_class.subjects
+      @actual_subjects.any? do |subject|
+        subject_matches?(subject, subject_pattern)
+      end
+    end
+
+    def subject_matches?(actual, expected)
+      # Exact match
+      return true if actual == expected
+
+      # Wildcard matching
+      actual_parts = actual.split('.')
+      expected_parts = expected.split('.')
+
+      return false if expected_parts.last != '>' && actual_parts.size != expected_parts.size
+
+      expected_parts.each_with_index do |expected_part, i|
+        actual_part = actual_parts[i]
+
+        case expected_part
+        when '*'
+          next
+        when '>'
+          return true
+        else
+          return false if actual_part != expected_part
+        end
+      end
+
+      true
+    end
+
+    failure_message do
+      "expected #{subscriber_class} to subscribe to #{subject_pattern.inspect}, " \
+        "but subscribed to: #{@actual_subjects.inspect}"
+    end
+
+    failure_message_when_negated do
+      "expected #{subscriber_class} not to subscribe to #{subject_pattern.inspect}"
+    end
+  end
+end

data/lib/nats_pubsub/testing/test_harness.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Testing
+    # TestHarness provides comprehensive testing utilities for NatsPubsub
+    #
+    # Features:
+    # - Message capture and inspection
+    # - Inline/synchronous processing for deterministic tests
+    # - DLQ message tracking
+    # - Subscriber call tracking
+    # - Error simulation
+    #
+    # @example Using in RSpec
+    #   RSpec.describe OrderProcessor do
+    #     let(:harness) { NatsPubsub::Testing::TestHarness.new }
+    #
+    #     before { harness.setup }
+    #     after { harness.cleanup }
+    #
+    #     it 'processes orders' do
+    #       harness.publish('order.placed', { id: '123' })
+    #       expect(harness.received('order.placed').size).to eq(1)
+    #       expect(harness.subscriber_called?(OrderSubscriber)).to be true
+    #     end
+    #   end
+    #
+    class TestHarness
+      attr_reader :messages, :dlq_messages, :subscriber_calls, :error_simulations
+
+      # Initialize a new test harness
+      #
+      # @param subscribers [Array<Class>] Subscriber classes to register
+      # @param inline_mode [Boolean] Process messages synchronously
+      def initialize(subscribers: [], inline_mode: true)
+        @subscribers = subscribers
+        @inline_mode = inline_mode
+        @messages = []
+        @dlq_messages = []
+        @subscriber_calls = Hash.new(0)
+        @error_simulations = {}
+      end
+
+      # Setup the test harness
+      #
+      # @return [void]
+      def setup
+        # Enable fake mode
+        NatsPubsub.fake!
+
+        # Register subscribers
+        @subscribers.each do |subscriber_class|
+          register_subscriber(subscriber_class)
+        end
+      end
+
+      # Cleanup after tests
+      #
+      # @return [void]
+      def cleanup
+        clear
+        NatsPubsub.unfake!
+      end
+
+      # Register a subscriber for testing
+      #
+      # @param subscriber_class [Class] Subscriber class
+      # @return [void]
+      def register_subscriber(subscriber_class)
+        subscriber = subscriber_class.new
+
+        # Wrap subscriber to track calls
+        original_call = subscriber.method(:call) if subscriber.respond_to?(:call)
+        original_handle = subscriber.method(:handle) if subscriber.respond_to?(:handle)
+
+        if original_call
+          subscriber.define_singleton_method(:call) do |message, metadata|
+            TestHarness.track_call(subscriber_class, @subscriber_calls)
+            TestHarness.check_error_simulation(subscriber_class, @error_simulations)
+            original_call.call(message, metadata)
+          end
+        end
+
+        if original_handle
+          subscriber.define_singleton_method(:handle) do |message, context|
+            TestHarness.track_call(subscriber_class, @subscriber_calls)
+            TestHarness.check_error_simulation(subscriber_class, @error_simulations)
+            original_handle.call(message, context)
+          end
+        end
+
+        NatsPubsub.register_subscriber(subscriber)
+      end
+
+      # Publish a message for testing
+      #
+      # @param topic [String] Topic to publish to
+      # @param message [Hash] Message payload
+      # @param options [Hash] Publish options
+      # @return [void]
+      def publish(topic, message, **options)
+        # Capture message
+        @messages << {
+          topic: topic,
+          message: message,
+          options: options,
+          timestamp: Time.now
+        }
+
+        # Actually publish
+        NatsPubsub.publish(topic: topic, message: message, **options)
+      end
+
+      # Get all messages received on a topic
+      #
+      # @param topic [String] Topic to filter by
+      # @return [Array<Hash>] Array of captured messages
+      def received(topic)
+        @messages.select { |m| m[:topic] == topic }
+      end
+
+      # Get the last message received on a topic
+      #
+      # @param topic [String] Topic to filter by
+      # @return [Hash, nil] Last captured message or nil
+      def last_message(topic)
+        received(topic).last&.dig(:message)
+      end
+
+      # Check if a subscriber was called
+      #
+      # @param subscriber_class [Class] Subscriber class
+      # @return [Boolean] True if subscriber was called
+      def subscriber_called?(subscriber_class)
+        @subscriber_calls[subscriber_class].positive?
+      end
+
+      # Get the number of times a subscriber was called
+      #
+      # @param subscriber_class [Class] Subscriber class
+      # @return [Integer] Number of calls
+      def subscriber_call_count(subscriber_class)
+        @subscriber_calls[subscriber_class]
+      end
+
+      # Get all DLQ messages
+      #
+      # @return [Array<Hash>] Array of captured DLQ messages
+      def dlq_messages
+        @dlq_messages
+      end
+
+      # Get the last DLQ message
+      #
+      # @return [Hash, nil] Last DLQ message or nil
+      def last_dlq_message
+        @dlq_messages.last
+      end
+
+      # Simulate an error for a subscriber
+      #
+      # @param subscriber_class [Class] Subscriber class
+      # @param error [Exception] Error to raise
+      # @return [void]
+      def simulate_error(subscriber_class, error)
+        @error_simulations[subscriber_class] = error
+      end
+
+      # Clear simulated error for a subscriber
+      #
+      # @param subscriber_class [Class] Subscriber class
+      # @return [void]
+      def clear_simulated_error(subscriber_class)
+        @error_simulations.delete(subscriber_class)
+      end
+
+      # Clear all captured data
+      #
+      # @return [void]
+      def clear
+        @messages.clear
+        @dlq_messages.clear
+        @subscriber_calls.clear
+        @error_simulations.clear
+      end
+
+      # Wait for a condition to be true
+      #
+      # @param timeout [Float] Timeout in seconds
+      # @param interval [Float] Polling interval in seconds
+      # @yield Block that returns true when condition is met
+      # @return [void]
+      # @raise [Timeout::Error] If condition not met within timeout
+      def wait_for(timeout: 5.0, interval: 0.1)
+        start_time = Time.now
+
+        loop do
+          return if yield
+
+          raise Timeout::Error, "Condition not met within #{timeout}s" if Time.now - start_time > timeout
+
+          sleep interval
+        end
+      end
+
+      # Wait for a subscriber to be called
+      #
+      # @param subscriber_class [Class] Subscriber class
+      # @param timeout [Float] Timeout in seconds
+      # @return [void]
+      # @raise [Timeout::Error] If not called within timeout
+      def wait_for_subscriber(subscriber_class, timeout: 5.0)
+        wait_for(timeout: timeout) { subscriber_called?(subscriber_class) }
+      end
+
+      # Wait for messages on a topic
+      #
+      # @param topic [String] Topic to wait for
+      # @param count [Integer] Expected number of messages
+      # @param timeout [Float] Timeout in seconds
+      # @return [void]
+      # @raise [Timeout::Error] If messages not received within timeout
+      def wait_for_messages(topic, count: 1, timeout: 5.0)
+        wait_for(timeout: timeout) { received(topic).size >= count }
+      end
+
+      # Track a subscriber call
+      #
+      # @param subscriber_class [Class] Subscriber class
+      # @param calls_hash [Hash] Subscriber calls hash
+      # @return [void]
+      # @api private
+      def self.track_call(subscriber_class, calls_hash)
+        calls_hash[subscriber_class] += 1
+      end
+
+      # Check for error simulation
+      #
+      # @param subscriber_class [Class] Subscriber class
+      # @param simulations_hash [Hash] Error simulations hash
+      # @return [void]
+      # @raise [Exception] If error is simulated
+      # @api private
+      def self.check_error_simulation(subscriber_class, simulations_hash)
+        error = simulations_hash[subscriber_class]
+        raise error if error
+      end
+    end
+  end
+end