convenient_service 0.17.0 → 0.18.0

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            module SubMatchers
+              class Base
+                ##
+                # @!attribute [r] block_expectation_value
+                #   @return [Object] Can be any type.
+                #
+                attr_reader :block_expectation_value
+
+                ##
+                # @!attribute [r] matcher
+                #   @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
+                #
+                attr_reader :matcher
+
+                ##
+                # @overload initialize(matcher:)
+                #   @param matcher [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
+                #   @return [void]
+                #
+                # @overload initialize(matcher:, block_expectation_value:)
+                #   @param matcher [ConvenientService::RSpec::PrimitiveMatchers::Classes::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
+
+                private
+
+                ##
+                # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Inputs]
+                #
+                def inputs
+                  matcher.inputs
+                end
+
+                ##
+                # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Inputs]
+                #
+                def outputs
+                  matcher.outputs
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            module SubMatchers
+              class ReturnCustomValue < SubMatchers::Base
+                ##
+                # @param block_expectation_value [Object]
+                # @return [Boolean]
+                #
+                # @internal
+                #   TODO: Proper explanatory message when `matcher.inputs.custom_return_value` raises exception.
+                #
+                def matches?(block_expectation_value)
+                  super
+
+                  ##
+                  #   specify do
+                  #     expect { require_dependencies_not_pure }
+                  #       .to delegate_to(RequireDependenciesNotPure, :call)
+                  #       .and_return { |delegation_value| delegation_value.to_s }
+                  #   end
+                  #
+                  block_expectation_value == inputs.custom_return_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 `#{inputs.printable_block_expectation}` NOT to delegate to `#{inputs.printable_method}` and return custom value `#{inputs.custom_return_value.inspect}`, but it did."
+                end
+
+                private
+
+                ##
+                # @return [String]
+                #
+                def failure_message_permanent_part
+                  <<~MESSAGE.chomp
+                    expected `#{inputs.printable_block_expectation}` to delegate to `#{inputs.printable_method}` and return custom value `#{inputs.custom_return_value.inspect}`, but it didn't.
+
+                    `#{inputs.printable_block_expectation}` returns `#{block_expectation_value.inspect}`.
+
+                    Delegation returns `#{inputs.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.custom_return_value.inspect
+                #     return "" if block_expectation_value == matcher.custom_return_value
+                #
+                #     # ...
+                #   end
+                #
+                def same_visual_output_note
+                  if block_expectation_value.inspect == inputs.custom_return_value.inspect && block_expectation_value != inputs.custom_return_value
+                    <<~MESSAGE.chomp
+                      NOTE: Block expectation value `#{block_expectation_value.inspect}` and custom return value `#{inputs.custom_return_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

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            module SubMatchers
+              class ReturnDelegationValue < SubMatchers::Base
+                ##
+                # @param block_expectation_value [Object]
+                # @return [Boolean]
+                #
+                # @internal
+                #   TODO: Proper explanatory message when `inputs.delegation_value` raises exception.
+                #
+                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 == inputs.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 `#{inputs.printable_block_expectation}` NOT to delegate to `#{inputs.printable_method}` and return its value, but it did."
+                end
+
+                private
+
+                ##
+                # @return [String]
+                #
+                def failure_message_permanent_part
+                  <<~MESSAGE.chomp
+                    expected `#{inputs.printable_block_expectation}` to delegate to `#{inputs.printable_method}` and return its value, but it didn't.
+
+                    `#{inputs.printable_block_expectation}` returns `#{block_expectation_value.inspect}`, but delegation returns `#{inputs.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 == inputs.delegation_value.inspect && block_expectation_value != inputs.delegation_value
+                    <<~MESSAGE.chomp
+                      NOTE: Block expectation value `#{block_expectation_value.inspect}` and delegation value `#{inputs.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

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            module SubMatchers
+              class WithAnyArguments < 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

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

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

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            module SubMatchers
+              class WithoutArguments < 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

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "sub_matchers/base"
+
+require_relative "sub_matchers/arguments"
+require_relative "sub_matchers/with_any_arguments"
+require_relative "sub_matchers/with_concrete_arguments"
+require_relative "sub_matchers/without_arguments"
+
+require_relative "sub_matchers/return_delegation_value"
+require_relative "sub_matchers/return_custom_value"

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

@@ -1,3 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "entities/matcher"
+require_relative "entities/delegation"
+require_relative "entities/inputs"
+require_relative "entities/outputs"
+require_relative "entities/sub_matcher_collection"
+require_relative "entities/sub_matchers"

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/exceptions.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Exceptions
+            class CallOriginalChainingIsAlreadySet < ::ConvenientService::Exception
+              def initialize_without_arguments
+                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
+
+                initialize(message)
+              end
+            end
+
+            class ArgumentsChainingIsAlreadySet < ::ConvenientService::Exception
+              def initialize_without_arguments
+                message = <<~TEXT
+                  Arguments chaining is already set.
+
+                  Did you use `with_arguments`, `with_any_arguments` or `without_arguments` multiple times? Or a combination of them?
+                TEXT
+
+                initialize(message)
+              end
+            end
+
+            class ReturnValueChainingIsAlreadySet < ::ConvenientService::Exception
+              def initialize_without_arguments
+                message = <<~TEXT
+                  Returns value chaining is already set.
+
+                  Did you use `and_return_its_value` or `and_return { |delegation_value| ... }` multiple times? Or a combination of them?
+                TEXT
+
+                initialize(message)
+              end
+            end
+
+            class ReturnCustomValueChainingInvalidArguments < ::ConvenientService::Exception
+              def initialize_without_arguments
+                message = <<~TEXT
+                  Returns custom value chaining has invalid arguments.
+
+                  Make sure you use one of the following forms:
+
+                  `and_return(custom_value)`
+                  `and_return { custom_value }`
+                  `and_return { |delegation_value| process_somehow(delegation_value) }`
+                TEXT
+
+                initialize(message)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end