rspec-sleeping_king_studios 2.6.0 → 2.7.0.rc.0

data/lib/rspec/sleeping_king_studios/concerns/include_contract.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require 'sleeping_king_studios/tools/toolbelt'
+
+require 'rspec/sleeping_king_studios/concerns'
+
+module RSpec::SleepingKingStudios::Concerns
+  # Defines helpers for including reusable contracts in RSpec example groups.
+  #
+  # RSpec contracts are a mechanism for sharing tests between projects. For
+  # example, one library may define an interface or specification for a type of
+  # object, while a second library implements that object. By defining a
+  # contract and sharing that contract as part of the library, the developer
+  # ensures that any object that matches the contract has correctly implemented
+  # and conforms to the interface. This reduces duplication of tests and
+  # provides resiliency as an interface is developed over time and across
+  # versions of the library.
+  #
+  # Mechanically speaking, each contract encapsulates a section of RSpec code.
+  # When the contract is included in a spec, that code is then injected into the
+  # spec. Writing a contract, therefore, is no different than writing any other
+  # RSpec specification - it is only the delivery mechanism that differs. A
+  # contract can be any object that responds to #to_proc; the simplest contract
+  # is therefore a Proc or lambda that contains some RSpec code.
+  #
+  # @example Defining A Contract
+  #   module ExampleContracts
+  #     # This contract asserts that the object has the Enumerable module as an
+  #     # ancestor, and that it responds to the #each method.
+  #     SHOULD_BE_ENUMERABLE_CONTRACT = lambda do
+  #       it 'should be Enumerable' do
+  #         expect(subject).to be_a Enumerable
+  #       end
+  #
+  #       it 'should respond to #each' do
+  #         expect(subject).to respond_to(:each).with(0).arguments
+  #       end
+  #     end
+  #   end
+  #
+  #   RSpec.describe Array do
+  #     extend RSpec::SleepingKingStudios::Concerns::IncludeContract
+  #
+  #     include_contract ExampleContracts::SHOULD_BE_ENUMERABLE_CONTRACT
+  #   end
+  #
+  #   RSpec.describe Hash do
+  #     extend  RSpec::SleepingKingStudios::Concerns::IncludeContract
+  #     include ExampleContracts
+  #
+  #     include_contract 'should be enumerable'
+  #   end
+  #
+  # @example Defining A Contract With Parameters
+  #   module SerializerContracts
+  #     # This contract asserts that the serialized result has the expected
+  #     # values.
+  #     #
+  #     # First, we pass the contract a series of attribute names. These are
+  #     # used to assert that the serialized attributes match the values on the
+  #     # original object.
+  #     #
+  #     # Second, we pass the contract a set of attribute names and values.
+  #     # These are used to assert that the serialized attributes have the
+  #     # specified values.
+  #     #
+  #     # Finally, we can pass the contract a block, which the contract then
+  #     # executes. Note that the block is executed in the context of our
+  #     # describe block, and thus can take advantage of our memoized
+  #     # #serialized helper method.
+  #     SHOULD_SERIALIZE_ATTRIBUTES_CONTRACT = lambda \
+  #     do |*attributes, **values, &block|
+  #       describe '#serialize' do
+  #         let(:serialized) { subject.serialize }
+  #
+  #         it { expect(subject).to respond_to(:serialize).with(0).arguments }
+  #
+  #         attributes.each do |attribute|
+  #           it "should serialize #{attribute}" do
+  #             expect(serialized[attribute]).to be == subject[attribute]
+  #           end
+  #         end
+  #
+  #         values.each do |attribute, value|
+  #           it "should serialize #{attribute}" do
+  #             expect(serialized[attribute]).to be == value
+  #           end
+  #         end
+  #
+  #         instance_exec(&block) if block
+  #       end
+  #     end
+  #
+  #   RSpec.describe CaptainPicard do
+  #     extend  RSpec::SleepingKingStudios::Concerns::IncludeContract
+  #     include SerializerContracts
+  #
+  #     include_contract 'should serialize attributes',
+  #       :name,
+  #       :rank,
+  #       lights: 4 do
+  #         it 'should serialize the catchphrase' do
+  #           expect(serialized[:catchphrase]).to be == 'Make it so.'
+  #         end
+  #     end
+  #   end
+  #
+  # @see RSpec::SleepingKingStudios::Contract.
+  module IncludeContract
+    class << self
+      # @private
+      def define_contract_method(context:, contract:, name:)
+        method_name = +'rspec_include_contract'
+        method_name << '_' << tools.str.underscore(name) if contract_name?(name)
+        method_name << '_' << tools.str.underscore(SecureRandom.uuid)
+        method_name = method_name.tr(' ', '_').intern
+
+        context.define_singleton_method(method_name, &contract)
+
+        yield method_name
+      ensure
+        if context.singleton_class.respond_to?(method_name)
+          context.singleton_class.remove_method(method_name)
+        end
+      end
+
+      # @private
+      def resolve_contract(context:, contract_or_name:)
+        validate_contract!(contract_or_name)
+
+        return contract_or_name unless contract_name?(contract_or_name)
+
+        contract_name = contract_or_name.to_s
+        contract      =
+          resolve_contract_class(context, "#{contract_name} contract") ||
+          resolve_contract_const(context, "#{contract_name} contract") ||
+          resolve_contract_class(context, contract_name) ||
+          resolve_contract_const(context, contract_name)
+
+        return contract if contract
+
+        raise ArgumentError, "undefined contract #{contract_or_name.inspect}"
+      end
+
+      private
+
+      def contract?(contract_or_name)
+        contract_or_name.respond_to?(:to_proc)
+      end
+
+      def contract_name?(contract_or_name)
+        contract_or_name.is_a?(String) || contract_or_name.is_a?(Symbol)
+      end
+
+      def resolve_contract_class(context, contract_name)
+        class_name = tools.str.camelize(contract_name.tr(' ', '_'))
+
+        return nil unless context.const_defined?(class_name)
+
+        context.const_get(class_name)
+      end
+
+      def resolve_contract_const(context, contract_name)
+        const_name = tools.str.underscore(contract_name.tr(' ', '_')).upcase
+
+        return nil unless context.const_defined?(const_name)
+
+        context.const_get(const_name)
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+
+      def validate_contract!(contract_or_name)
+        raise ArgumentError, "contract can't be blank" if contract_or_name.nil?
+
+        if contract_name?(contract_or_name)
+          return unless contract_or_name.to_s.empty?
+
+          raise ArgumentError, "contract can't be blank"
+        end
+
+        return if contract?(contract_or_name)
+
+        raise ArgumentError, 'contract must be a name or respond to #to_proc'
+      end
+    end
+
+    # As #include_contract, but wraps the contract in a focused example group.
+    #
+    # @see include_contract.
+    def finclude_contract(contract_or_name, *arguments, **keywords, &block)
+      fdescribe '(focused)' do
+        if keywords.empty?
+          include_contract(contract_or_name, *arguments, &block)
+        else
+          include_contract(contract_or_name, *arguments, **keywords, &block)
+        end
+      end
+    end
+
+    # Adds the contract to the example group with the given parameters.
+    #
+    # @overload include_contract(contract, *arguments, **keywords, &block)
+    #   @param contract [#to_proc] The contract to include.
+    #   @param arguments [Array] The arguments to pass to the contract.
+    #   @param keywords [Hash] The keywords to pass to the contract.
+    #
+    #   @yield A block passed to the contract.
+    #
+    # @overload include_contract(contract_name, *arguments, **keywords, &block)
+    #   @param contract_name [String, Symbol] The name of contract to include.
+    #     The contract must be defined as a Class or constant in the same scope,
+    #     e.g. include_contract('does something') expects the example group to
+    #     define either a DoSomething class or a DO_SOMETHING constant. The name
+    #     can optionally be suffixed with "contract", so it will also match a
+    #     DoSomethingContract class or a DO_SOMETHING_CONTRACT constant.
+    #   @param arguments [Array] The arguments to pass to the contract.
+    #   @param keywords [Hash] The keywords to pass to the contract.
+    #
+    #   @yield A block passed to the contract.
+    #
+    #   @raise ArgumentError
+    def include_contract(contract_or_name, *arguments, **keywords, &block) # rubocop:disable Metrics/MethodLength
+      concern  = RSpec::SleepingKingStudios::Concerns::IncludeContract
+      contract = concern.resolve_contract(
+        context:          self,
+        contract_or_name: contract_or_name
+      )
+
+      concern.define_contract_method(
+        context:  self,
+        contract: contract,
+        name:     contract_or_name
+      ) do |method_name|
+        if keywords.empty?
+          send(method_name, *arguments, &block)
+        else
+          send(method_name, *arguments, **keywords, &block)
+        end
+      end
+    end
+
+    # As #include_contract, but wraps the contract in a skipped example group.
+    #
+    # @see include_contract.
+    def xinclude_contract(contract_or_name, *arguments, **keywords, &block)
+      xdescribe '(skipped)' do
+        if keywords.empty?
+          include_contract(contract_or_name, *arguments, &block)
+        else
+          include_contract(contract_or_name, *arguments, **keywords, &block)
+        end
+      end
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/contract.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios'
+require 'rspec/sleeping_king_studios/concerns/include_contract'
+
+module RSpec::SleepingKingStudios
+  # A Contract wraps RSpec functionality for sharing and reusability.
+  #
+  # An RSpec::SleepingKingStudios::Contract integrates with the
+  # .include_contract class method to share and reuse RSpec examples and
+  # configuration. The major advantage a Contract object provides over using a
+  # Proc is documentation - tools such as YARD do not gracefully handle bare
+  # lambdas, while the functionality and requirements of a Contract can be
+  # specified using standard patterns, such as documenting the parameters passed
+  # to a contract using the #apply method.
+  #
+  # @example Defining A Contract
+  #   module ExampleContracts
+  #     # This contract asserts that the object has the Enumerable module as an
+  #     # ancestor, and that it responds to the #each method.
+  #     class ShouldBeEnumerableContract
+  #       extend RSpec::SleepingKingStudios::Contract
+  #
+  #       # @!method apply(example_group)
+  #       #   Adds the contract to the example group.
+  #
+  #       contract do
+  #         it 'should be Enumerable' do
+  #           expect(subject).to be_a Enumerable
+  #         end
+  #
+  #         it 'should respond to #each' do
+  #           expect(subject).to respond_to(:each).with(0).arguments
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   RSpec.describe Array do
+  #     ExampleContracts::SHOULD_BE_ENUMERABLE_CONTRACT.apply(self)
+  #   end
+  #
+  #   RSpec.describe Hash do
+  #     extend  RSpec::SleepingKingStudios::Concerns::IncludeContract
+  #     include ExampleContracts
+  #
+  #     include_contract 'should be enumerable'
+  #   end
+  #
+  # @example Defining A Contract With Parameters
+  #   module SerializerContracts
+  #     # This contract asserts that the serialized result has the expected
+  #     # values.
+  #     #
+  #     # First, we pass the contract a series of attribute names. These are
+  #     # used to assert that the serialized attributes match the values on the
+  #     # original object.
+  #     #
+  #     # Second, we pass the contract a set of attribute names and values.
+  #     # These are used to assert that the serialized attributes have the
+  #     # specified values.
+  #     #
+  #     # Finally, we can pass the contract a block, which the contract then
+  #     # executes. Note that the block is executed in the context of our
+  #     # describe block, and thus can take advantage of our memoized
+  #     # #serialized helper method.
+  #     class ShouldSerializeAttributesContract
+  #       extend RSpec::SleepingKingStudios::Contract
+  #
+  #       contract do |*attributes, **values, &block|
+  #         describe '#serialize' do
+  #           let(:serialized) { subject.serialize }
+  #
+  #           it { expect(subject).to respond_to(:serialize).with(0).arguments }
+  #
+  #           attributes.each do |attribute|
+  #             it "should serialize #{attribute}" do
+  #               expect(serialized[attribute]).to be == subject[attribute]
+  #             end
+  #           end
+  #
+  #           values.each do |attribute, value|
+  #             it "should serialize #{attribute}" do
+  #               expect(serialized[attribute]).to be == value
+  #             end
+  #           end
+  #
+  #           instance_exec(&block) if block
+  #         end
+  #       end
+  #     end
+  #
+  #   RSpec.describe CaptainPicard do
+  #     SerializerContracts::ShouldSerializeAttributesContract.apply(
+  #       self,
+  #       :name,
+  #       :rank,
+  #       lights: 4) \
+  #     do
+  #       it 'should serialize the catchphrase' do
+  #         expect(serialized[:catchphrase]).to be == 'Make it so.'
+  #       end
+  #     end
+  #   end
+  #
+  # @see RSpec::SleepingKingStudios::Concerns::IncludeContract.
+  module Contract
+    # Adds the contract to the given example group.
+    #
+    # @param example_group [RSpec::Core::ExampleGroup] The example group to
+    #   which the contract is applied.
+    # @param arguments [Array] Optional arguments to pass to the contract.
+    # @param keywords [Hash] Optional keywords to pass to the contract.
+    #
+    # @yield A block to pass to the contract.
+    #
+    # @see #to_proc
+    def apply(example_group, *arguments, **keywords, &block)
+      concern = RSpec::SleepingKingStudios::Concerns::IncludeContract
+
+      concern.define_contract_method(
+        context:  example_group,
+        contract: self,
+        name:     tools.str.underscore(name).gsub('::', '_')
+      ) do |method_name|
+        if keywords.empty?
+          example_group.send(method_name, *arguments, &block)
+        else
+          example_group.send(method_name, *arguments, **keywords, &block)
+        end
+      end
+    end
+
+    # @overload contract()
+    #   @return [Proc, nil] the contract implementation for the class.
+    #
+    # @overload contract()
+    #   Sets the contract implementation for the class.
+    #
+    #   @yield [*arguments, **keywords, &block] The implementation to
+    #     configure for the class.
+    #
+    #   @yieldparam arguments [Array] Optional arguments to pass to the
+    #     contract.
+    #   @yieldparam keywords [Hash] Optional keywords defined for the
+    #     contract.
+    #   @yieldparam block [Array] A block to pass to the contract.
+    def contract(&block)
+      return @contract = block if block_given?
+
+      @contract
+    end
+
+    # @return [Proc, nil] the contract implementation for the class.
+    def to_proc
+      @contract
+    end
+
+    private
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/matchers/core/alias_method.rb

