karafka-testing 2.2.0 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84ae796af17d02ace2ed5130aab0d964ea724bcd5b8379f954b3b93d265afbf2
-  data.tar.gz: 938a1f00fa6b1670d6cf8c6a045426c17ad9964398e6f3e16785ee927f21be93
+  metadata.gz: a79a60538d27c37844e17b112d7640e9ee9d975c8537bb2b78d8b8399faf656b
+  data.tar.gz: bcd86d7094908a5ac1e261651722f387c4188772890da390cadd19ed874aef04
 SHA512:
-  metadata.gz: 7229353c31414e28d97b0d498ec0a92d628432d8544b3a34811d518681607573ab2734c75ea936cb25666e1f12dbcce7c6de8fda2e39e2ce7f5f1c394759ec2a
-  data.tar.gz: 0a5b5db670109114c6fbb77e6da81fde0215dbe2c2b38dc95cc063654cc349d836fde8dd09a18fa76a52a50c0560529c4ddd0971b5e4da1ae37a50845e103c08
+  metadata.gz: abc39e5c005227a77ba7145e263c93e10c8c3e0406cdccf66cc3406c72d479436f8b3f0a1f665d5f793c3b416760d87beb02f25f319594e1bbc9d9093537a7da
+  data.tar.gz: 91c4255aa2897199498879a7e400b6609204d322c39307ba131449752d9b6b562fca70d37513170e1c6563ee351018a7c8bb11ec9e833e426020cb2bec011e67

data/.github/workflows/ci.yml

@@ -1,6 +1,8 @@
 name: ci
 
-concurrency: ci-${{ github.ref }}
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 on:
   pull_request:
@@ -16,6 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
+          - '3.3.0-preview2'
           - '3.2'
           - '3.1'
           - '3.0'
@@ -24,7 +27,7 @@ jobs:
           - ruby: '3.2'
             coverage: 'true'
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install package dependencies
         run: "[ -e $APT_DEPS ] || sudo apt-get install -y --no-install-recommends $APT_DEPS"
       - name: Set up Ruby
@@ -43,7 +46,7 @@ jobs:
     strategy:
       fail-fast: false
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Set up Ruby
@@ -62,7 +65,7 @@ jobs:
     strategy:
       fail-fast: false
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Run Coditsu

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Karafka Test gem changelog
 
-## 2.2.0 (2023-09-91)
+## 2.2.2 (2023-11-16)
+- [**Feature**] Provide support for Minitest (ValentinoRusconi-EH)
+
+## 2.2.1 (2023-10-26)
+- [Enhancement] Support patterns in `#consumer_for` consumer builder.
+
+## 2.2.0 (2023-09-01)
 - [Maintenance] Ensure that `2.2.0` works with consumers for patterns.
 - [Maintenance] Replace signing key with a new one (old expired).
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    karafka-testing (2.2.0)
+    karafka-testing (2.2.2)
       karafka (>= 2.2.0, < 3.0.0)
       waterdrop (>= 2.6.6)
 

data/karafka-testing.gemspec

