convenient_service 0.5.0 → 0.7.0

data/lib/convenient_service/rspec/matchers/custom/delegate_to.rb

@@ -1,291 +1,124 @@
 # frozen_string_literal: true
 
+require_relative "delegate_to/entities"
+
 ##
-# IMPORTANT: This matcher has a dedicated end-user doc. Do NOT forget to update it when needed.
-# https://github.com/marian13/convenient_service_docs/blob/main/docs/api/tests/rspec/matchers/delegate_to.mdx
-#
-# TODO: Refactor into composition:
-#   - Ability to compose when `delegate_to` is used `without_arguments`.
-#   - Ability to compose when `delegate_to` is used `with_arguments`.
-#   - Ability to compose when `delegate_to` is used `and_return_its_value`.
-#
-# TODO: Refactor to NOT use `expect` inside this matcher.
-# This way the matcher will return true or false, but never raise exceptions (descendant of Exception, not StandardError).
-# Then it will be easier to developer a fully comprehensive spec suite for `delegate_to`.
+# @internal
+#   IMPORTANT: This matcher has a dedicated end-user doc. Do NOT forget to update it when needed.
+#   https://github.com/marian13/convenient_service_docs/blob/main/docs/api/tests/rspec/matchers/delegate_to.mdx
 #
 module ConvenientService
   module RSpec
     module Matchers
       module Custom
         ##
-        #   specify {
-        #     expect { method_class.cast(other, **options) }
-        #       .to delegate_to(ConvenientService::Service::Plugins::HasResultSteps::Entities::Method::Commands::CastMethod, :call)
-        #       .with_arguments(other: other, options: options)
-        #       .and_return_its_value
-        #   }
-        #
-        #   { method_class.cast(other, **options) }
-        #   # => block_expectation
-        #
-        #   ConvenientService::Service::Plugins::HasResultSteps::Entities::Method::Commands::CastMethod
-        #   # => object
-        #
-        #   :call
-        #   #=> method
-        #
-        #   (other: other, options: options)
-        #   # => chain[:with]
-        #
-        #   and_return_its_value
-        #   # => chain[:and_return_its_value]
-        #
-        # NOTE: A similar (with different behaviour) matcher exists in `saharspec`.
-        # https://github.com/zverok/saharspec#send_messageobject-method-matcher
+        # @internal
+        #   NOTE: This is a Facade class.
+        #   https://refactoring.guru/design-patterns/facade
         #
         class DelegateTo
+          include Support::Delegate
+
           ##
-          # NOTE: `include ::RSpec::Expectations`.
-          # - https://github.com/rspec/rspec-expectations/blob/v3.11.0/lib/rspec/expectations.rb
-          # - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/expectations.rb#L60
+          # @return [Boolean]
           #
-          include ::RSpec::Expectations
+          delegate :matches?, to: :matcher
 
           ##
-          # NOTE: `include ::RSpec::Matchers`.
-          # - https://github.com/rspec/rspec-expectations/blob/v3.11.0/lib/rspec/matchers.rb
-          # - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/matchers.rb
+          # @internal
+          #   NOTE: Required by RSpec.
+          #   https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/custom-matchers/define-a-matcher-supporting-block-expectations
           #
-          include ::RSpec::Matchers
+          delegate :supports_block_expectations?, to: :matcher
 
           ##
-          # NOTE: `include ::RSpec::Mocks::ExampleMethods`.
-          # - https://github.com/rspec/rspec-mocks/blob/v3.11.1/lib/rspec/mocks/example_methods.rb
-          # - https://github.com/rspec/rspec-mocks/blob/main/lib/rspec/mocks/example_methods.rb
+          # @return [String]
           #
-          include ::RSpec::Mocks::ExampleMethods
+          delegate :description, to: :matcher
 
           ##
+          # @return [String]
           #
-          #
-          def initialize(object, method)
-            @object = object
-            @method = method
-          end
+          delegate :failure_message, to: :matcher
 
           ##
+          # @return [String]
           #
