convenient_service 0.6.0 → 0.8.0

data/lib/convenient_service/rspec/helpers/custom/wrap_method/entities/wrapped_method.rb

@@ -35,9 +35,25 @@ module ConvenientService
                   #
                   stack.use(
                     proc do |env|
-                      entity.__send__(method, *env[:args], **env[:kwargs], &env[:block])
-                        .tap { |value| @chain_value = value }
-                        .tap { @chain_arguments = {args: env[:args], kwargs: env[:kwargs], block: env[:block]} }
+                      @chain_arguments = {args: env[:args], kwargs: env[:kwargs], block: env[:block]}
+
+                      ##
+                      # IMPORTANT: Forces Ruby to define `@chain_value` instance variable.
+                      #
+                      # NOTE: If `@chain_value` is still set to `Support::UNDEFINED` after running the begin block - an exception was raised by `chain.next`. See `chain_called?` for more info.
+                      #
+                      @chain_value = Support::UNDEFINED
+
+                      begin
+                        @chain_value = entity.__send__(method, *env[:args], **env[:kwargs], &env[:block])
+                      rescue => exception
+                        @chain_exception = exception
+
+                        ##
+                        # NOTE: `raise` with no args inside `rescue` reraises rescued exception.
+                        #
+                        raise
+                      end
                     end
                   )
                 end
@@ -107,6 +123,16 @@ module ConvenientService
 
                 @chain_arguments[:block]
               end
+
+              ##
+              # @return [StandardError, nil]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              #
+              def chain_exception
+                raise Errors::ChainAttributePreliminaryAccess.new(attribute: :exception) unless chain_called?
+
+                @chain_exception
+              end
             end
           end
         end

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

@@ -30,7 +30,7 @@ module ConvenientService
           end
 
           ##
-          # NOTE: `failure_message` is only called when `mathces?` returns `false`.
+          # NOTE: `failure_message` is only called when `matches?` returns `false`.
           # https://rubydoc.info/github/rspec/rspec-expectations/RSpec/Matchers/MatcherProtocol#failure_message-instance_method
           #
           def failure_message
@@ -38,7 +38,7 @@ module ConvenientService
           end
 
           ##
-          # NOTE: `failure_message_when_negated` is only called when `mathces?` returns `false`.
+          # NOTE: `failure_message_when_negated` is only called when `matches?` returns `false`.
           # https://rubydoc.info/github/rspec/rspec-expectations/RSpec/Matchers/MatcherProtocol#failure_message-instance_method
           #
           def failure_message_when_negated

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

@@ -30,7 +30,7 @@ module ConvenientService
           end
 
           ##
-          # NOTE: `failure_message` is only called when `mathces?` returns `false`.
+          # NOTE: `failure_message` is only called when `matches?` returns `false`.
           # https://rubydoc.info/github/rspec/rspec-expectations/RSpec/Matchers/MatcherProtocol#failure_message-instance_method
           #
           def failure_message
@@ -38,7 +38,7 @@ module ConvenientService
           end
 
           ##
-          # NOTE: `failure_message_when_negated` is only called when `mathces?` returns `false`.
+          # NOTE: `failure_message_when_negated` is only called when `matches?` returns `false`.
           # https://rubydoc.info/github/rspec/rspec-expectations/RSpec/Matchers/MatcherProtocol#failure_message-instance_method
           #
           def failure_message_when_negated

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

@@ -94,6 +94,15 @@ module ConvenientService
             self
           end
 
+          ##
+          # TODO: `and_return`.
+          #
+          # def and_return(...)
+          #   matcher.and_return(...)
+          #
+          #   self
+          # end
+
           ##
           # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
           #

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

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        module Results
+          class Base
+            module Commands
+              class MatchResultStep < Support::Command
+                ##
+                # @!attribute result [r]
+                #   @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                #
+                attr_reader :result
+
+                ##
+                # @!attribute step [r]
+                #   @return [Class, Symbol]
+                #
+                attr_reader :step
+
+                ##
+                # @param result [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+                # @param step [Class, Symbol]
+                # @return [void]
+                #
+                def initialize(result:, step:)
+                  @result = result
+                  @step = step
+                end
+
+                ##
+                # @return [Boolean]
+                # @raise [ConvenientService::RSpec::Matchers::Custom::Results::Base::Errors::InvalidStep]
+                #
+                def call
+                  case step
+                  when ::Class then match_service_step?
+                  when :result then match_result_method_step?
+                  when ::Symbol then match_method_step?
+                  when nil then match_without_step?
+                  else raise Errors::InvalidStep.new(step: step)
+                  end
+                end
+
+                private
+
+                ##
+                # @return [Boolean]
+                #
+                def match_service_step?
+                  service_step = Commands::FindResultServiceStep.call(result: result, service_class: step)
+
+                  Utils::Bool.to_bool(service_step)
+                end
+
+                ##
+                # @return [Boolean]
+                #
+                def match_result_method_step?
+                  result_method_step = Commands::FindResultResultMethodStep.call(result: result)
+
+                  Utils::Bool.to_bool(result_method_step)
+                end
+
+                ##
+                # @return [Boolean]
+                #
+                def match_method_step?
+                  method_step = Commands::FindResultMethodStep.call(result: result, method_name: step)
+
+                  Utils::Bool.to_bool(method_step)
+                end
+
+                ##
+                # @return [Boolean]
+                #
+                def match_without_step?
+                  result.step.nil?
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "commands/find_result_method_step"
+require_relative "commands/find_result_result_method_step"
+require_relative "commands/find_result_service_step"
+
+require_relative "commands/generate_expected_step_part"
+require_relative "commands/generate_got_step_part"
+
+require_relative "commands/match_result_step"

