cuprum 0.7.0 → 0.10.0.rc.0

data/lib/cuprum/result.rb

@@ -1,154 +1,91 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 module Cuprum
   # Data object that encapsulates the result of calling a Cuprum command.
   class Result
+    STATUSES = %i[success failure].freeze
+
     # @param value [Object] The value returned by calling the command.
-    # @param errors [Array] The errors (if any) generated when the command was
-    #   called.
-    def initialize value = nil, errors: []
+    # @param error [Object] The error (if any) generated when the command was
+    #   called. Can be a Cuprum::Error, a model errors object, etc.
+    # @param status [String, Symbol] The status of the result. Must be :success,
+    #   :failure, or nil.
+    def initialize(value: nil, error: nil, status: nil)
       @value  = value
-      @errors = errors
-      @status = nil
-      @halted = false
-    end # constructor
+      @error  = error
+      @status = resolve_status(status)
+    end
 
     # @return [Object] the value returned by calling the command.
-    attr_accessor :value
+    attr_reader :value
 
-    # @return [Array] the errors (if any) generated when the command was
+    # @return [Object] the error (if any) generated when the command was
     #   called.
-    attr_accessor :errors
+    attr_reader :error
+
+    # @return [Symbol] the status of the result, either :success or :failure.
+    attr_reader :status
 
-    # rubocop:disable Metrics/AbcSize
     # rubocop:disable Metrics/CyclomaticComplexity
-    # rubocop:disable Metrics/MethodLength
-    # rubocop:disable Metrics/PerceivedComplexity
 
     # Compares the other object to the result.
     #
     # @param other [#value, #success?] An object responding to, at minimum,
-    #   #value and #success?. If present, the #failure?, #errors and #halted?
-    #   values will also be compared.
+    #   #value and #success?. If present, the #failure? and #error values
+    #   will also be compared.
     #
     # @return [Boolean] True if all present values match the result, otherwise
     #   false.
-    def == other
-      return false unless other.respond_to?(:value) && other.value == value
-
-      unless other.respond_to?(:success?) && other.success? == success?
-        return false
-      end # unless
-
-      if other.respond_to?(:failure?) && other.failure? != failure?
-        return false
-      end # if
-
-      if other.respond_to?(:errors) && other.errors != errors
-        return false
-      end # if
-
-      if other.respond_to?(:halted?) && other.halted? != halted?
-        return false
-      end # if
+    def ==(other)
+      return false unless other.respond_to?(:value)  && other.value  == value
+      return false unless other.respond_to?(:status) && other.status == status
+      return false unless other.respond_to?(:error)  && other.error  == error
 
       true
-    end # method ==
-    # rubocop:enable Metrics/AbcSize
+    end
     # rubocop:enable Metrics/CyclomaticComplexity
-    # rubocop:enable Metrics/MethodLength
-    # rubocop:enable Metrics/PerceivedComplexity
 
-    # @return [Boolean] true if the result is empty, i.e. has no value or errors
-    #   and does not have its status set or is halted.
-    def empty?
-      value.nil? && errors.empty? && @status.nil? && !halted?
-    end # method empty?
-
-    # Marks the result as a failure, whether or not the command generated any
-    # errors.
-    #
-    # @return [Cuprum::Result] The result.
-    def failure!
-      @status = :failure
-
-      self
-    end # method failure!
-
-    # @return [Boolean] false if the command did not generate any errors,
-    #   otherwise true.
+    # @return [Boolean] true if the result status is :failure, otherwise false.
     def failure?
-      @status == :failure || (@status.nil? && !errors.empty?)
-    end # method failure?
-
-    # Marks the result as halted. Any subsequent chained commands will not be
-    #   run.
-    #
-    # @return [Cuprum::Result] The result.
-    def halt!
-      @halted = true
-
-      self
-    end # method halt!
-
-    # @return [Boolean] true if the command has been halted, and will not run
-    #   any subsequent chained commands.
-    def halted?
-      @halted
-    end # method halted?
-
-    # Marks the result as a success, whether or not the command generated any
-    # errors.
-    #
-    # @return [Cuprum::Result] The result.
-    def success!
-      @status = :success
-
-      self
-    end # method success!
+      @status == :failure
+    end
 
