rspec-sleeping_king_studios 2.7.0 → 2.8.0.rc.0

data/lib/rspec/sleeping_king_studios/configuration.rb

@@ -1,4 +1,4 @@
-# lib/rspec/sleeping_king_studios/configuration.rb
+# frozen_string_literal: true
 
 require 'rspec/sleeping_king_studios'
 
@@ -19,7 +19,7 @@ module RSpec::SleepingKingStudios
       # @return [Symbol] The current missing message handler.
       def handle_missing_failure_message_with
         @handle_missing_failure_message_with ||= :pending
-      end # method handle_missing_failure_message_with
+      end
 
       # Sets the handler for missing failure messages when using the matcher
       # examples.
@@ -29,17 +29,19 @@ module RSpec::SleepingKingStudios
       #
       # @raise ArgumentError If the handler is not one of the recognized
       #   values.
-      def handle_missing_failure_message_with= value
+      def handle_missing_failure_message_with=(value)
         value = value.to_s.intern
 
         unless MISSING_FAILURE_MESSAGE_HANDLERS.include?(value)
-          message = "unrecognized handler value -- must be in #{MISSING_FAILURE_MESSAGE_HANDLERS.join ', '}"
+          message =
+            'unrecognized handler value -- must be in ' \
+            "#{MISSING_FAILURE_MESSAGE_HANDLERS.join ', '}"
 
-          raise ArgumentError.new message
-        end # unless
+          raise ArgumentError, message
+        end
 
         @handle_missing_failure_message_with = value
-      end # method handle_missing_failure_message_with=
+      end
 
       # Gets the option for matching failure messages to strings, and sets to
       # :substring if unset.
@@ -47,7 +49,7 @@ module RSpec::SleepingKingStudios
       # @return [Symbol] The current failure message string matching option.
       def match_string_failure_message_as
         @match_string_failure_message_as ||= :substring
-      end # method match_string_failure_message_as
+      end
 
       # Sets the option for matching failure messages to strings.
       #
@@ -56,19 +58,21 @@ module RSpec::SleepingKingStudios
       #
       # @raise ArgumentError If the handler is not one of the recognized
       #   values.
-      def match_string_failure_message_as= value
+      def match_string_failure_message_as=(value)
         value = value.to_s.intern
         value = :substring if value == :partial
 
         unless STRING_FAILURE_MESSAGE_MATCH_OPTIONS.include?(value)
-          message = "unrecognized value -- must be in #{STRING_FAILURE_MESSAGE_MATCH_OPTIONS.join ', '}"
+          message =
+            'unrecognized value -- must be in ' \
+            "#{STRING_FAILURE_MESSAGE_MATCH_OPTIONS.join ', '}"
 
-          raise ArgumentError.new message
-        end # unless
+          raise ArgumentError, message
+        end
 
         @match_string_failure_message_as = value
-      end # method match_string_failure_message_as=
-    end # class
+      end
+    end
 
     # Configuration options for RSpec::SleepingKingStudios::Matchers.
     class Matchers
@@ -77,12 +81,14 @@ module RSpec::SleepingKingStudios
       #
       # @return [Boolean] True if the empty include matchers are permitted,
       #   otherwise false.
+      #
+      # @deprecated [3.0] Will be removed in version 3.0.
       def allow_empty_include_matchers
         value = @allow_empty_include_matchers
 
-        value.nil? ? true : value
-      end # method allow_empty_include_matchers
-      alias_method :allow_empty_include_matchers?, :allow_empty_include_matchers
+        value.nil? ? true : value # rubocop:disable Style/RedundantCondition
+      end
+      alias allow_empty_include_matchers? allow_empty_include_matchers
 
       # Sets whether the #include matcher can be instantiated without an
       # expectation object or block. If this option is set to false, an
@@ -97,9 +103,11 @@ module RSpec::SleepingKingStudios
       #
       # @return [Boolean] True if the empty include matchers are permitted,
       #   otherwise false.
-      def allow_empty_include_matchers= value
+      #
+      # @deprecated [3.0] Will be removed in version 3.0.
+      def allow_empty_include_matchers=(value)
         @allow_empty_include_matchers = !!value
