rspec-sleeping_king_studios 2.7.0 → 2.8.0.rc.0

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/calls/included_examples'
+require 'rspec/sleeping_king_studios/deferred/calls/shared_examples'
+require 'rspec/sleeping_king_studios/deferred/dsl'
+
+module RSpec::SleepingKingStudios::Deferred::Dsl # rubocop:disable Style/Documentation
+  # Methods for defining and including deferred shared example groups.
+  module SharedExamples
+    # Meta-methods for defining deferred examples.
+    module Macros
+      # Registers a method for deferring including a shared example group.
+      #
+      # @param method_name [String, Symbol] the name of the deferred method.
+      #
+      # @return [void]
+      def define_included_examples_method(method_name) # rubocop:disable Metrics/MethodLength
+        define_method(method_name) do |name, *args, **kwargs, &block|
+          deferred_calls <<
+            RSpec::SleepingKingStudios::Deferred::Calls::IncludedExamples.new(
+              method_name,
+              name,
+              *args,
+              **kwargs,
+              &block
+            )
+
+          nil
+        end
+      end
+
+      # Registers a method for deferring a shared example group.
+      #
+      # @param method_name [String, Symbol] the name of the deferred method.
+      #
+      # @return [void]
+      def define_shared_examples_method(method_name) # rubocop:disable Metrics/MethodLength
+        define_method(method_name) do |name, *args, **kwargs, &block|
+          deferred_calls <<
+            RSpec::SleepingKingStudios::Deferred::Calls::SharedExamples.new(
+              method_name,
+              name,
+              *args,
+              **kwargs,
+              &block
+            )
+
+          nil
+        end
+      end
+    end
+
+    extend Macros
+
+    # @!macro [new] define_included_examples_method
+    #   @!method $1(name, *flags, **metadata, &block)
+    #     Defines a deferred included example group using the $1 method.
+    #
+    #     @param name [String, Symbol, Module] the name for the included example
+    #       group.
+    #     @param flags [Array<Symbol>] metadata flags for the included example
+    #       group.
+    #     @param metadata [Hash] metadata for the included example group.
+    #     @param block [Proc] the implementation of the included example group.
+    #
+    #     @return [void]
+
+    # @!macro [new] define_shared_examples_method
+    #   @!method $1(name, *flags, **metadata, &block)
+    #     Defines a deferred shared example group using the $1 method.
+    #
+    #     @param name [String, Symbol, Module] the name for the shared example
+    #       group.
+    #     @param flags [Array<Symbol>] metadata flags for the shared example
+    #       group.
+    #     @param metadata [Hash] metadata for the shared example group.
+    #     @param block [Proc] the implementation of the shared example group.
+    #
+    #     @return [void]
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :finclude_examples
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :fwrap_context
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :fwrap_examples
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :include_context
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :include_examples
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :it_behaves_like
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :it_should_behave_like
+
+    # @!macro define_shared_examples_method
+    define_shared_examples_method :shared_context
+
+    # @!macro define_shared_examples_method
+    define_shared_examples_method :shared_examples
+
+    # @!macro define_shared_examples_method
+    define_shared_examples_method :shared_examples_for
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :wrap_context
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :wrap_examples
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :xinclude_examples
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :xwrap_context
+
+    # @!macro define_included_examples_method
+    define_included_examples_method :xwrap_examples
+  end
+
+  include SharedExamples
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Domain-specific language for defining deferred examples.
+  module Dsl
+    # Callback invoked when the module is extended into another module or class.
+    #
+    # Delegates to child module #extended methods.
+    #
+    # @param other [Module] the other module or class.
+    def self.extended(other)
+      super
+
+      other.extend(RSpec::SleepingKingStudios::Deferred::Dsl::MemoizedHelpers)
+    end
+  end
+end
+
+require 'rspec/sleeping_king_studios/deferred/dsl/examples'
+require 'rspec/sleeping_king_studios/deferred/dsl/example_constants'
+require 'rspec/sleeping_king_studios/deferred/dsl/example_groups'
+require 'rspec/sleeping_king_studios/deferred/dsl/hooks'
+require 'rspec/sleeping_king_studios/deferred/dsl/memoized_helpers'
+require 'rspec/sleeping_king_studios/deferred/dsl/shared_examples'

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred'
+require 'rspec/sleeping_king_studios/deferred/definitions'
+require 'rspec/sleeping_king_studios/deferred/dsl'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Defines a deferred example group for declaring shared tests.
+  module Examples
+    # Class methods for deferred examples.
+    module ClassMethods
+      # @return [RSpec::SleepingKingStudios::Deferred::Examples] the deferred
+      #   example group where this example group was included, if any.
+      attr_accessor :parent_group
+
+      # @return [Array<String, Integer>] the Ruby source filename and line
+      #   number where the deferred example group was defined.
+      attr_accessor :source_location
+
+      # @return [String] the description for the deferred examples. By default,
+      #   formats the last segment of the module name in lowercase words,
+      #   excepting any trailing "Context" or "Examples".
+      def description
+        return @description if @description
+
+        return @description = '(anonymous examples)' if name.nil?
+
+        @description = format_description
+      end
+
+      # @param value [String] the description for the deferred examples.
+      def description=(value)
+        tools.assertions.validate_name(value, as: 'description')
+
+        @description = value.to_s.tr('_', ' ')
+      end
+
+      # @return [Boolean] flag indicating that the included module has deferred
+      #   examples, rather than including another deferred examples module.
+      def deferred_examples?
+        true
+      end
+
+      private
+
+      def format_description
+        name
+          .split('::')
+          .last
+          .gsub(/(Context|Examples?)\z/, '')
+          .then { |str| tools.string_tools.underscore(str) }
+          .tr('_', ' ')
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+    end
+
+    # Callback invoked when the module is included in another module or class.
+    #
+    # Extends the class or module with the Deferred::Definitions
+    # and Deferred::Examples::DSL modules.
+    #
+    # @param other [Module] the other module or class.
+    #
+    # @see RSpec::SleepingKingStudios::Deferred::Definitions.
+    # @see RSpec::SleepingKingStudios::Deferred::Examples::Dsl.
+    def self.included(other)
+      super
+
+      other.extend  ClassMethods
+      other.extend  RSpec::SleepingKingStudios::Deferred::Definitions
+      other.extend  RSpec::SleepingKingStudios::Deferred::Dsl
+      other.include RSpec::SleepingKingStudios::Deferred::Provider
+      other.include RSpec::SleepingKingStudios::Deferred::Consumer
+
+      location = caller_locations(1, 1).first
+
+      other.source_location = [location.path, location.lineno]
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/call'
+require 'rspec/sleeping_king_studios/deferred/definitions'
+require 'rspec/sleeping_king_studios/deferred'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Optional support for deferring unrecognized methods.
+  module Missing
+    # Methods extended into the class when included in a class or module.
+    module ClassMethods
+      include RSpec::SleepingKingStudios::Deferred::Definitions
+
+      private
+
+      def method_missing(...)
+        deferred_calls << RSpec::SleepingKingStudios::Deferred::Call.new(...)
+
+        nil
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        return true if super
+
+        return false if !include_private && super(name, true)
+
+        true
+      end
+    end
+
+    # Callback invoked when the module is included in another module or class.
+    #
+    # Extends the class or module with the ClassMethods module.
+    #
+    # @param other [Module] the other module or class.
+    #
+    # @see RSpec::SleepingKingStudios::Deferred::Missing::ClassMethods.
+    def self.included(other)
+      super
+
+      other.extend(
+        RSpec::SleepingKingStudios::Deferred::Missing::ClassMethods
+      )
+    end
+  end
+end

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbelt'
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'rspec/sleeping_king_studios/deferred'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Methods for registering deferred examples.
+  module Provider
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Exception raised when the requested deferred examples are not defined.
+    class DeferredExamplesNotFoundError < StandardError; end
+
+    # Class methods for registering deferred examples.
+    module ClassMethods
+      # Defines deferred examples in the current context.
+      #
+      # @param description [String] the name of the deferred examples.
+      #
+      # @yield [*arguments, **keywords, &block] the definition for the deferred
+      #   examples. Supports the same DSL as an RSpec::Core::ExampleGroup. If
+      #   the block takes parameters, these can be used to customize the
+      #   behavior of the deferred examples when they are included in an example
+      #   group.
+      # @yieldparam arguments [Array] arguments passed to the deferred examples.
+      # @yieldparam keywords [Hash] keywords passed to the deferred examples.
+      # @yieldparam block [Block] a block passed to the deferred examples.
+      #
+      # @example Defining Deferred Examples
+      #   deferred_examples 'should be a Rocket' do
+      #     it { expect(subject).to be_a Rocket }
+      #   end
+      #
+      # @example Defining Parameterized Examples
+      #   deferred_examples 'should be a Vehicle' do |expected_type:|
+      #     it { expect(subject).to be_a Vehicle }
+      #
+      #     it { expect(subject.tyoe).to be == expected_type }
+      #   end
+      def deferred_examples(description, &block)
+        raise ArgumentError, 'block is required' unless block_given?
+
+        tools.assertions.validate_name(description, as: 'description')
+
+        defined_deferred_examples[description.to_s] = block
+
+        nil
+      end
+      alias deferred_context deferred_examples
+
+      # @private
+      def defined_deferred_examples
+        @defined_deferred_examples ||= {}
+      end
+
+      # Checks if the given deferred example group is defined.
+      #
+      # @param description [String] the name of the deferred examples.
+      #
+      # @return [true, false] true if a deferred example group with the given
+      #   description is defined in the current context; otherwise false.
+      def defined_deferred_examples?(description)
+        ancestors.any? do |ancestor|
+          next false unless ancestor.respond_to?(:defined_deferred_examples)
+
+          ancestor.deferred_definition_exists?(description) ||
+            ancestor.deferred_module_exists?(description)
+        end
+      end
+      alias defined_deferred_context? defined_deferred_examples?
+
+      # @api private
+      def find_deferred_examples(description)
+        tools.assertions.validate_name(description, as: 'description')
+
+        deferred = find_deferred_by_description(description.to_s)
+
+        return deferred if deferred
+
+        message =
+          'deferred examples not found with description ' \
+          "#{description.to_s.inspect}"
+
+        raise DeferredExamplesNotFoundError, message
+      end
+
+      protected
+
+      def deferred_definition_exists?(description)
+        defined_deferred_examples.key?(description)
+      end
+
+      def deferred_module_exists?(description)
+        constants(false)
+          .any? do |const_name|
+            value = const_get(const_name)
+
+            next false unless module_is_deferred_examples?(value)
+
+            return true if matches_description?(description, const_name, value)
+          end
+      end
+
+      def find_deferred_definition(description)
+        defined_deferred_examples.fetch(description, nil)
+      end
+
+      def find_deferred_module(description)
+        constants(false)
+          .each do |const_name|
+            value = const_get(const_name)
+
+            next false unless module_is_deferred_examples?(value)
+
+            return value if matches_description?(description, const_name, value)
+          end
+
+        nil
+      end
+
+      private
+
+      def find_deferred_by_description(description)
+        ancestors.each do |ancestor|
+          next unless ancestor.respond_to?(:defined_deferred_examples)
+
+          deferred =
+            ancestor.find_deferred_definition(description) ||
+            ancestor.find_deferred_module(description)
+
+          return deferred if deferred
+        end
+
+        nil
+      end
+
+      def matches_description?(description, const_name, value)
+        return true if value.description == description
+
+        const_name = const_name.to_s
+
+        return true if const_name == description
+
+        const_name = const_name.gsub(/(Context|Examples?)\z/, '')
+
+        const_name == description
+      end
+
+      def module_is_deferred_examples?(value)
+        return false unless value.is_a?(Module)
+
+        return false unless value.respond_to?(:deferred_examples?)
+
+        value.deferred_examples?
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+    end
+  end
+end