@@ -1,11 +1,17 @@
 # lib/rspec/sleeping_king_studios/matchers/core/alias_method.rb
 
-require 'rspec/sleeping_king_studios/matchers/core/alias_method_matcher'
+require 'rspec/sleeping_king_studios/matchers/core/have_aliased_method_matcher'
 require 'rspec/sleeping_king_studios/matchers/macros'
 
 module RSpec::SleepingKingStudios::Matchers::Macros
   # @see RSpec::SleepingKingStudios::Matchers::Core::AliasMethodMatcher#matches?
   def alias_method expected
-    RSpec::SleepingKingStudios::Matchers::Core::AliasMethodMatcher.new expected
+    SleepingKingStudios::Tools::CoreTools.deprecate(
+      '#alias_method',
+      message: 'Use #have_aliased_method instead.'
+    )
+
+    RSpec::SleepingKingStudios::Matchers::Core::HaveAliasedMethodMatcher
+      .new expected
   end # method be_boolean
 end # module

data/lib/rspec/sleeping_king_studios/matchers/core/alias_method_matcher.rb

@@ -1,107 +1,22 @@
-# lib/rspec/sleeping_king_studios/matchers/core/alias_method_matcher.rb
+# frozen_string_literal: true
 
-require 'rspec/sleeping_king_studios/matchers/base_matcher'
 require 'rspec/sleeping_king_studios/matchers/core'