-      end # method allow_empty_include_matchers
+      end
 
       # Checks whether predicates are matched "strictly", meaning that they must
       # return either true or false.
@@ -108,47 +116,47 @@ module RSpec::SleepingKingStudios
       #   false.
       def strict_predicate_matching
         @strict_predicate_matching ||= false
-      end # method strict_predicate_matching
-      alias_method :strict_predicate_matching?, :strict_predicate_matching
+      end
+      alias strict_predicate_matching? strict_predicate_matching
 
       # Sets whether predicates are matched "strictly", meaning that they must
       # return either true or false.
       #
       # @param [Boolean] value The desired value. Is coerced to true or false.
-      def strict_predicate_matching= value
+      def strict_predicate_matching=(value)
         @strict_predicate_matching = !!value
-      end # method strict_predicate_matching
-    end # class
+      end
+    end
 
     # Get or set the configuration options for
     # RSpec::SleepingKingStudios::Examples.
-    def examples &block
+    def examples(&)
       @examples ||= RSpec::SleepingKingStudios::Configuration::Examples.new
 
-      @examples.instance_eval(&block) if block_given?
+      @examples.instance_eval(&) if block_given?
 
       @examples
-    end # method examples
+    end
 
     # Get or set the configuration options for
     # RSpec::SleepingKingStudios::Matchers.
-    def matchers &block
+    def matchers(&)
       @matchers ||= RSpec::SleepingKingStudios::Configuration::Matchers.new
 
-      @matchers.instance_eval(&block) if block_given?
+      @matchers.instance_eval(&) if block_given?
 
       @matchers
-    end # method matchers
-  end # class
-end # module
+    end
+  end
+end
 
-class RSpec::Core::Configuration
+class RSpec::Core::Configuration # rubocop:disable Style/Documentation
   # Get or set the configuration options for RSpec::SleepingKingStudios.
-  def sleeping_king_studios &block
+  def sleeping_king_studios(&)
     @sleeping_king_studios ||= RSpec::SleepingKingStudios::Configuration.new
 
-    @sleeping_king_studios.instance_eval(&block) if block_given?
+    @sleeping_king_studios.instance_eval(&) if block_given?
 
     @sleeping_king_studios