data/lib/rspec/sleeping_king_studios/deferred.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios'
+
+module RSpec::SleepingKingStudios
+  # Namespace for deferred example functionality.
+  module Deferred
+    autoload :Call,         'rspec/sleeping_king_studios/deferred/call'
+    autoload :Calls,        'rspec/sleeping_king_studios/deferred/calls'
+    autoload :Consumer,     'rspec/sleeping_king_studios/deferred/consumer'
+    autoload :Definitions,  'rspec/sleeping_king_studios/deferred/definitions'
+    autoload :Dependencies, 'rspec/sleeping_king_studios/deferred/dependencies'
+    autoload :Dsl,          'rspec/sleeping_king_studios/deferred/dsl'
+    autoload :Examples,     'rspec/sleeping_king_studios/deferred/examples'
+    autoload :Missing,      'rspec/sleeping_king_studios/deferred/missing'
+    autoload :Provider,     'rspec/sleeping_king_studios/deferred/provider'
+
+    class << self
+      # Returns the full path of an example, including deferred example groups.
+      #
+      # By default, returns the path in a single-line format similar to an
+      # example group description. Deferred example groups are parenthesized.
+      # When the :source_locations flag is set to true, it instead returns each
+      # example group or deferred group on its own line, along with the source
+      # location for that group.
+      #
+      # @param example [RSpec::Core::Example] the example to examine.
+      # @param source_locations [true, false] if true, returns the path in a
+      #   multi-line format including the source location for each group.
+      #
+      # @return [String] the generated example path.
+      #
+      # @example Displaying the full path of failing specs:
+      #   config.after(:example) do |example|
+      #     next unless ENV['REFLECT_ON_FAILURE']
+      #     next unless example.metadata[:last_run_status] == 'failed'
+      #
+      #     STDERR.puts "\nFailing spec at:"
+      #
+      #     path =
+      #       RSpec::SleepingKingStudios::Deferred
+      #         .reflect(example, source_locations: true)
+      #     path =
+      #       SleepingKingStudios::Tools::Toolbelt
+      #         .instance
+      #         .string_tools
+      #         .indent(path)
+      #
+      #     STDERR.puts path
+      #   end
+      def reflect(example, source_locations: false)
+        return short_description_for(example) unless source_locations
+
+        each_ancestor_group_for(example)
+          .reverse_each
+          .reduce([]) do |lines, group|
+            lines << format_full_description(group)
+          end
+          .join("\n")
+      end
+
+      private
+
+      def constant_or_method?(description)
+        description.start_with?('::') ||
+          description.start_with?('#') ||
+          description.start_with?('.')
+      end
+
+      def deferred_group?(example_group)
+        return false unless example_group.is_a?(Module)
+        return false if example_group.is_a?(Class)
+
+        example_group < RSpec::SleepingKingStudios::Deferred::Consumer
+      end
+
+      def each_ancestor_group_for(example, &) # rubocop:disable Metrics/MethodLength
+        return enum_for(:each_ancestor_group_for, example) unless block_given?
+
+        each_parent_group_for(example.metadata[:deferred_example_group], &)
+
+        example
+          .example_group
+          .ancestors
+          .select do |ancestor|
+            ancestor.is_a?(Class) && ancestor < RSpec::Core::ExampleGroup
+          end # rubocop:disable Style/MultilineBlockChain
+          .each do |ancestor|
+            yield ancestor
+
+            each_parent_group_for(ancestor.metadata[:deferred_example_group], &)
+          end
+      end
+
+      def each_parent_group_for(maybe_deferred, &)
+        unless block_given?
+          return enum_for(:each_parent_group_for, maybe_deferred)
+        end
+
+        loop do
+          break unless deferred_group?(maybe_deferred)
+
+          yield maybe_deferred
+
+          maybe_deferred = maybe_deferred.parent_group
+        end
+      end
+
+      def format_description(group)
+        return group.description unless deferred_group?(group)
+
+        "(#{group.description})"
+      end
+
+      def format_full_description(group)
+        "#{format_description(group)} at #{format_source_location(group)}"
+      end
+
+      def format_source_location(group)
+        source_location =
+          if group < RSpec::Core::ExampleGroup
+            group.metadata[:block].source_location
+          else
+            group.source_location
+          end
+
+        source_location.join(':')
+      end
+
+      def short_description_for(example)
+        each_ancestor_group_for(example)
+          .reverse_each
+          .reduce('') do |description, group|
+            description += ' ' unless constant_or_method?(group.description)
+
+            description + format_description(group)
+          end
+          .strip
+      end
+    end
+  end
+end