-          #
-          def matches?(block_expectation)
-            @block_expectation = block_expectation
-
-            ##
-            # TODO: Support multiple `with_arguments` calls.
-            #
-            if used_with_arguments?
-              ##
-              # NOTE: RSpec `allow(object).to receive(method).with(*args, **kwargs)` does NOT support block.
-              # https://github.com/rspec/rspec-mocks/issues/1182#issuecomment-679820352
-              #
-              # NOTE: RSpec `allow(object).to receive(method) do` does NOT support `and_call_original`.
-              # https://github.com/rspec/rspec-mocks/issues/774#issuecomment-54245277
-              #
-              # NOTE: That is why `and_wrap_original` is used.
-              # https://relishapp.com/rspec/rspec-mocks/docs/configuring-responses/wrapping-the-original-implementation
-              #
-              allow(object).to receive(method).and_wrap_original do |original, *actual_args, **actual_kwargs, &actual_block|
-                actual_arguments_collection << [actual_args, actual_kwargs, actual_block]
-
-                ##
-                # NOTE: Imitates `and_call_original`.
-                #
-                original.call(*actual_args, **actual_kwargs, &actual_block)
-              end
-            else
-              allow(object).to receive(method).and_call_original
-            end
-
-            ##
-            # NOTE: Calls `block_expectation` before checking expections.
-            #
-            value = block_expectation.call
-
-            ##
-            # NOTE: If this expectation fails, it means `delegate_to` is NOT met.
-            #
-            expect(object).to have_received(method).at_least(1) unless used_with_arguments?
-
-            ##
-            # IMPORTANT: `and_return_its_value` works only when `delegate_to` checks a pure function.
-            #
-            # For example (1):
-            #   def require_dependencies_pure
-            #     RequireDependenciesPure.call
-            #   end
-            #
-            #   class RequireDependenciesPure
-            #     def self.call
-            #       dependencies.require!
-            #
-            #       true
-            #     end
-            #   end
-            #
-            #   # Works since `RequireDependenciesPure.call` always returns `true`.
-            #   specify do
-            #     expect { require_dependencies_pure }
-            #       .to delegate_to(RequireDependenciesPure, :call)
-            #       .and_return_its_value
-            #   end
-            #
-            # Example (2):
-            #   def require_dependencies_not_pure
-            #     RequireDependenciesNotPure.call
-            #   end
-            #
-            #   class RequireDependenciesNotPure
-            #     def self.call
-            #       return false if dependencies.required?
-            #
-            #       dependencies.require!
-            #
-            #       true
-            #     end
-            #   end
-            #
-            #   # Does NOT work since `RequireDependenciesNotPure.call` returns `true` for the first time and `false` for the subsequent call.
-            #   specify do
-            #     expect { require_dependencies_not_pure }
-            #       .to delegate_to(RequireDependenciesNotPure, :call)
-            #       .and_return_its_value
-            #   end
-            #
-            # NOTE: If this expectation fails, it means `and_return_its_value` is NOT met.
-            #
-            expect(value).to eq(object.__send__(method, *args, **kwargs, &block)) if used_and_return_its_value?
-
-            ##
-            # IMPORTANT: A matcher should always return a boolean.
-            # https://github.com/zverok/saharspec/blob/master/lib/saharspec/matchers/send_message.rb#L59
-            #
-            # NOTE: RSpec raises exception when any `expect` is NOT satisfied.
-            # So, this `true` is returned only when all `expect` are successful.
-            #
-            if used_with_arguments?
-              actual_arguments_collection.any? do |(actual_args, actual_kwargs, actual_block)|
-                actual_args == expected_args && actual_kwargs == expected_kwargs && actual_block == expected_block
-              end
-            else
-              true
-            end
-          end
+          delegate :failure_message_when_negated, to: :matcher
 
           ##