+require 'rspec/sleeping_king_studios/matchers/core/have_aliased_method_matcher'
 
 module RSpec::SleepingKingStudios::Matchers::Core
   # Matcher for testing whether an object aliases a specified method using the
   # specified other method name.
   #
   # @since 2.2.0
-  class AliasMethodMatcher < RSpec::SleepingKingStudios::Matchers::BaseMatcher
-    # @param [String, Symbol] expected The name of the method that is expected
-    #   to be aliased.
-    def initialize expected
-      @old_method_name = @expected = expected.intern
-      @errors          = {}
-    end # method initialize
-
-    # Specifies the name of the new method.
-    #
-    # @param [String, Symbol] new_method_name The method name.
-    #
-    # @return [AliasMethodMatcher] self
-    def as new_method_name
-      @new_method_name = new_method_name
-
-      self
-    end # method as
-
-    # (see BaseMatcher#description)
-    def description
-      str = "alias :#{old_method_name}"
-
-      str << " as #{new_method_name.inspect}" if new_method_name
-
-      str
-    end # method description
-
-    # (see BaseMatcher#failure_message)
-    def failure_message
-      message = "expected #{@actual.inspect} to alias :#{old_method_name}"
-
-      message << " as #{new_method_name.inspect}" if new_method_name
-
-      if @errors[:does_not_respond_to_old_method]
-        message << ", but did not respond to :#{old_method_name}"
-
-        return message
-      end # if
-
-      if @errors[:does_not_respond_to_new_method]
-        message << ", but did not respond to :#{new_method_name}"
-
-        return message
-      end # if
-
-      if @errors[:does_not_alias_method]
-        message <<
-          ", but :#{old_method_name} and :#{new_method_name} are different "\
-          "methods"
-
-        return message
-      end # if
-
-      message
-    end # method failure_message
-
+  class AliasMethodMatcher < RSpec::SleepingKingStudios::Matchers::Core::HaveAliasedMethodMatcher
     # (see BaseMatcher#matches?)