-  end # method sleeping_king_studios
-end # class
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred/call.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbelt'
+
+require 'rspec/sleeping_king_studios/deferred'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Value object representing a deferred call to a method.
+  class Call
+    # @param method_name [String, Symbol] the name of the method to call.
+    # @param arguments [Array] the arguments to pass to the method.
+    # @param keywords [Hash] the keywords to pass to the method.
+    # @param block [Proc] the block to pass to the method.
+    def initialize(method_name, *arguments, **keywords, &block)
+      @method_name = method_name
+      @arguments   = arguments
+      @keywords    = keywords
+      @block       = block
+
+      validate_parameters!
+    end
+
+    # @return [Array] the arguments to pass to the method.
+    attr_reader :arguments
+
+    # @return [Proc] the block to pass to the method.
+    attr_reader :block
+
+    # @return [Hash] the keywords to pass to the method.
+    attr_reader :keywords
+
+    # @return [String, Symbol] the name of the method to call.
+    attr_reader :method_name
+
+    # Compares the other object with the deferred call.
+    #
+    # Returns true if and only if:
+    # - The other object is an instance of Deferred::Call.
+    # - The other object's method name and type match the deferred call.
+    # - The other object's arguments, keywords, and block all match the deferred
+    #   call.
+    #
+    # @param other [Object] the object to compare.
+    #
+    # @return [Boolean] true if the other matches the deferred call; otherwise
+    #   false.
+    def ==(other)
+      other.class == self.class &&
+        other.method_name == method_name &&
+        other.arguments == arguments &&
+        other.keywords == keywords &&
+        other.block == block
+    end
+
+    # Invokes the deferred method call on the receiver.
+    #
+    # @param receiver [Object] the receiver for the method call.
+    #
+    # @return [Object] the returned value of the method call.
+    def call(receiver)
+      receiver.send(method_name, *arguments, **keywords, &block)
+    end
+
+    private
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_parameters!
+      tools.assertions.validate_name(method_name, as: 'method_name')
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred/calls/example.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/call'
+require 'rspec/sleeping_king_studios/deferred/calls'
+
+module RSpec::SleepingKingStudios::Deferred::Calls
+  # Value object representing a deferred RSpec example.
+  class Example < RSpec::SleepingKingStudios::Deferred::Call
+    # @param method_name [String, Symbol] the name of the method to call.
+    # @param arguments [Array] the arguments to pass to the method.
+    # @param keywords [Hash] the keywords to pass to the method.
+    # @param deferred_example_group [Deferred::Examples] the deferred example
+    #   group defining the deferred call.
+    # @param block [Proc] the block to pass to the method.
+    def initialize(
+      method_name,
+      *arguments,
+      deferred_example_group: nil,
+      **keywords,
+      &block
+    )
+      super(method_name, *arguments, **keywords, &block)
+
+      @deferred_example_group = deferred_example_group
+    end
+
+    # @return [Deferred::Examples] the deferred example group defining the
+    #   deferred call.
+    attr_reader :deferred_example_group
+
+    # (see RSpec::SleepingKingStudios::Deferred::Call#call)
+    def call(receiver)
+      example = super
+
+      # Store a reference to the deferred group when adding to an actual example
+      # group.
+      example.metadata[:deferred_example_group] = @deferred_example_group
+
+      example
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred/calls/example_group.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/call'
+require 'rspec/sleeping_king_studios/deferred/calls'
+
+module RSpec::SleepingKingStudios::Deferred::Calls
+  # Value object representing a deferred RSpec example group.
+  class ExampleGroup < RSpec::SleepingKingStudios::Deferred::Call
+    # @param method_name [String, Symbol] the name of the method to call.
+    # @param arguments [Array] the arguments to pass to the method.
+    # @param keywords [Hash] the keywords to pass to the method.
+    # @param deferred_example_group [Deferred::Examples] the deferred example
+    #   group defining the deferred call.
+    # @param block [Proc] the block to pass to the method.
+    def initialize(
+      method_name,
+      *arguments,
+      deferred_example_group: nil,
+      **keywords,
+      &block
+    )
+      super(method_name, *arguments, **keywords, &block)
+
+      @deferred_example_group = deferred_example_group
+    end
+
+    # @return [Deferred::Examples] the deferred example group defining the
+    #   deferred call.
+    attr_reader :deferred_example_group
+
+    # (see RSpec::SleepingKingStudios::Deferred::Call#call)
+    def call(receiver)
+      example_group = super
+
+      # Store a reference to the deferred group when adding to an actual example
+      # group.
+      example_group.metadata[:deferred_example_group] = @deferred_example_group
+
+      example_group
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred/calls/hook.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require 'rspec/sleeping_king_studios/deferred/call'
+require 'rspec/sleeping_king_studios/deferred/calls'
+
+module RSpec::SleepingKingStudios::Deferred::Calls
+  # Value object representing a deferred RSpec example.
+  class Hook < RSpec::SleepingKingStudios::Deferred::Call
+    VALID_METHOD_NAMES = Set.new(
+      %i[after append_after around before prepend_before]
+    ).freeze
+    private_constant :VALID_METHOD_NAMES
+
+    VALID_SCOPES = Set.new(%i[context each example]).freeze
+    private_constant :VALID_SCOPES
+
+    # @return [Symbol] the scope of the hook.
+    def scope
+      arguments.first&.intern
+    end
+
+    private
+
+    def validate_block!
+      return if block
+
+      raise ArgumentError, 'no block given'
+    end
+
+    def validate_method_name!
+      return if VALID_METHOD_NAMES.include?(method_name)
+
+      raise ArgumentError, "invalid hook method #{method_name.inspect}"
+    end
+
+    def validate_parameters!
+      super
+
+      validate_block!
+      validate_method_name!
+      validate_scope!
+    end
+
+    def validate_scope! # rubocop:disable Metrics/MethodLength
+      tools.assertions.validate_name(arguments.first, as: :scope)
+
+      if method_name == :around
+        return if scope == :each || scope == :example # rubocop:disable Style/MultipleComparison
+
+        raise ArgumentError, 'scope for an :around hook must be :example'
+      else
+        return if VALID_SCOPES.include?(scope)
+
+        message =
+          "scope for a #{method_name.inspect} hook must be :context, :each, " \
+          'or :example'
+
+        raise ArgumentError, message
+      end
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred/calls/included_examples.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/call'
+require 'rspec/sleeping_king_studios/deferred/calls'
+
+module RSpec::SleepingKingStudios::Deferred::Calls
+  # Value object representing a deferred RSpec included example group.
+  class IncludedExamples < RSpec::SleepingKingStudios::Deferred::Call
+    # @return [String] the description for the shared example group.
+    def name
+      arguments.first
+    end
+
+    private
+
+    def validate_name!
+      return if name.is_a?(Module)
+
+      return if (name.is_a?(String) || name.is_a?(Symbol)) && !name.to_s.empty?
+
+      message =
+        'shared example group name must be a non-empty String, Symbol, or ' \
+        'Module'
+
+      raise ArgumentError, message
+    end
+
+    def validate_parameters!
+      super
+
+      validate_name!
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred/calls/shared_examples.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/call'
+require 'rspec/sleeping_king_studios/deferred/calls'
+
+module RSpec::SleepingKingStudios::Deferred::Calls
+  # Value object representing a deferred RSpec shared example group.
+  class SharedExamples < RSpec::SleepingKingStudios::Deferred::Call
+    # @return [String] the description for the shared example group.
+    def name
+      arguments.first
+    end
+
+    private
+
+    def validate_block!
+      return if block
+
+      raise ArgumentError, 'no block given'
+    end
+
+    def validate_name!
+      return if name.is_a?(Module)
+
+      return if (name.is_a?(String) || name.is_a?(Symbol)) && !name.to_s.empty?
+
+      message =
+        'shared example group name must be a non-empty String, Symbol, or ' \
+        'Module'
+
+      raise ArgumentError, message
+    end
+
+    def validate_parameters!
+      super
+
+      validate_name!
+      validate_block!
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred/calls.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Namespace for deferred call implementations.
+  module Calls
+    autoload :Example,
+      'rspec/sleeping_king_studios/deferred/calls/example'
+    autoload :ExampleGroup,
+      'rspec/sleeping_king_studios/deferred/calls/example_group'
+    autoload :Hook,
+      'rspec/sleeping_king_studios/deferred/calls/hook'
+    autoload :IncludedExamples,
+      'rspec/sleeping_king_studios/deferred/calls/included_examples'
+    autoload :SharedExamples,
+      'rspec/sleeping_king_studios/deferred/calls/shared_examples'
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred/consumer.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'rspec/sleeping_king_studios/deferred'
+require 'rspec/sleeping_king_studios/deferred/examples'
+require 'rspec/sleeping_king_studios/deferred/provider'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Methods for including deferred examples.
+  module Consumer
+    extend  SleepingKingStudios::Tools::Toolbox::Mixin
+    include RSpec::SleepingKingStudios::Deferred::Provider
+
+    # Class methods for registering deferred examples.
+    module ClassMethods
+      # @overload finclude_deferred(description, *arguments, **keywords, &block)
+      #   Includes the deferred examples inside a focused example group.
+      #
+      #   @param description [String] the name of the deferred examples.
+      #   @param arguments [Array] arguments passed to the deferred examples.
+      #   @param keywords [Hash] keywords passed to the deferred examples.
+      #   @param block [Block] a block passed to the deferred examples.
+      def finclude_deferred(description, ...)
+        fdescribe '(focused)' do
+          include_deferred(description, ...)
+        end
+      end
+
+      # @overload fwrap_deferred(description, *arguments, **keywords, &block)
+      #   Includes the deferred examples inside a focused example group.
+      #
+      #   Unlike #include_deferred, a block parameter will be included in the
+      #   created example group, not passed to the deferred examples. To wrap
+      #   deferred examples that require a block, create the example group
+      #   separately and call #include_deferred.
+      #
+      #   @param description [String] the name of the deferred examples.
+      #   @param arguments [Array] arguments passed to the deferred examples.
+      #   @param keywords [Hash] keywords passed to the deferred examples.
+      #   @param block [Block] additional examples to be evaluated inside the
+      #     example group.
+      def fwrap_deferred(description, *args, **kwargs, &block)
+        fdescribe "(focused) #{description}" do
+          include_deferred(description, *args, **kwargs)
+
+          instance_exec(&block) if block_given?
+        end
+      end
+
+      # @overload include_deferred(description, *arguments, **keywords, &block)
+      #   Includes the deferred examples with the given definition.
+      #
+      #   @param description [String] the name of the deferred examples.
+      #   @param arguments [Array] arguments passed to the deferred examples.
+      #   @param keywords [Hash] keywords passed to the deferred examples.
+      #   @param block [Block] a block passed to the deferred examples.
+      def include_deferred(description, ...)
+        deferred = find_deferred_examples(description)
+
+        deferred =
+          if deferred.is_a?(Proc)
+            define_deferred_module(deferred, description, ...)
+          else
+            wrap_deferred_module(deferred)
+          end
+
+        deferred.parent_group = self
+
+        include deferred
+      end
+
+      # @overload wrap_deferred(description, *arguments, **keywords, &block)
+      #   Includes the deferred examples inside an example group.
+      #
+      #   Unlike #include_deferred, a block parameter will be included in the
+      #   created example group, not passed to the deferred examples. To wrap
+      #   deferred examples that require a block, create the example group
+      #   separately and call #include_deferred.
+      #
+      #   @param description [String] the name of the deferred examples.
+      #   @param arguments [Array] arguments passed to the deferred examples.
+      #   @param keywords [Hash] keywords passed to the deferred examples.
+      #   @param block [Block] additional examples to be evaluated inside the
+      #     example group.
+      def wrap_deferred(description, *args, **kwargs, &block)
+        describe description do
+          include_deferred(description, *args, **kwargs)
+
+          instance_exec(&block) if block_given?
+        end
+      end
+
+      # @overload xinclude_deferred(description, *arguments, **keywords, &block)
+      #   Includes the deferred examples inside a skipped example group.
+      #
+      #   @param description [String] the name of the deferred examples.
+      #   @param arguments [Array] arguments passed to the deferred examples.
+      #   @param keywords [Hash] keywords passed to the deferred examples.
+      #   @param block [Block] a block passed to the deferred examples.
+      def xinclude_deferred(description, ...)
+        xdescribe '(skipped)' do
+          include_deferred(description, ...)
+        end
+      end
+
+      # @overload xwrap_deferred(description, *arguments, **keywords, &block)
+      #   Includes the deferred examples inside a skipped example group.
+      #
+      #   Unlike #include_deferred, a block parameter will be included in the
+      #   created example group, not passed to the deferred examples. To wrap
+      #   deferred examples that require a block, create the example group
+      #   separately and call #include_deferred.
+      #
+      #   @param description [String] the name of the deferred examples.
+      #   @param arguments [Array] arguments passed to the deferred examples.
+      #   @param keywords [Hash] keywords passed to the deferred examples.
+      #   @param block [Block] additional examples to be evaluated inside the
+      #     example group.
+      def xwrap_deferred(description, *args, **kwargs, &block)
+        xdescribe "(skipped) #{description}" do
+          include_deferred(description, *args, **kwargs)
+
+          instance_exec(&block) if block_given?
+        end
+      end
+
+      private
+
+      def define_deferred_module(implementation, description, ...) # rubocop:disable Metrics/MethodLength
+        Module.new do
+          extend  RSpec::SleepingKingStudios::Deferred::Examples::ClassMethods
+          include RSpec::SleepingKingStudios::Deferred::Examples
+
+          self.description     = description
+          self.source_location = implementation.source_location
+
+          define_singleton_method(
+            :deferred_examples_implementation,
+            &implementation
+          )
+
+          deferred_examples_implementation(...)
+        end
+      end
+
+      def wrap_deferred_module(examples)
+        Module.new do
+          extend  RSpec::SleepingKingStudios::Deferred::Examples::ClassMethods
+          include RSpec::SleepingKingStudios::Deferred::Examples
+          include examples
+
+          self.description     = examples.description
+          self.source_location = examples.source_location
+        end
+      end
+    end
+  end
+end