-          # NOTE: Required by RSpec.
-          # https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/custom-matchers/define-a-matcher-supporting-block-expectations
+          # @overload initialize(object, method)
+          #   @param object [Object]
+          #   @param method [String, Symbol]
+          #   @return [void]
+          #
+          # @overload initialize(matcher)
+          #   @param matcher [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher]
+          #   @return [void]
+          #   @api private
           #
-          def supports_block_expectations?
-            true
+          # @internal
+          #   TODO: `overload do`?
+          #
+          def initialize(object = nil, method = nil, matcher: nil)
+            @matcher = matcher || Entities::Matcher.new(object, method)
           end
 
           ##
+          # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+          # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ArgumentsChainingIsAlreadySet]
           #
-          #
-          def description
-            "delegate to `#{printable_method}`"
-          end
+          def with_arguments(...)
+            matcher.with_arguments(...)
 
-          def failure_message
-            if used_with_arguments?
-              "expected `#{printable_block_expectation}` to delegate to `#{printable_method}` with expected arguments at least once, but it didn't."
-            else
-              "expected `#{printable_block_expectation}` to delegate to `#{printable_method}` at least once, but it didn't."
-            end
+            self
           end
 
           ##
-          # IMPORTANT: `failure_message_when_negated` is NOT supported yet.
+          # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+          # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ArgumentsChainingIsAlreadySet]
           #
-
-          def with_arguments(*args, **kwargs, &block)
-            chain[:with_arguments] = {args: args, kwargs: kwargs, block: block}
+          def without_arguments
+            matcher.without_arguments
 
             self
           end
 
+          ##
+          # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+          # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ReturnItsValueChainingIsAlreadySet]
+          #
           def and_return_its_value
-            chain[:and_return_its_value] = true
+            matcher.and_return_its_value
 
             self
           end
 
-          def printable_method
-            @printable_method ||=
-              case Utils::Object.resolve_type(object)
-              when "class", "module"
-                "#{object}.#{method}"
-              when "instance"
-                "#{object.class}##{method}"
-              end
-          end
-
-          private
-
-          attr_reader :object, :method, :block_expectation
-
-          def used_with_arguments?
-            chain.key?(:with_arguments)
-          end
-
-          def used_and_return_its_value?
-            chain.key?(:and_return_its_value)
-          end
-
-          def chain
-            @chain ||= {}
-          end
-
-          def args
-            @args ||= chain.dig(:with_arguments, :args) || []
-          end
-
-          alias_method :expected_args, :args
-
-          def kwargs
-            @kwargs ||= chain.dig(:with_arguments, :kwargs) || {}
-          end
-
-          alias_method :expected_kwargs, :kwargs
+          ##
+          # TODO: `and_return`.
+          #
+          # def and_return(...)
+          #   matcher.and_return(...)
+          #
+          #   self
+          # end
 
           ##
-          # NOTE: `if defined?` is used in order to cache `nil` if needed.
+          # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
           #
-          def block
-            return @block if defined? @block
+          def without_calling_original
+            matcher.without_calling_original
 
-            @block = chain.dig(:with_arguments, :block)
+            self
           end
 
-          alias_method :expected_block, :block
-
-          def actual_arguments_collection
-            @actual_arguments_collection ||= []
-          end
+          private
 
           ##
-          # NOTE: An example of how RSpec extracts block source, but they marked it as private.
-          # https://github.com/rspec/rspec-expectations/blob/311aaf245f2c5493572bf683b8c441cb5f7e44c8/lib/rspec/matchers/built_in/change.rb#L437
-          #
-          # TODO: `printable_block_expectation` when `method_source` is available.
-          # https://github.com/banister/method_source
+          # @!attribute [r] matcher
+          #   @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher]
           #
-          # def printable_block_expectation
-          #   @printable_block_expectation ||= block_expectation.source
-          # end
-          #
-          def printable_block_expectation
-            @printable_block_expectation ||= "{ ... }"
-          end
+          attr_reader :matcher
         end
       end
     end