-    def matches? actual
-      super
-
-      raise ArgumentError.new('must specify a new method name') if new_method_name.nil?
-
-      responds_to_methods? && aliases_method?
-    end # method matches?
-
-    private
-
-    attr_reader :old_method_name, :new_method_name
-
-    def aliases_method?
-      unless @actual.method(old_method_name) == @actual.method(new_method_name)
-        @errors[:does_not_alias_method] = true
+    def matches?(actual)
+      SleepingKingStudios::Tools::CoreTools.deprecate(
+        'AliasMethodMatcher',
+        message: 'Use a HaveAliasedMethodMatcher instead.'
+      )
 
-        return false
-      end # unless
-
-      true
-    end # method aliases_method?
-
-    def responds_to_methods?
-      unless @actual.respond_to?(old_method_name)
-        @errors[:does_not_respond_to_old_method] = true
-
-        return false
-      end # unless
-
-      unless @actual.respond_to?(new_method_name)
-        @errors[:does_not_respond_to_new_method] = true
-
-        return false
-      end # unless
-
-      true
-    end # method responds_to_methods?
-  end # class
-end # module
+      super
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/matchers/core/delegate_method_matcher.rb

@@ -125,7 +125,14 @@ module RSpec::SleepingKingStudios::Matchers::Core
 
     # (see BaseMatcher#matches?)
     def matches? actual
-      SleepingKingStudios::Tools::CoreTools.deprecate('DelegateMethodMatcher')
+      # :nocov:
+      if RUBY_VERSION < '3.0'
+        SleepingKingStudios::Tools::CoreTools.deprecate('DelegateMethodMatcher')
+      else
+        SleepingKingStudios::Tools::CoreTools
+          .new(deprecation_strategy: 'raise')
+          .deprecate('DelegateMethodMatcher')
+      end
 
       super
 

data/lib/rspec/sleeping_king_studios/matchers/core/have_aliased_method.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/matchers/core/have_aliased_method_matcher'
+require 'rspec/sleeping_king_studios/matchers/macros'
+
+module RSpec::SleepingKingStudios::Matchers::Macros
+  # @see RSpec::SleepingKingStudios::Matchers::Core::HaveAliasedMethodMatcher#matches?
+  def have_aliased_method(original_name)
+    RSpec::SleepingKingStudios::Matchers::Core::HaveAliasedMethodMatcher
+      .new(original_name)
+  end
+end