convenient_service 0.1.0

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

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        ##
+        #   specify {
+        #     expect { method_class.cast(other, **options) }
+        #       .to delegate_to(ConvenientService::Service::Plugins::HasResultSteps::Entities::Method::Commands::CastMethod, :call)
+        #       .with_arguments(other: other, options: options)
+        #       .and_return_its_value
+        #   }
+        #
+        #   { method_class.cast(other, **options) }
+        #   # => block_expectation
+        #
+        #   ConvenientService::Service::Plugins::HasResultSteps::Entities::Method::Commands::CastMethod
+        #   # => object
+        #
+        #   :call
+        #   #=> method
+        #
+        #   (other: other, options: options)
+        #   # => chain[:with]
+        #
+        #   and_return_its_value
+        #   # => chain[:and_return_its_value]
+        #
+        # NOTE: A similar (with different behaviour) matcher exists in `saharspec`.
+        # https://github.com/zverok/saharspec#send_messageobject-method-matcher
+        #
+        class DelegateTo
+          ##
+          # NOTE: `include ::RSpec::Expectations`.
+          # - https://github.com/rspec/rspec-expectations/blob/v3.11.0/lib/rspec/expectations.rb
+          # - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/expectations.rb#L60
+          #
+          include ::RSpec::Expectations
+
+          ##
+          # NOTE: `include ::RSpec::Matchers`.
+          # - https://github.com/rspec/rspec-expectations/blob/v3.11.0/lib/rspec/matchers.rb
+          # - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/matchers.rb
+          #
+          include ::RSpec::Matchers
+
+          ##
+          # 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
+
+          ##
+          #
+          #
+          def initialize(object, method)
+            @object = object
+            @method = method
+          end
+
+          ##
+          #
+          #
+          def matches?(block_expectation)
+            @block_expectation = block_expectation
+
+            ##
+            # TODO: Support multiple `with_arguments` calls.
+            #
+            if used_with_arguments?
+              ##
+              # 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
+              #
+              allow(object).to receive(method).and_wrap_original do |original, *actual_args, **actual_kwargs, &actual_block|
+                ##
+                # TODO: Provide customized error messages?
+                # https://relishapp.com/rspec/rspec-expectations/docs/customized-message
+                #
+                # NOTE: `delegate_to` expects that delegation is executed only once during `block_expectation`.
+                #
+                expect(actual_args).to eq(expected_args)
+                expect(actual_kwargs).to eq(expected_kwargs)
+                expect(actual_block).to eq(expected_block)
+
+                ##
+                # NOTE: Imitates `and_call_original`.
+                #
+                original.call(*actual_args, **actual_kwargs, &actual_block)
+              end
+            else
+              allow(object).to receive(method).and_call_original
+            end
+
+            ##
+            # NOTE: Calls `block_expectation` before checking expections.
+            #
+            value = block_expectation.call
+
+            ##
+            # NOTE: If this expectation fails, it means `delegate_to` is NOT met.
+            #
+            expect(object).to have_received(method)
+
+            ##
+            # 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
+            #
+            # NOTE: If this expectation fails, it means `and_return_its_value` is NOT met.
+            #
+            expect(value).to eq(object.__send__(method, *args, **kwargs, &block)) if used_and_return_its_value?
+
+            ##
+            # IMPORTANT: A matcher should always return a boolean.
+            # https://github.com/zverok/saharspec/blob/master/lib/saharspec/matchers/send_message.rb#L59
+            #
+            # NOTE: RSpec raises exception when any `expect` is NOT satisfied.
+            # So, this `true` is returned only when all `expect` are successful.
+            #
+            true
+          end
+
+          ##
+          # NOTE: Required by RSpec.
+          # https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/custom-matchers/define-a-matcher-supporting-block-expectations
+          #
+          def supports_block_expectations?
+            true
+          end
+
+          ##
+          #
+          #
+          def description
+            "delegate to `#{printable_method}`"
+          end
+
+          ##
+          # IMPORTANT: `failure_message`, `failure_message_when_negated` are NOT implemented, since they are never called (since `matches?` always returns `true`).
+          #
+
+          def with_arguments(*args, **kwargs, &block)
+            chain[:with_arguments] = {args: args, kwargs: kwargs, block: block}
+
+            self
+          end
+
+          def and_return_its_value
+            chain[:and_return_its_value] = true
+
+            self
+          end
+
+          def printable_method
+            @printable_method ||=
+              case Utils::Object.resolve_type(object)
+              when "class", "module"
+                "#{object}.#{method}"
+              when "instance"
+                "#{object.class}##{method}"
+              end
+          end
+
+          private
+
+          attr_reader :object, :method, :block_expectation
+
+          def used_with_arguments?
+            chain.key?(:with_arguments)
+          end
+
+          def used_and_return_its_value?
+            chain.key?(:and_return_its_value)
+          end
+
+          def chain
+            @chain ||= {}
+          end
+
+          def args
+            @args ||= chain.dig(:with_arguments, :args) || []
+          end
+
+          alias_method :expected_args, :args
+
+          def kwargs
+            @kwargs ||= chain.dig(:with_arguments, :kwargs) || {}
+          end
+
+          alias_method :expected_kwargs, :kwargs
+
+          ##
+          # NOTE: `if defined?` is used in order to cache `nil` if needed.
+          #
+          def block
+            return @block if defined? @block
+
+            @block = chain.dig(:with_arguments, :block)
+          end
+
+          alias_method :expected_block, :block
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class ExtendModule
+          ##
+          # NOTE: `mod` since `module` is a keyword.
+          #
+          def initialize(mod)
+            @mod = mod
+          end
+
+          def matches?(klass)
+            @klass = klass
+
+            klass.singleton_class.included_modules.include?(mod)
+          end
+
+          def description
+            "extend module `#{mod}`"
+          end
+
+          def failure_message
+            "expected `#{klass}` to extend module `#{mod}`"
+          end
+
+          def failure_message_when_negated
+            "expected `#{klass}` NOT to extend module `#{mod}`"
+          end
+
+          private
+
+          attr_reader :klass, :mod
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class HaveAbstractMethod
+          def initialize(method_name)
+            @method_name = method_name
+          end
+
+          def matches?(object)
+            @object = object
+
+            begin
+              object.__send__(method_name)
+
+              false
+            rescue ConvenientService::Support::AbstractMethod::Errors::AbstractMethodNotOverridden
+              true
+            rescue
+              false
+            end
+          end
+
+          def description
+            "have abstract method `#{method_name}`"
+          end
+
+          def failure_message
+            "expected `#{object.class}` to have abstract method `#{method_name}`"
+          end
+
+          def failure_message_when_negated
+            "expected `#{object.class}` NOT to have abstract method `#{method_name}`"
+          end
+
+          private
+
+          attr_reader :object, :method_name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class HaveAliasMethod
+          def initialize(alias_name, original_name)
+            @alias_name = alias_name
+            @original_name = original_name
+          end
+
+          def matches?(object)
+            @object = object
+
+            return false unless Utils::Method.defined?(original_name, object.class, private: true)
+
+            return false unless Utils::Method.defined?(alias_name, object.class, private: true)
+
+            ##
+            # https://stackoverflow.com/a/45640516/12201472
+            #
+            object.method(alias_name).original_name == object.method(original_name).original_name
+          end
+
+          def description
+            "have alias method `#{alias_name}` for `#{original_name}`"
+          end
+
+          def failure_message
+            "expected `#{object.class}` to have alias method `#{alias_name}` for `#{original_name}`"
+          end
+
+          def failure_message_when_negated
+            "expected `#{object.class}` NOT to have alias method `#{alias_name}` for `#{original_name}`"
+          end
+
+          private
+
+          attr_reader :object, :alias_name, :original_name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        ##
+        # TODO: Specs.
+        #
+        class HaveAttrAccessor
+          def initialize(attr_name)
+            @attr_name = attr_name
+          end
+
+          def matches?(object)
+            @object = object
+
+            Custom::HaveAttrReader.new(attr_name).matches?(object)
+            Custom::HaveAttrWriter.new(attr_name).matches?(object)
+
+            true
+          end
+
+          def description
+            "have attr accessor `#{attr_name}`"
+          end
+
+          def failure_message
+            "expected `#{object.class}` to have attr accessor `#{attr_name}`"
+          end
+
+          def failure_message_when_negated
+            "expected `#{object.class}` NOT to have attr accessor `#{attr_name}`"
+          end
+
+          private
+
+          attr_reader :object, :attr_name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        ##
+        # TODO: Specs.
+        #
+        class HaveAttrReader
+          def initialize(attr_name)
+            @attr_name = attr_name
+          end
+
+          def matches?(object)
+            @object = object
+
+            ##
+            # IMPORTANT: A copy is created in order to be thread safe.
+            #
+            copy = object.dup
+
+            copy.instance_variable_set("@#{attr_name}", :custom_value)
+
+            copy.public_send(attr_name) == :custom_value
+          end
+
+          def description
+            "have attr reader `#{attr_name}`"
+          end
+
+          def failure_message
+            "expected `#{object.class}` to have attr reader `#{attr_name}`"
+          end
+
+          def failure_message_when_negated
+            "expected `#{object.class}` NOT to have attr reader `#{attr_name}`"
+          end
+
+          private
+
+          attr_reader :object, :attr_name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        ##
+        # TODO: Specs.
+        #
+        class HaveAttrWriter
+          def initialize(attr_name)
+            @attr_name = attr_name
+          end
+
+          def matches?(object)
+            @object = object
+
+            ##
+            # IMPORTANT: A copy is created in order to be thread safe.
+            #
+            copy = object.dup
+
+            copy.public_send("#{attr_name}=", :custom_value)
+
+            copy.instance_variable_get("@#{attr_name}") == :custom_value
+          end
+
+          def description
+            "have attr writer `#{attr_name}`"
+          end
+
+          def failure_message
+            "expected `#{object.class}` to have attr writer `#{attr_name}`"
+          end
+
+          def failure_message_when_negated
+            "expected `#{object.class}` NOT to have attr writer `#{attr_name}`"
+          end
+
+          private
+
+          attr_reader :object, :attr_name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class IncludeModule
+          ##
+          # NOTE: `mod` since `module` is a keyword.
+          #
+          def initialize(mod)
+            @mod = mod
+          end
+
+          def matches?(klass)
+            @klass = klass
+
+            klass.included_modules.include?(mod)
+          end
+
+          def description
+            "include module `#{mod}`"
+          end
+
+          def failure_message
+            "expected `#{klass}` to include module `#{mod}`"
+          end
+
+          def failure_message_when_negated
+            "expected `#{klass}` NOT to include module `#{mod}`"
+          end
+
+          private
+
+          attr_reader :klass, :mod
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        class PrependModule
+          ##
+          # NOTE: `mod` since `module` is a keyword.
+          #
+          def initialize(mod)
+            @mod = mod
+          end
+
+          def matches?(klass)
+            @klass = klass
+
+            klass.ancestors.take_while { |ancestor| ancestor != klass }.include?(mod)
+          end
+
+          def description
+            "prepend module `#{mod}`"
+          end
+
+          def failure_message
+            "expected `#{klass}` to prepend module `#{mod}`"
+          end
+
+          def failure_message_when_negated
+            "expected `#{klass}` NOT to prepend module `#{mod}`"
+          end
+
+          private
+
+          attr_reader :klass, :mod
+        end
+      end
+    end
+  end
+end