data/lib/convenient_service/rspec/matchers/custom/results/base/commands/find_result_method_step.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        module Results
+          class Base
+            module Commands
+              class FindResultMethodStep < Support::Command
+                ##
+                # @!attribute result [r]
+                #   @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                #
+                attr_reader :result
+
+                ##
+                # @!attribute method_name [r]
+                #   @return [Symbol]
+                #
+                attr_reader :method_name
+
+                ##
+                # @param result [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                # @param method_name [Symbol]
+                # @return [void]
+                #
+                def initialize(result:, method_name:)
+                  @result = result
+                  @method_name = method_name
+                end
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                #
+                def call
+                  return nil unless result.step
+
+                  result.step.inputs.find { |input| match_service_class?(input) && match_key?(input) && match_value?(input) }
+                end
+
+                private
+
+                ##
+                # @param input [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                # @return [Boolean]
+                #
+                def match_service_class?(input)
+                  result.step.service_class == Services::RunMethodInOrganizer
+                end
+
+                ##
+                # @param input [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                # @return [Boolean]
+                #
+                def match_key?(input)
+                  input.key.to_sym == :method_name
+                end
+
+                ##
+                # @param input [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                # @return [Boolean]
+                #
+                def match_value?(input)
+                  input.value.to_sym == method_name
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/results/base/commands/find_result_result_method_step.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        module Results
+          class Base
+            module Commands
+              class FindResultResultMethodStep < Support::Command
+                ##
+                # @!attribute result [r]
+                #   @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                #
+                attr_reader :result
+
+                ##
+                # @param result [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                # @return [void]
+                #
+                def initialize(result:)
+                  @result = result
+                end
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                #
+                def call
+                  return nil unless result.step
+
+                  result.step.inputs.find { |input| match_service_class?(input) && match_key?(input) && match_value?(input) }
+                end
+
+                private
+
+                ##
+                # @param input [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                # @return [Boolean]
+                #
+                def match_service_class?(input)
+                  result.step.service_class == Services::RunOwnMethodInOrganizer
+                end
+
+                ##
+                # @param input [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                # @return [Boolean]
+                #
+                def match_key?(input)
+                  input.key.to_sym == :method_name
+                end
+
+                ##
+                # @param input [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                # @return [Boolean]
+                #
+                def match_value?(input)
+                  input.value.to_sym == :result
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/results/base/commands/find_result_service_step.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        module Results
+          class Base
+            module Commands
+              class FindResultServiceStep < Support::Command
+                ##
+                # @!attribute result [r]
+                #   @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                #
+                attr_reader :result
+
+                ##
+                # @!attribute service_class [r]
+                #   @return [Class]
+                #
+                attr_reader :service_class
+
+                ##
+                # @param result [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                # @param service_class [Class]
+                # @return [void]
+                #
+                def initialize(result:, service_class:)
+                  @result = result
+                  @service_class = service_class
+                end
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method]
+                #
+                def call
+                  return nil unless result.step
+
+                  result.step.service_class == service_class
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/results/base/commands/generate_expected_step_part.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        module Results
+          class Base
+            module Commands
+              class GenerateExpectedStepPart < Support::Command
+                ##
+                # @!attribute step [r]
+                #   @return [Class, Symbol]
+                #
+                attr_reader :step
+
+                ##
+                # @param step [Class, Symbol]
+                # @return [void]
+                #
+                def initialize(step:)
+                  @step = step
+                end
+
+                ##
+                # @return [String]
+                #
+                def call
+                  if step.nil?
+                    "without step"
+                  else
+                    "of step `#{step}`"
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/results/base/commands/generate_got_step_part.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        module Results
+          class Base
+            module Commands
+              class GenerateGotStepPart < Support::Command
+                ##
+                # @!attribute result [r]
+                #   @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                #
+                attr_reader :result
+
+                ##
+                # @param result [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                # @return [void]
+                #
+                def initialize(result:)
+                  @result = result
+                end
+
+                ##
+                # @return [String]
+                #
+                def call
+                  if result.step.nil?
+                    "without step"
+                  else
+                    "of step `#{result.step.service.klass}`"
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end