convenient_service 0.5.0 → 0.6.0

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/sub_matchers/base.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                module Chainings
+                  module SubMatchers
+                    class Base
+                      ##
+                      # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+                      #
+                      attr_reader :matcher
+
+                      ##
+                      # @return [Object] Can be any type.
+                      #
+                      attr_reader :block_expectation_value
+
+                      ##
+                      # @overload initialize(matcher:)
+                      #   @param matcher [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+                      #   @return [void]
+                      #
+                      # @overload initialize(matcher:, block_expectation_value:)
+                      #   @param matcher [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+                      #   @param block_expectation_value [Object] Can be any type.
+                      #   @return [void]
+                      #   @api private
+                      #
+                      def initialize(matcher:, block_expectation_value: nil)
+                        @matcher = matcher
+                        @block_expectation_value = block_expectation_value
+                      end
+
+                      ##
+                      # @return [void]
+                      #
+                      def apply_stubs!
+                      end
+
+                      ##
+                      # @param block_expectation_value [Object] Can be any type.
+                      # @return [Boolean]
+                      #
+                      def matches?(block_expectation_value)
+                        @block_expectation_value = block_expectation_value
+
+                        false
+                      end
+
+                      ##
+                      # @param block_expectation_value [Object] Can be any type.
+                      # @return [Boolean]
+                      #
+                      def does_not_match?(block_expectation_value)
+                        !matches?(block_expectation_value)
+                      end
+
+                      ##
+                      # @return [String]
+                      #
+                      def failure_message
+                        ""
+                      end
+
+                      ##
+                      # @return [String]
+                      #
+                      def failure_message_when_negated
+                        ""
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/sub_matchers/return_its_value.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                module Chainings
+                  module SubMatchers
+                    class ReturnItsValue < Chainings::SubMatchers::Base
+                      ##
+                      # @param block_expectation_value [Object]
+                      # @return [Boolean]
+                      #
+                      def matches?(block_expectation_value)
+                        super
+
+                        ##
+                        # TODO: `with_warmup`.
+                        #
+                        # 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
+                        #
+                        block_expectation_value == matcher.delegation_value
+                      end
+
+                      ##
+                      # @return [String]
+                      #
+                      def failure_message
+                        [failure_message_permanent_part, same_visual_output_note].reject(&:empty?).join("\n\n")
+                      end
+
+                      ##
+                      # @return [String]
+                      #
+                      def failure_message_when_negated
+                        "expected `#{matcher.printable_block_expectation}` NOT to delegate to `#{matcher.printable_method}` and return its value, but it did."
+                      end
+
+                      private
+
+                      def failure_message_permanent_part
+                        <<~MESSAGE.chomp
+                          expected `#{matcher.printable_block_expectation}` to delegate to `#{matcher.printable_method}` and return its value, but it didn't.
+
+                          `#{matcher.printable_block_expectation}` returns `#{block_expectation_value.inspect}`, but delegation returns `#{matcher.delegation_value.inspect}`.
+                        MESSAGE
+                      end
+
+                      ##
+                      # @internal
+                      #   NOTE: Early return is harder to understand in this particular case, that is why a casual if is used.
+                      #
+                      #   def note
+                      #     return "" if block_expectation_value.inspect != matcher.delegation_value.inspect
+                      #     return "" if block_expectation_value == matcher.delegation_value
+                      #
+                      #     # ...
+                      #   end
+                      #
+                      def same_visual_output_note
+                        if block_expectation_value.inspect == matcher.delegation_value.inspect && block_expectation_value != matcher.delegation_value
+                          <<~MESSAGE.chomp
+                            NOTE: `#{block_expectation_value.inspect}` and `#{matcher.delegation_value.inspect}` have the same visual output, but they are different objects in terms of `#==`.
+
+                            If it is expected behavior, ignore this note.
+
+                            Otherwise, define a meaningful `#==` for `#{block_expectation_value.class}` or adjust its `#inspect` to generate different output.
+                          MESSAGE
+                        else
+                          ""
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/sub_matchers/with_any_arguments.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                module Chainings
+                  module SubMatchers
+                    class WithAnyArguments < Chainings::SubMatchers::Arguments
+                      ##
+                      # @return [Boolean]
+                      #
+                      def matches_arguments?(arguments)
+                        true
+                      end
+
+                      ##
+                      # @return [String]
+                      #
+                      def printable_expected_arguments
+                        "with any arguments (no arguments is also valid)"
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/sub_matchers/with_concrete_arguments.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                module Chainings
+                  module SubMatchers
+                    class WithConcreteArguments < Chainings::SubMatchers::Arguments
+                      ##
+                      # @return [Boolean]
+                      #
+                      def matches_arguments?(arguments)
+                        Utils::Bool.to_bool(arguments == matcher.expected_arguments)
+                      end
+
+                      ##
+                      # @return [String]
+                      #
+                      def printable_expected_arguments
+                        "with `#{Arguments::Commands::GeneratePrintableArguments.call(arguments: matcher.expected_arguments)}`"
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/sub_matchers/without_arguments.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                module Chainings
+                  module SubMatchers
+                    class WithoutArguments < Chainings::SubMatchers::Arguments
+                      ##
+                      # @return [Boolean]
+                      #
+                      def matches_arguments?(arguments)
+                        arguments.none?
+                      end
+
+                      ##
+                      # @return [String]
+                      #
+                      def printable_expected_arguments
+                        "without arguments"
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/values/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                module Chainings
+                  module Values
+                    class Base
+                      ##
+                      # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+                      #
+                      attr_reader :matcher
+
+                      ##
+                      # @return [Object] Can be any type.
+                      #
+                      attr_reader :value
+
+                      ##
+                      # @param matcher [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+                      # @return [void]
+                      #
+                      def initialize(matcher:)
+                        @matcher = matcher
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/values/with_calling_original.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                module Chainings
+                  module Values
+                    class WithCallingOriginal < Chainings::Values::Base
+                      ##
+                      # @return [Boolean]
+                      #
+                      def value
+                        true
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/values/without_calling_original.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                module Chainings
+                  module Values
+                    class WithoutCallingOriginal < Chainings::Values::Base
+                      ##
+                      # @return [Boolean]
+                      #
+                      def value
+                        false
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "chainings/sub_matchers/base"
+require_relative "chainings/sub_matchers/arguments"
+require_relative "chainings/sub_matchers/with_any_arguments"
+require_relative "chainings/sub_matchers/with_concrete_arguments"
+require_relative "chainings/sub_matchers/without_arguments"
+require_relative "chainings/sub_matchers/return_its_value"
+
+require_relative "chainings/values/base"
+require_relative "chainings/values/with_calling_original"
+require_relative "chainings/values/without_calling_original"

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings_collection/errors.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                class ChainingsCollection
+                  module Errors
+                    class CallOriginalChainingIsAlreadySet < ConvenientService::Error
+                      def initialize
+                        message = <<~TEXT
+                          Call original chaining is already set.
+
+                          Did you use `with_calling_original` or `without_calling_original` multiple times? Or a combination of them?
+                        TEXT
+
+                        super(message)
+                      end
+                    end
+
+                    class ArgumentsChainingIsAlreadySet < ConvenientService::Error
+                      def initialize
+                        message = <<~TEXT
+                          Arguments chaining is already set.
+
+                          Did you use `with_arguments` or `without_arguments` multiple times? Or a combination of them?
+                        TEXT
+
+                        super(message)
+                      end
+                    end
+
+                    class ReturnItsValueChainingIsAlreadySet < ConvenientService::Error
+                      def initialize
+                        message = <<~TEXT
+                          Returns its value chaining is already set.
+
+                          Did you use `and_returns_its_value` multiple times?
+                        TEXT
+
+                        super(message)
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings_collection.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "chainings_collection/errors"
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class DelegateTo
+          module Entities
+            class Matcher
+              module Entities
+                class ChainingsCollection
+                  include Support::Delegate
+
+                  ##
+                  # @!attribute [r] matcher
+                  #   @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher::Entities::Chainings]
+                  #
+                  attr_reader :matcher
+
+                  ##
+                  # @!attribute [r] block_expectation_value
+                  #   @return [Object]
+                  #
+                  attr_reader :block_expectation_value
+
+                  ##
+                  # @!attribute [r] call_original
+                  #   @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher::Entities::Chainings::Permissions:Base, nil]
+                  #
+                  attr_reader :call_original
+
+                  ##
+                  # @!attribute [r] arguments
+                  #   @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher::Entities::Chainings::SubMatchers::Base, nil]
+                  #
+                  attr_reader :arguments
+
+                  ##
+                  # @!attribute [r] return_its_value
+                  #   @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher::Entities::Chainings::SubMatchers::Base, nil]
+                  #
+                  attr_reader :return_its_value
+
+                  ##
+                  # @param matcher [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher]
+                  # @return [void]
+                  #
+                  def initialize(matcher:)
+                    @matcher = matcher
+                  end
+
+                  ##
+                  # @param block_expectation [Proc]
+                  # @return [Boolean]
+                  #
+                  def sub_matchers_match?(block_expectation)
+                    sub_matchers.each(&:apply_stubs!)
+
+                    @block_expectation_value = block_expectation.call
+
+                    sub_matchers.all? { |sub_matcher| sub_matcher.matches?(@block_expectation_value) }
+                  end
+
+                  ##
+                  # @return [String]
+                  #
+                  def failure_message
+                    sub_matchers
+                      .lazy
+                      .reject { |sub_matcher| sub_matcher.matches?(block_expectation_value) }
+                      .first
+                      &.failure_message
+                      .to_s
+                  end
+
+                  ##
+                  # @return [String]
+                  #
+                  def failure_message_when_negated
+                    sub_matchers
+                      .reject { |sub_matcher| sub_matcher.does_not_match?(block_expectation_value) }
+                      .last
+                      &.failure_message_when_negated
+                      .to_s
+                  end
+
+                  ##
+                  # @return [Array]
+                  #
+                  # @internal
+                  #   IMPORTANT: Order of sub matcher chainings matters.
+                  #
+                  def sub_matchers
+                    [arguments, return_its_value].compact
+                  end
+
+                  ##
+                  # @return [Array]
+                  #
+                  def values
+                    [call_original].compact
+                  end
+
+                  ##
+                  # @return [Boolean]
+                  #
+                  def should_call_original?
+                    Utils::Bool.to_bool(call_original&.value)
+                  end
+
+                  ##
+                  # @return [Boolean]
+                  #
+                  def has_call_original?
+                    Utils::Bool.to_bool(call_original)
+                  end
+
+                  ##
+                  # @return [Boolean]
+                  #
+                  def has_arguments?
+                    Utils::Bool.to_bool(arguments)
+                  end
+
+                  ##
+                  # @return [Boolean]
+                  #
+                  def has_return_its_value?
+                    Utils::Bool.to_bool(return_its_value)
+                  end
+
+                  ##
+                  # @param chaining [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher::Entities::Chainings::Values::Base]
+                  # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ReturnItsValueChainingIsAlreadySet]
+                  #
+                  def call_original=(chaining)
+                    raise Errors::CallOriginalChainingIsAlreadySet.new if @call_original
+
+                    @call_original = chaining
+                  end
+
+                  ##
+                  # @param chaining [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher::Entities::Chainings::SubMatchers::Base]
+                  # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ArgumentsChainingIsAlreadySet]
+                  #
+                  def arguments=(chaining)
+                    raise Errors::ArgumentsChainingIsAlreadySet.new if @arguments
+
+                    @arguments = chaining
+                  end
+
+                  ##
+                  # @param chaining [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher::Entities::Chainings::SubMatchers::Base]
+                  # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ReturnItsValueChainingIsAlreadySet]
+                  #
+                  def return_its_value=(chaining)
+                    raise Errors::ReturnItsValueChainingIsAlreadySet.new if @return_its_value
+
+                    @return_its_value = chaining
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end