convenient_service 0.17.0 → 0.18.0

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/entities/inputs.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            class Inputs
+              ##
+              # @api private
+              #
+              # @!attribute [r] values
+              #   @return [Hash{Symbol => Object}]
+              #
+              attr_reader :values
+
+              ##
+              # @api private
+              #
+              # @param object [Object]
+              # @param method [String, Symbol]
+              # @param block_expectation [Proc]
+              # @return [void]
+              #
+              def initialize(object:, method:, block_expectation:)
+                @values = {object: object, method: method, block_expectation: block_expectation}
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Proc, nil]
+              #
+              def block_expectation
+                values[:block_expectation]
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Object] Can be any type.
+              #
+              # @internal
+              #   IMPORTANT: Must be refreshed when `expected_arguments` are reset.
+              #
+              def custom_return_value
+                return values[:custom_return_value] if values.has_key?(:custom_return_value)
+
+                values[:custom_return_value] = expected_return_value_block.call(delegation_value)
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Object] Can be any type.
+              #
+              # @internal
+              #   IMPORTANT: Must be refreshed when `expected_arguments` are reset.
+              #
+              def delegation_value
+                return values[:delegation_value] if values.has_key?(:delegation_value)
+
+                values[:delegation_value] =
+                  object.__send__(
+                    method,
+                    *expected_arguments.args,
+                    **expected_arguments.kwargs,
+                    &expected_arguments.block
+                  )
+              end
+
+              ##
+              # @api private
+              #
+              # @return [ConvenientService::Support::Arguments]
+              #
+              def expected_arguments
+                values[:expected_arguments] ||= Support::Arguments.null_arguments
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Proc]
+              #
+              def expected_return_value_block
+                values[:expected_return_value_block] ||= proc { Support::UNDEFINED }
+              end
+
+              ##
+              # @api private
+              #
+              # @return [String, Symbol]
+              #
+              def method
+                values[:method]
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Object] Can be any type.
+              #
+              def object
+                values[:object]
+              end
+
+              ##
+              # @api private
+              #
+              # @return [String]
+              #
+              def printable_block_expectation
+                @printable_block_expectation ||= Utils::Proc.display(block_expectation)
+              end
+
+              ##
+              # @api private
+              #
+              # @return [String]
+              #
+              def printable_method
+                @printable_method ||= Commands::GeneratePrintableMethod.call(object: object, method: method)
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Boolean]
+              #
+              def has_call_original?
+                values.has_key?(:should_call_original)
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Boolean]
+              #
+              def should_call_original?
+                return values[:should_call_original] if values.has_key?(:should_call_original)
+
+                values[:should_call_original] = true
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Proc]
+              #
+              def block_expectation=(block)
+                values[:block_expectation] = block
+              end
+
+              ##
+              # @api private
+              #
+              # @param arguments [ConvenientService::Support::Arguments]
+              # @return [ConvenientService::Support::Arguments]
+              #
+              def expected_arguments=(arguments)
+                values.delete(:delegation_value)
+                values.delete(:custom_return_value)
+
+                values[:expected_arguments] = arguments
+              end
+
+              ##
+              # @api private
+              #
+              # @param flag [Boolean]
+              # @return [Boolean]
+              #
+              def should_call_original=(flag)
+                values[:should_call_original] = flag
+              end
+
+              ##
+              # @api private
+              #
+              # @param block [Proc]
+              # @return [Proc]
+              # @raise [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Exceptions::ReturnCustomValueChainingInvalidArguments]
+              #
+              def update_expected_return_value_block(*args, &block)
+                values.delete(:custom_return_value)
+
+                values[:expected_return_value_block] =
+                  if args.any? && block
+                    ::ConvenientService.raise Exceptions::ReturnCustomValueChainingInvalidArguments.new
+                  elsif args.any?
+                    proc { args.first }
+                  elsif block
+                    block
+                  else
+                    ::ConvenientService.raise Exceptions::ReturnCustomValueChainingInvalidArguments.new
+                  end
+              end
+
+              ##
+              # @api private
+              #
+              # @param other [Object] Can be any type.
+              # @return [Boolean, nil]
+              #
+              # @internal
+              #   TODO: Unify `==(other)` YARD tags.
+              #
+              def ==(other)
+                return unless other.instance_of?(self.class)
+
+                return false if values != other.values
+
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/entities/outputs.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            class Outputs
+              ##
+              # @api private
+              #
+              # @return [Array]
+              #
+              def delegations
+                @delegations ||= []
+              end
+
+              ##
+              # @api private
+              #
+              # @param other [Object] Can be any type.
+              # @return [Boolean, nil]
+              #
+              def ==(other)
+                return unless other.instance_of?(self.class)
+
+                return false if delegations != other.delegations
+
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/entities/sub_matcher_collection.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            class SubMatcherCollection
+              ##
+              # @api private
+              #
+              # @!attribute [r] block_expectation_value
+              #   @return [Object]
+              #
+              attr_reader :block_expectation_value
+
+              ##
+              # @api private
+              #
+              # @!attribute [r] matcher
+              #   @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::SubMatchers]
+              #
+              attr_reader :matcher
+
+              ##
+              # @api private
+              #
+              # @!attribute [r] sub_matchers
+              #   @return [Hash]
+              #
+              attr_reader :sub_matchers
+
+              ##
+              # @api private
+              #
+              # @param matcher [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
+              # @return [void]
+              #
+              def initialize(matcher:)
+                @matcher = matcher
+                @sub_matchers = {}
+              end
+
+              ##
+              # @api private
+              #
+              # @param block_expectation [Proc]
+              # @return [Boolean]
+              #
+              def matches?(block_expectation)
+                sub_matchers_ordered_by_index.each(&:apply_stubs!)
+
+                @block_expectation_value = block_expectation.call
+
+                sub_matchers_ordered_by_index.all? { |sub_matcher| sub_matcher.matches?(@block_expectation_value) }
+              end
+
+              ##
+              # @api private
+              #
+              # @return [String]
+              #
+              def failure_message
+                sub_matchers_ordered_by_index
+                  .lazy
+                  .reject { |sub_matcher| sub_matcher.matches?(block_expectation_value) }
+                  .first
+                  &.failure_message
+                  .to_s
+              end
+
+              ##
+              # @api private
+              #
+              # @return [String]
+              #
+              def failure_message_when_negated
+                sub_matchers_ordered_by_index
+                  .reject { |sub_matcher| sub_matcher.does_not_match?(block_expectation_value) }
+                  .last
+                  &.failure_message_when_negated
+                  .to_s
+              end
+
+              ##
+              # @api private
+              #
+              # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::SubMatchers::Arguments]
+              #
+              def arguments
+                sub_matchers[:arguments] ||= Entities::SubMatchers::WithAnyArguments.new(matcher: matcher)
+              end
+
+              ##
+              # @api private
+              #
+              # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::SubMatchers::ReturnValue, nil]
+              #
+              def return_value
+                sub_matchers[:return_value]
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Array]
+              #
+              # @internal
+              #   IMPORTANT: Order of sub matcher chainings matters.
+              #
+              def sub_matchers_ordered_by_index
+                [arguments, return_value].compact
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Boolean]
+              #
+              def has_arguments?
+                sub_matchers.has_key?(:arguments)
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Boolean]
+              #
+              def has_return_value?
+                sub_matchers.has_key?(:return_value)
+              end
+
+              ##
+              # @api private
+              #
+              # @param sub_matcher [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::SubMatchers::Arguments]
+              #
+              def arguments=(sub_matcher)
+                sub_matchers[:arguments] = sub_matcher
+              end
+
+              ##
+              # @api private
+              #
+              # @param sub_matcher [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::SubMatchers::ReturnValue]
+              #
+              def return_value=(sub_matcher)
+                sub_matchers[:return_value] = sub_matcher
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/entities/sub_matchers/arguments/commands/apply_stub_to_track_delegations.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            module SubMatchers
+              class Arguments < SubMatchers::Base
+                module Commands
+                  class ApplyStubToTrackDelegations < Support::Command
+                    ##
+                    # @internal
+                    #   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
+                    #
+                    include ::RSpec::Mocks::ExampleMethods
+
+                    ##
+                    # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
+                    #
+                    attr_reader :matcher
+
+                    ##
+                    # @param matcher [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
+                    # @return [void]
+                    #
+                    def initialize(matcher:)
+                      @matcher = matcher
+                    end
+
+                    def call
+                      ##
+                      # 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
+                      #
+                      # TODO: Check whether `matcher.object.frozen?` in order to show more explanatory exception instead of the following (provide an example of how to avoid it in the exception message):
+                      #   ArgumentError:
+                      #     Cannot proxy frozen objects, rspec-mocks relies on proxies for method stubbing and expectations
+                      #
+                      allow(matcher.inputs.object).to receive(matcher.inputs.method).and_wrap_original do |original, *actual_args, **actual_kwargs, &actual_block|
+                        ##
+                        # TODO: Add backtrace for easier reason tracing.
+                        #
+                        matcher.outputs.delegations << Entities::Delegation.new(
+                          object: matcher.inputs.object,
+                          method: matcher.inputs.method,
+                          args: actual_args,
+                          kwargs: actual_kwargs,
+                          block: actual_block
+                        )
+
+                        ##
+                        # NOTE: Imitates `and_call_original`.
+                        # TODO: What to do when `original.call` raises an exception?
+                        #
+                        original.call(*actual_args, **actual_kwargs, &actual_block) if matcher.inputs.should_call_original?
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/entities/sub_matchers/arguments/commands/generate_printable_arguments.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            module SubMatchers
+              class Arguments < SubMatchers::Base
+                module Commands
+                  class GeneratePrintableArguments < Support::Command
+                    include Support::Delegate
+
+                    ##
+                    # @!attribute [r] arguments
+                    #   @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Arguments]
+                    #
+                    attr_reader :arguments
+
+                    ##
+                    # @return [Array]
+                    #
+                    delegate :args, to: :arguments
+
+                    ##
+                    # @return [Hash]
+                    #
+                    delegate :kwargs, to: :arguments
+
+                    ##
+                    # @return [Proc]
+                    #
+                    delegate :block, to: :arguments
+
+                    ##
+                    # @param arguments [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Arguments]
+                    #
+                    def initialize(arguments:)
+                      @arguments = arguments
+                    end
+
+                    ##
+                    # @return [String]
+                    #
+                    def call
+                      return "" if arguments.null_arguments?
+
+                      text =
+                        if args.any? && kwargs.any?
+                          "(#{printable_args}, #{printable_kwargs})"
+                        elsif args.any?
+                          "(#{printable_args})"
+                        elsif kwargs.any?
+                          "(#{printable_kwargs})"
+                        else
+                          "()"
+                        end
+
+                      text += " #{printable_block}" if block
+
+                      text
+                    end
+
+                    ##
+                    # @return [String]
+                    #
+                    def printable_args
+                      args.map(&:inspect).join(", ")
+                    end
+
+                    ##
+                    # @return [String]
+                    #
+                    def printable_kwargs
+                      kwargs.map { |key, value| "#{key}: #{value.inspect}" }.join(", ")
+                    end
+
+                    ##
+                    # @return [String]
+                    #
+                    def printable_block
+                      block ? Utils::Proc.display(block) : ""
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/entities/sub_matchers/arguments.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "arguments/commands"
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            module SubMatchers
+              class Arguments < SubMatchers::Base
+                ##
+                # @return [void]
+                #
+                def apply_stubs!
+                  Commands::ApplyStubToTrackDelegations.call(matcher: matcher)
+                end
+
+                ##
+                # @param block_expectation_value [Object]
+                # @return [Boolean]
+                #
+                def matches?(block_expectation_value)
+                  super
+
+                  outputs.delegations.any? { |delegation| matches_arguments?(delegation.arguments) }
+                end
+
+                ##
+                # @return [String]
+                #
+                # @internal
+                #   TODO: Prettier message.
+                #
+                def failure_message
+                  <<~MESSAGE.chomp
+                    #{failure_message_expected_part}
+
+                    #{failure_message_got_part}
+                  MESSAGE
+                end
+
+                ##
+                # @return [String]
+                #
+                def failure_message_when_negated
+                  "expected `#{inputs.printable_block_expectation}` NOT to delegate to `#{inputs.printable_method}` #{printable_expected_arguments} at least once, but it did."
+                end
+
+                ##
+                # @return [String]
+                #
+                def printable_actual_arguments
+                  return "" if outputs.delegations.none?
+
+                  outputs.delegations
+                    .map { |delegation| Commands::GeneratePrintableArguments.call(arguments: delegation.arguments) }
+                    .join(", ")
+                    .prepend("with ")
+                end
+
+                private
+
+                def failure_message_expected_part
+                  "expected `#{inputs.printable_block_expectation}` to delegate to `#{inputs.printable_method}` #{printable_expected_arguments} at least once, but it didn't."
+                end
+
+                ##
+                # @return [String]
+                #
+                # @internal
+                #   TODO: String diff.
+                #
+                def failure_message_got_part
+                  if outputs.delegations.any?
+                    "got delegated #{printable_actual_arguments}"
+                  else
+                    "got not delegated at all"
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end