@@ -30,7 +30,7 @@ Gem::Specification.new do |spec|
   spec.metadata = {
     'funding_uri' => 'https://karafka.io/#become-pro',
     'homepage_uri' => 'https://karafka.io',
-    'changelog_uri' => 'https://github.com/karafka/karafka-testing/blob/master/CHANGELOG.md',
+    'changelog_uri' => 'https://karafka.io/docs/Changelog-Karafka-Testing',
     'bug_tracker_uri' => 'https://github.com/karafka/karafka-testing/issues',
     'source_code_uri' => 'https://github.com/karafka/karafka-testing',
     'documentation_uri' => 'https://karafka.io/docs',

data/lib/karafka/testing/errors.rb

@@ -13,6 +13,9 @@ module Karafka
 
       # Raised when topic is in many consumer groups and not limited by consumer group expectation
       TopicInManyConsumerGroupsError = Class.new(BaseError)
+
+      # Raised when you requested a topic from a consumer group that does not exist
+      ConsumerGroupNotFound = Class.new(BaseError)
     end
   end
 end

data/lib/karafka/testing/minitest/helpers.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require 'karafka/testing/errors'
+require 'karafka/testing/spec_consumer_client'
+require 'karafka/testing/spec_producer_client'
+require 'karafka/testing/minitest/proxy'
+
+module Karafka
+  module Testing
+    # All the things related to extra functionalities needed to easier spec out
+    # Karafka things using Minitest
+    module Minitest
+      # Minitest helpers module that needs to be included
+      module Helpers
+        class << self
+          # Adds all the needed extra functionalities to the minitest group
+          # @param base [Class] Minitest example group we want to extend
+          def included(base)
+            base.class_eval do
+              setup do
+                @karafka = Karafka::Testing::Minitest::Proxy.new(self)
+                @_karafka_consumer_messages = []
+                @_karafka_consumer_client = Karafka::Testing::SpecConsumerClient.new
+                @_karafka_producer_client = Karafka::Testing::SpecProducerClient.new(self)
+
+                @_karafka_consumer_messages.clear
+                @_karafka_producer_client.reset
+
+                Karafka.producer.stubs(:client).returns(@_karafka_producer_client)
+              end
+            end
+          end
+        end
+
+        # Creates a consumer instance for a given topic
+        #
+        # @param requested_topic [String, Symbol] name of the topic for which we want to
+        #   create a consumer instance
+        # @param requested_consumer_group [String, Symbol, nil] optional name of the consumer group
+        #   if we have multiple consumer groups listening on the same topic
+        # @return [Object] Karafka consumer instance
+        # @raise [Karafka::Testing::Errors::TopicNotFoundError] raised when we're unable to find
+        #   topic that was requested
+        #
+        # @example Creates a consumer instance with settings for `my_requested_topic`
+        #   consumer = @karafka.consumer_for(:my_requested_topic)
+        def _karafka_consumer_for(requested_topic, requested_consumer_group = nil)
+          selected_topics = _karafka_consumer_find_candidate_topics(
+            requested_topic.to_s,
+            requested_consumer_group.to_s
+          )
+
+          raise Errors::TopicInManyConsumerGroupsError, requested_topic if selected_topics.size > 1
+          raise Errors::TopicNotFoundError, requested_topic if selected_topics.empty?
+
+          _karafka_build_consumer_for(selected_topics.first)
+        end
+
+        # Adds a new Karafka message instance if needed with given payload and options into an
+        # internal consumer buffer that will be used to simulate messages delivery to the consumer
+        #
+        # @param message [Hash] message that was sent to Kafka
+        #
+        # @example Send a json message to consumer
+        #   @karafka.produce({ 'hello' => 'world' }.to_json)
+        #
+        # @example Send a json message to consumer and simulate, that it is partition 6
+        #   @karafka.produce({ 'hello' => 'world' }.to_json, 'partition' => 6)
+        def _karafka_add_message_to_consumer_if_needed(message)
+          # Consumer needs to be defined in order to pass messages to it
+          return unless defined?(@consumer)
+          # We're interested in adding message to consumer only when it is a Karafka consumer
+          # Users may want to test other things (models producing messages for example) and in
+          # their case consumer will not be a consumer
+          return unless @consumer.is_a?(Karafka::BaseConsumer)
+          # We target to the consumer only messages that were produced to it, since specs may also
+          # produce other messages targeting other topics
+          return unless message[:topic] == @consumer.topic.name
+
+          # Build message metadata and copy any metadata that would come from the message
+          metadata = _karafka_message_metadata_defaults
+
+          metadata.keys.each do |key|
+            next unless message.key?(key)
+
+            metadata[key] = message.fetch(key)
+          end
+          # Add this message to previously produced messages
+          @_karafka_consumer_messages << Karafka::Messages::Message.new(
+            message[:payload],
+            Karafka::Messages::Metadata.new(metadata).freeze
+          )
+          # Update batch metadata
+          batch_metadata = Karafka::Messages::Builders::BatchMetadata.call(
+            @_karafka_consumer_messages,
+            @consumer.topic,
+            0,
+            Time.now
+          )
+
+          # Update consumer messages batch
+          @consumer.messages = Karafka::Messages::Messages.new(
+            @_karafka_consumer_messages,
+            batch_metadata
+          )
+        end
+
+        # Produces message with a given payload to the consumer matching topic
+        # @param payload [String] payload we want to dispatch
+        # @param metadata [Hash] any metadata we want to dispatch alongside the payload
+        def _karafka_produce(payload, metadata = {})
+          Karafka.producer.produce_sync(
+            {
+              topic: @consumer.topic.name,
+              payload: payload
+            }.merge(metadata)
+          )
+        end
+
+        # @return [Array<Hash>] messages that were produced
+        def _karafka_produced_messages
+          @_karafka_producer_client.messages
+        end
+
+        private
+
+        # @return [Hash] message default options
+        def _karafka_message_metadata_defaults
+          {
+            deserializer: @consumer.topic.deserializer,
+            timestamp: Time.now,
+            headers: {},
+            key: nil,
+            offset: @_karafka_consumer_messages.size,
+            partition: 0,
+            received_at: Time.now,
+            topic: @consumer.topic.name
+          }
+        end
+
+        # Builds the consumer instance based on the provided topic
+        #
+        # @param topic [Karafka::Routing::Topic] topic for which we want to build the consumer
+        # @return [Object] karafka consumer
+        def _karafka_build_consumer_for(topic)
+          coordinators = Karafka::Processing::CoordinatorsBuffer.new(
+            Karafka::Routing::Topics.new([topic])
+          )
+          @consumer = topic.consumer.new
+          @consumer.producer = Karafka::App.producer
+          # Inject appropriate strategy so needed options and components are available
+          strategy = Karafka::App.config.internal.processing.strategy_selector.find(topic)
+          @consumer.singleton_class.include(strategy)
+          @consumer.client = @karafka_consumer_client
+          @consumer.coordinator = coordinators.find_or_create(topic.name, 0)
+          @consumer.coordinator.seek_offset = 0
+          # Indicate usage as for tests no direct enqueuing happens
+          @consumer.instance_variable_set('@used', true)
+          @consumer
+        end
+
+        # Finds all the routing topics matching requested topic within all topics or within
+        # provided consumer group based on name
+        #
+        # @param requested_topic [String] requested topic name
+        # @param requested_consumer_group [String] requested consumer group or nil to look in all
+        # @return [Array<Karafka::Routing::Topic>] all matching topics
+        #
+        # @note Since we run the lookup on subscription groups, the search will automatically
+        #   expand with matching patterns
+        def _karafka_consumer_find_candidate_topics(requested_topic, requested_consumer_group)
+          _karafka_consumer_find_subscription_groups(requested_consumer_group)
+            .map(&:topics)
+            .filter_map do |topics|
+              topics.find(requested_topic.to_s)
+            rescue Karafka::Errors::TopicNotFoundError
+              nil
+            end
+        end
+
+        # Finds subscription groups from the requested consumer group or selects all if no
+        # consumer group specified
+        # @param requested_consumer_group [String] requested consumer group or nil to look in all
+        # @return [Array<Karafka::Routing::SubscriptionGroup>] requested subscription groups
+        def _karafka_consumer_find_subscription_groups(requested_consumer_group)
+          if requested_consumer_group && !requested_consumer_group.empty?
+            ::Karafka::App
+              .subscription_groups
+              # Find matching consumer group
+              .find { |cg, _sgs| cg.name == requested_consumer_group.to_s }
+              # Raise error if not found
+              .tap { |cg| cg || raise(Errors::ConsumerGroupNotFound, requested_consumer_group) }
+              # Since lookup was on a hash, get the value, that is subscription groups
+              .last
+          else
+            ::Karafka::App
+              .subscription_groups
+              .values
+              .flatten
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/testing/minitest/proxy.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Testing
+    module Minitest
+      # Proxy object for a nicer `karafka.` API within Minitest
+      # None other should be used by the end users
+      class Proxy
+        # @param minitest_example [Minitest::Test] minitest context
+        def initialize(minitest_example)
+          @minitest_example = minitest_example
+        end
+
+        # @param args Anything that the `#_karafka_consumer_for` accepts
+        def consumer_for(*args)
+          @minitest_example._karafka_consumer_for(*args)
+        end
+
+        # @param args Anything that `#_karafka_produce` accepts
+        def produce(*args)
+          @minitest_example._karafka_produce(*args)
+        end
+
+        # @return [Array<Hash>] messages produced via `Karafka#producer`
+        def produced_messages
+          @minitest_example._karafka_produced_messages
+        end
+      end
+    end
+  end
+end

data/lib/karafka/testing/rspec/helpers.rb

@@ -57,17 +57,10 @@ module Karafka
         #     subject(:consumer) { karafka.consumer_for(:my_requested_topic) }
         #   end
         def _karafka_consumer_for(requested_topic, requested_consumer_group = nil)
-          all_topics = ::Karafka::App.consumer_groups.map(&:topics).flat_map(&:to_a)
-
-          # First select topics that match what we are looking for
-          selected_topics = all_topics.select do |topic|
-            topic.name == requested_topic.to_s
-          end
-
-          # And then narrow it down based on the consumer group criteria (if present)
-          selected_topics.delete_if do |topic|
-            requested_consumer_group && topic.consumer_group.name != requested_consumer_group.to_s
-          end
+          selected_topics = _karafka_consumer_find_candidate_topics(
+            requested_topic.to_s,
+            requested_consumer_group.to_s
+          )
 
           raise Errors::TopicInManyConsumerGroupsError, requested_topic if selected_topics.size > 1
           raise Errors::TopicNotFoundError, requested_topic if selected_topics.empty?
@@ -183,6 +176,47 @@ module Karafka
           consumer.instance_variable_set('@used', true)
           consumer
         end
+
+        # Finds all the routing topics matching requested topic within all topics or within
+        # provided consumer group based on name
+        #
+        # @param requested_topic [String] requested topic name
+        # @param requested_consumer_group [String] requested consumer group or nil to look in all
+        # @return [Array<Karafka::Routing::Topic>] all matching topics
+        #
+        # @note Since we run the lookup on subscription groups, the search will automatically
+        #   expand with matching patterns
+        def _karafka_consumer_find_candidate_topics(requested_topic, requested_consumer_group)
+          _karafka_consumer_find_subscription_groups(requested_consumer_group)
+            .map(&:topics)
+            .filter_map do |topics|
+              topics.find(requested_topic.to_s)
+            rescue Karafka::Errors::TopicNotFoundError
+              nil
+            end
+        end
+
+        # Finds subscription groups from the requested consumer group or selects all if no
+        # consumer group specified
+        # @param requested_consumer_group [String] requested consumer group or nil to look in all
+        # @return [Array<Karafka::Routing::SubscriptionGroup>] requested subscription groups
+        def _karafka_consumer_find_subscription_groups(requested_consumer_group)
+          if requested_consumer_group && !requested_consumer_group.empty?
+            ::Karafka::App
+              .subscription_groups
+              # Find matching consumer group
+              .find { |cg, _sgs| cg.name == requested_consumer_group.to_s }
+              # Raise error if not found
+              .tap { |cg| cg || raise(Errors::ConsumerGroupNotFound, requested_consumer_group) }
+              # Since lookup was on a hash, get the value, that is subscription groups
+              .last
+          else
+            ::Karafka::App
+              .subscription_groups
+              .values
+              .flatten
+          end
+        end
       end
     end
   end

data/lib/karafka/testing/version.rb

@@ -4,6 +4,6 @@
 module Karafka
   module Testing
     # Current version of gem. It should match Karafka framework version
-    VERSION = '2.2.0'
+    VERSION = '2.2.2'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: karafka-testing
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.2.2
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -35,7 +35,7 @@ cert_chain:
   AnG1dJU+yL2BK7vaVytLTstJME5mepSZ46qqIJXMuWob/YPDmVaBF39TDSG9e34s
   msG3BiCqgOgHAnL23+CN3Rt8MsuRfEtoTKpJVcCfoEoNHOkc
   -----END CERTIFICATE-----
-date: 2023-09-01 00:00:00.000000000 Z
+date: 2023-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: karafka
@@ -97,6 +97,8 @@ files:
 - lib/karafka-testing.rb
 - lib/karafka/testing.rb
 - lib/karafka/testing/errors.rb
+- lib/karafka/testing/minitest/helpers.rb
+- lib/karafka/testing/minitest/proxy.rb
 - lib/karafka/testing/rspec/helpers.rb
 - lib/karafka/testing/rspec/proxy.rb
 - lib/karafka/testing/spec_consumer_client.rb
@@ -109,7 +111,7 @@ licenses:
 metadata:
   funding_uri: https://karafka.io/#become-pro
   homepage_uri: https://karafka.io
-  changelog_uri: https://github.com/karafka/karafka-testing/blob/master/CHANGELOG.md
+  changelog_uri: https://karafka.io/docs/Changelog-Karafka-Testing
   bug_tracker_uri: https://github.com/karafka/karafka-testing/issues
   source_code_uri: https://github.com/karafka/karafka-testing
   documentation_uri: https://karafka.io/docs