-    # @return [Boolean] true if the command did not generate any errors,
-    #   otherwise false.
+    # @return [Boolean] true if the result status is :success, otherwise false.
     def success?
-      @status == :success || (@status.nil? && errors.empty?)
-    end # method success?
+      @status == :success
+    end
 
     # @return [Cuprum::Result] The result.
-    def to_result
+    def to_cuprum_result
       self
-    end # method to_result
+    end
 
-    # @api private
-    def update other_result
-      return self if other_result.nil?
-
-      self.value = other_result.value
-
-      update_status(other_result)
-
-      update_errors(other_result)
-
-      halt! if other_result.halted?
+    private
 
-      self
-    end # method update
+    def defined_statuses
+      self.class::STATUSES
+    end
 
-    protected
+    def normalize_status(status)
+      return status unless status.is_a?(String) || status.is_a?(Symbol)
 
-    attr_reader :status
+      tools.string_tools.underscore(status).intern
+    end
 
-    private
+    def resolve_status(status)
+      return error.nil? ? :success : :failure if status.nil?
 
-    def update_errors other_result
-      return if other_result.errors.empty?
+      normalized = normalize_status(status)
 
-      @errors += other_result.errors
-    end # method update_errors
+      return normalized if defined_statuses.include?(normalized)
 
-    def update_status other_result
-      return if status || !errors.empty?
+      raise ArgumentError, "invalid status #{status.inspect}"
+    end
 
-      @status = other_result.status
-    end # method update_status
-  end # class
-end # module
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/result_helpers.rb

@@ -1,113 +1,22 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 module Cuprum
-  # Helper methods that delegate result methods to the currently processed
-  # result.
-  #
-  # @example
-  #   class LogCommand
-  #     include Cuprum::Processing
-  #     include Cuprum::ResultHelpers
-  #
-  #     private
-  #
-  #     def process log
-  #       case log[:level]
-  #       when 'fatal'
-  #         halt!
-  #
-  #         'error'
-  #       when 'error' && log[:message]
-  #         errors << message
-  #
-  #         'error'
-  #       when 'error'
-  #         failure!
-  #
-  #         'error'
-  #       else
-  #         'ok'
-  #       end # case
-  #     end # method process
-  #   end # class
-  #
-  #   result = LogCommand.new.call(:level => 'info')
-  #   result.success? #=> true
-  #
-  #   string = 'something went wrong'
-  #   result = LogCommand.new.call(:level => 'error', :message => string)
-  #   result.success? #=> false
-  #   result.errors   #=> ['something went wrong']
-  #
-  #   result = LogCommand.new.call(:level => 'error')
-  #   result.success? #=> false
-  #   result.errors   #=> []
-  #
-  #   result = LogCommand.new.call(:level => 'fatal')
-  #   result.halted? #=> true
-  #
-  # @see Cuprum::Command
+  # Helper methods for generating Cuprum result objects.
   module ResultHelpers
     private
 
-    # @!visibility public
-    #
-    # Provides a reference to the current result's errors object. Messages or
-    # error objects added to this will be included in the #errors method of the
-    # returned result object.
-    #
-    # @return [Array, Object] The errors object.
-    #
-    # @see Cuprum::Result#errors.
-    #
-    # @note This is a private method, and only available when executing the
-    #   command implementation as defined in the constructor block or the
-    #   #process method.
-    def errors
-      result&.errors
-    end # method errors
-
-    # @!visibility public
-    #
-    # Marks the current result as failed. Calling #failure? on the returned
-    # result object will evaluate to true, whether or not the result has any
-    # errors.
-    #
-    # @see Cuprum::Result#failure!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   command implementation as defined in the constructor block or the
-    #   #process method.
-    def failure!
-      result&.failure!
-    end # method failure!
+    def build_result(error: nil, status: nil, value: nil)
+      Cuprum::Result.new(error: error, status: status, value: value)
+    end
 
-    # @!visibility public
-    #
-    # Marks the current result as halted.
-    #
-    # @see Cuprum::Result#halt!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   command implementation as defined in the constructor block or the
-    #   #process method.
-    def halt!
-      result&.halt!
-    end # method halt!
+    def failure(error)
+      build_result(error: error)
+    end
 