data/lib/convenient_service/rspec/matchers/custom/results/base/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        module Results
+          class Base
+            module Errors
+              class InvalidStep < ConvenientService::Error
+                def initialize(step:)
+                  message = <<~TEXT
+                    Step `#{step}` is NOT valid.
+
+                    `of_step` only accepts a Class or a Symbol. For example:
+
+                    be_success.of_step(ReadFileContent)
+                    be_success.of_step(:validate_path)
+                    be_success.of_step(:result)
+
+                    If you need to confirm that `result` has NO step - use `without_step` instead.
+
+                    be_success.without_step
+                  TEXT
+
+                  super(message)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "base/commands"
+require_relative "base/errors"
+
 module ConvenientService
   module RSpec
     module Matchers
@@ -23,8 +26,14 @@ module ConvenientService
               rules = []
 
               rules << ->(result) { result.class.include?(Service::Plugins::HasResult::Entities::Result::Concern) }
+
+              ##
+              # IMPORTANT: Result status is NOT marked as checked intentionally, since it is a mutable operation.
+              #
               rules << ->(result) { result.status.in?(statuses) }
-              rules << ->(result) { result.service.instance_of?(service_class) } if used_of?
+
+              rules << ->(result) { result.service.instance_of?(service_class) } if used_of_service?
+              rules << ->(result) { Commands::MatchResultStep.call(result: result, step: step) } if used_of_step?
               rules << ->(result) { result.unsafe_data == data } if used_data?
               rules << ->(result) { result.unsafe_message == message } if used_message?
               rules << ->(result) { result.unsafe_code == code } if used_code?
@@ -38,14 +47,14 @@ module ConvenientService
             # @return [String]
             #
             def description
-              default_text
+              expected_parts
             end
 
             ##
             # @return [String]
             #
             def failure_message
-              "expected that `#{result}` would #{default_text}"
+              "expected that `#{result.service.class}` result would #{default_text}"
             end
 
             ##
@@ -55,7 +64,7 @@ module ConvenientService
             #   https://relishapp.com/rspec/rspec-expectations/v/3-11/docs/custom-matchers/define-a-custom-matcher#overriding-the-failure-message-when-negated
             #
             def failure_message_when_negated
-              "expected that #{result} would NOT #{default_text}"
+              "expected that `#{result.service.class}` result would NOT #{default_text}"
             end
 
             ##
@@ -131,12 +140,31 @@ module ConvenientService
             # @param service_class [Class]
             # @return [ConvenientService::RSpec::Matchers::Custom::Results::Base]
             #
-            def of(service_class)
+            def of_service(service_class)
               chain[:service_class] = service_class
 
               self
             end
 
+            ##
+            # @param step [Class, Symbol]
+            # @return [ConvenientService::RSpec::Matchers::Custom::Results::Base]
+            #
+            def of_step(step)
+              chain[:step] = step
+
+              self
+            end
+
+            ##
+            # @return [ConvenientService::RSpec::Matchers::Custom::Results::Base]
+            #
+            def without_step
+              chain[:step] = nil
+
+              self
+            end
+
             private
 
             ##
@@ -149,21 +177,45 @@ module ConvenientService
             # @return [String]
             #
             def default_text
+              expected_parts << "\n\n" << got_parts
+            end
+
+            ##
+            # @return [String]
+            #
+            # @internal
+            #   TODO: Align for easier visual comparison.
+            #   TODO: New line for each attribute.
+            #
+            def expected_parts
               parts = []
 
               parts << "be #{printable_statuses}"
-              parts << "of `#{service_class}`" if used_of?
+              parts << "of service `#{service_class}`" if used_of_service?
+              parts << Commands::GenerateExpectedStepPart.call(step: step) if used_of_step?
               parts << "with data `#{data}`" if used_data?
               parts << "with message `#{message}`" if used_message?
               parts << "with code `#{code}`" if used_code?
 
-              parts << "\n\n"
+              parts.join(" ")
+            end
+
+            ##
+            # @return [String]
+            #
+            # @internal
+            #   TODO: Align for easier visual comparison.
+            #   TODO: New line for each attribute.
+            #
+            def got_parts
+              parts = []
 
               parts << "got `#{result.status}`"
-              parts << "of `#{result.service.class}`" if used_of?
-              parts << "with data `#{result.data}`" if used_data?
-              parts << "with message `#{result.message}`" if used_message?
-              parts << "with code `#{result.code}`" if used_code?
+              parts << "of service `#{result.service.class}`" if used_of_service?
+              parts << Commands::GenerateGotStepPart.call(result: result) if used_of_step?
+              parts << "with data `#{result.unsafe_data}`" if used_data?
+              parts << "with message `#{result.unsafe_message}`" if used_message?
+              parts << "with code `#{result.unsafe_code}`" if used_code?
 
               parts.join(" ")
             end
@@ -192,10 +244,17 @@ module ConvenientService
             ##
             # @return [Boolean]
             #
-            def used_of?
+            def used_of_service?
               chain.key?(:service_class)
             end
 
+            ##
+            # @return [Boolean]
+            #
+            def used_of_step?
+              chain.key?(:step)
+            end
+
             ##
             # @return [Hash]
             #
@@ -224,6 +283,13 @@ module ConvenientService
               Utils::Object.instance_variable_fetch(self, :@service_class) { chain[:service_class] }
             end
 
+            ##
+            # @return [Class]
+            #
+            def step
+              Utils::Object.instance_variable_fetch(self, :@step) { chain[:step] }
+            end
+
             ##
             # @return [Hash]
             #