-    # @!visibility public
-    #
-    # Marks the current result as passing. Calling #success? on the returned
-    # result object will evaluate to true, whether or not the result has any
-    # errors.
-    #
-    # @see Cuprum::Result#success!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   command implementation as defined in the constructor block or the
-    #   #process method.
-    def success!
-      result&.success!
-    end # method success!
-  end # module
-end # module
+    def success(value)
+      build_result(value: value)
+    end
+  end
+end

data/lib/cuprum/rspec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Namespace for RSpec extensions for testing Cuprum applications.
+  module RSpec; end
+end

data/lib/cuprum/rspec/be_a_result.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'cuprum/rspec/be_a_result_matcher'
+
+module RSpec
+  module Matchers # rubocop:disable Style/Documentation
+    def be_a_failing_result
+      be_a_result.with_status(:failure)
+    end
+
+    def be_a_passing_result
+      be_a_result.with_status(:success).and_error(nil)
+    end
+
+    def be_a_result
+      Cuprum::RSpec::BeAResultMatcher.new
+    end
+  end
+end

data/lib/cuprum/rspec/be_a_result_matcher.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require 'cuprum/errors/operation_not_called'
+require 'cuprum/rspec'
+
+module Cuprum::RSpec
+  # Custom matcher that asserts the actual object is a Cuprum result object with
+  # the specified properties.
+  class BeAResultMatcher # rubocop:disable Metrics/ClassLength
+    DEFAULT_VALUE = Object.new.freeze
+    private_constant :DEFAULT_VALUE
+
+    RSPEC_MATCHER_METHODS = %i[description failure_message matches?].freeze
+    private_constant :RSPEC_MATCHER_METHODS
+
+    def initialize
+      @expected_error = DEFAULT_VALUE
+      @expected_value = DEFAULT_VALUE
+    end
+
+    # @return [String] a short description of the matcher and expected
+    #   properties.
+    def description
+      message = 'be a Cuprum result'
+
+      return message unless expected_properties?
+
+      "#{message} #{properties_description}"
+    end
+
+    # Checks that the given actual object is not a Cuprum result.
+    #
+    # @param actual [Object] The actual object to match.
+    #
+    # @return [Boolean] false if the actual object is a result; otherwise true.
+    def does_not_match?(actual)
+      @actual = actual
+
+      raise ArgumentError, negated_matcher_warning if expected_properties?
+
+      !actual_is_result?
+    end
+
+    # @return [String] a summary message describing a failed expectation.
+    def failure_message
+      message = "expected #{actual.inspect} to #{description}"
+
+      if !actual_is_result?
+        message + ', but the object is not a result'
+      elsif actual_is_uncalled_operation?
+        message + ', but the object is an uncalled operation'
+      elsif !properties_match?
+        message + properties_failure_message
+      else
+        # :nocov:
+        message
+        # :nocov:
+      end
+    end
+
+    # @return [String] a summary message describing a failed negated
+    #   expectation.
+    def failure_message_when_negated
+      "expected #{actual.inspect} not to #{description}"
+    end
+
+    # Checks that the given actual object is a Cuprum result or compatible
+    # object and has the specified properties.
+    #
+    # @param actual [Object] The actual object to match.
+    #
+    # @return [Boolean] true if the actual object is a result with the expected
+    #   properties; otherwise false.
+    def matches?(actual)
+      @actual = actual
+
+      actual_is_result? && !actual_is_uncalled_operation? && properties_match?
+    end
+
+    # Sets an error expectation on the matcher. Calls to #matches? will fail
+    # unless the actual object has the specified error.
+    #
+    # @param error [Cuprum::Error, Object] The expected error.
+    #
+    # @return [BeAResultMatcher] the updated matcher.
+    def with_error(error)
+      @expected_error = error
+
+      self
+    end
+    alias_method :and_error, :with_error
+
+    # Sets a status expectation on the matcher. Calls to #matches? will fail
+    # unless the actual object has the specified status.
+    #
+    # @param status [Symbol] The expected status.
+    #
+    # @return [BeAResultMatcher] the updated matcher.
+    def with_status(status)
+      @expected_status = status
+
+      self
+    end
+    alias_method :and_status, :with_status
+
+    # Sets a value expectation on the matcher. Calls to #matches? will fail
+    # unless the actual object has the specified value.
+    #
+    # @param value [Object] The expected value.
+    #
+    # @return [BeAResultMatcher] the updated matcher.
+    def with_value(value)
+      @expected_value = value
+
+      self
+    end
+    alias_method :and_value, :with_value
+
+    private
+
+    attr_reader \
+      :actual,
+      :expected_error,
+      :expected_status,
+      :expected_value
+
+    def actual_is_result?
+      actual.respond_to?(:to_cuprum_result)
+    end
+
+    def actual_is_uncalled_operation?
+      result.error.is_a?(Cuprum::Errors::OperationNotCalled)
+    end
+
+    def compare_items(expected, actual)
+      return expected.matches?(actual) if expected.respond_to?(:matches?)
+
+      expected == actual
+    end
+
+    def error_failure_message
+      return '' if error_matches?
+
+      "\n   expected error: #{inspect_expected(expected_error)}" \
+      "\n     actual error: #{result.error.inspect}"
+    end
+
+    def error_matches?
+      return @error_matches unless @error_matches.nil?
+
+      return @error_matches = true unless expected_error?
+
+      @error_matches = compare_items(expected_error, result.error)
+    end
+
+    def expected_properties?
+      (expected_error? && !expected_error.nil?) ||
+        expected_status? ||
+        expected_value?
+    end
+
+    def expected_error?
+      expected_error != DEFAULT_VALUE
+    end
+
+    def expected_status?
+      !!expected_status
+    end
+
+    def expected_value?
+      expected_value != DEFAULT_VALUE
+    end
+
+    def inspect_expected(expected)
+      return expected.description if rspec_matcher?(expected)
+
+      expected.inspect
+    end
+
+    def negated_matcher_warning
+      "Using `expect().not_to be_a_result#{properties_warning}` risks false" \
+      ' positives, since any other result will match.'
+    end
+
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/AbcSize
+    def properties_description
+      msg = ''
+      ary = []
+      ary << 'value' if expected_value?
+      ary << 'error' if expected_error? && !expected_error.nil?
+
+      unless ary.empty?
+        msg = "with the expected #{tools.array_tools.humanize_list(ary)}"
+      end
+
+      return msg unless expected_status?
+
+      return "with status: #{expected_status.inspect}" if msg.empty?
+
+      msg + " and status: #{expected_status.inspect}"
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/AbcSize
+
+    def properties_failure_message
+      properties_short_message +
+        status_failure_message +
+        value_failure_message +
+        error_failure_message
+    end
+
+    def properties_match?
+      error_matches? && status_matches? && value_matches?
+    end
+
+    def properties_short_message
+      ary = []
+      ary << 'status' unless status_matches?
+      ary << 'value'  unless value_matches?
+      ary << 'error'  unless error_matches?
+
+      ", but the #{tools.array_tools.humanize_list(ary)}" \
+      " #{tools.integer_tools.pluralize(ary.size, 'does', 'do')} not match:"
+    end
+
+    def properties_warning
+      ary = []
+      ary << 'value'  if expected_value?
+      ary << 'status' if expected_status?
+      ary << 'error'  if expected_error?
+
+      return '' if ary.empty?
+
+      message = ".with_#{ary.first}()"
+
+      return message if ary.size == 1
+
+      message + ary[1..-1].map { |str| ".and_#{str}()" }.join
+    end
+
+    def result
+      @result ||= actual.to_cuprum_result
+    end
+
+    def rspec_matcher?(value)
+      RSPEC_MATCHER_METHODS.all? do |method_name|
+        value.respond_to?(method_name)
+      end
+    end
+
+    def status_failure_message
+      return '' if status_matches?
+
+      "\n  expected status: #{expected_status.inspect}" \
+      "\n    actual status: #{result.status.inspect}"
+    end
+
+    def status_matches?
+      return @status_matches unless @status_matches.nil?
+
+      return @status_matches = true unless expected_status?
+
+      @status_matches = result.status == expected_status
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def value_failure_message
+      return '' if value_matches?
+
+      "\n   expected value: #{inspect_expected(expected_value)}" \
+      "\n     actual value: #{result.value.inspect}"
+    end
+
+    def value_matches?
+      return @value_matches unless @value_matches.nil?
+
+      return @value_matches = true unless expected_value?
+
+      @value_matches = compare_items(expected_value, result.value)
+    end
+  end
+end