rspec-sleeping_king_studios 2.7.0 → 2.8.0.rc.0

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Class methods for defining a registry of deferred calls.
+  module Definitions
+    # Invokes the deferred examples on the given example group.
+    #
+    # @param example_group [RSpec::Core::ExampleGroup] the example group.
+    #
+    # @return [void]
+    def call(example_group)
+      deferred_calls.each do |deferred|
+        deferred.call(example_group)
+      end
+    end
+
+    # @private
+    def deferred_calls
+      @deferred_calls ||= []
+    end
+
+    # Callback invoked when the module is included in another module or class.
+    #
+    # Calls the deferred calls with the other module as the receiver if the
+    # module is an RSpec::Core::ExampleGroup.
+    #
+    # @param other [Module] the other module or class.
+    def included(other)
+      super
+
+      return unless other < RSpec::Core::ExampleGroup
+
+      ancestors.reverse_each do |ancestor|
+        next unless ancestor.singleton_class.method_defined?(:deferred_calls)
+
+        ancestor.call(other)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred'
+
+module RSpec::SleepingKingStudios::Deferred
+  # Mixin for declaring dependent methods for deferred example groups.
+  #
+  # Each dependent method is expected to have a definition, either as a direct
+  # method definition (using the `def` keyword or `define_method`), or via  a
+  # memoized helper (such as `let`).
+  #
+  # When the deferred examples are included in an example group and that example
+  # group is run, a before(:context) hook will check for all of the declared
+  # dependencies of that example group. If any of the expected dependencies are
+  # not defined, the hook will raise an exception listing the missing methods,
+  # the deferred examples that expect that method, and the description provided.
+  #
+  # @example
+  #   module RocketExamples
+  #     include RSpec::SleepingKingStudios::Deferred::Provider
+  #
+  #     deferred_examples 'should launch the rocket' do
+  #       include RSpec::SleepingKingStudios::Deferred::Dependencies
+  #
+  #       depends_on :rocket,
+  #         'an instance of Rocket where #launched? returns false'
+  #
+  #       describe '#launch' do
+  #         it 'should launch the rocket' do
+  #           expect { rocket.launch }.to change(rocket, :launched?).to be true
+  #         end
+  #       end
+  #     end
+  #   end
+  module Dependencies
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Exception raised when declared dependencies are not defined.
+    class MissingDependenciesError < StandardError; end
+
+    # Class methods for declaring dependent methods.
+    module ClassMethods
+      # @private
+      def call(example_group)
+        super
+
+        metadata_key = :deferred_dependencies_check_added
+
+        return if example_group.metadata[metadata_key]
+
+        example_group.metadata[metadata_key] = true
+
+        example_group.before(:context) do
+          RSpec::SleepingKingStudios::Deferred::Dependencies
+            .check_dependencies_for(self)
+        end
+      end
+
+      # @private
+      def dependent_methods
+        @dependent_methods ||= []
+      end
+
+      # Declares an external method dependency.
+      #
+      # @param method_name [String, Symbol] the name of the expected method.
+      # @param description [String] a short description of the method.
+      #
+      # @return [void]
+      def depends_on(method_name, description = nil)
+        dependent_methods << {
+          deferred_group: self,
+          description:,
+          method_name:    method_name.to_s.sub(/\A#/, '').intern
+        }
+
+        nil
+      end
+    end
+
+    class << self
+      # Checks for missing dependent methods for the given example.
+      #
+      # @param example [RSpec::Core::Example] the example to check.
+      #
+      # @raise [MissingDependenciesError] if there are any dependencies missing
+      #   for the given example.
+      def check_dependencies_for(example)
+        missing = missing_dependencies_for(example)
+
+        return if missing.empty?
+
+        raise MissingDependenciesError, generate_missing_message(missing)
+      end
+
+      private
+
+      def all_dependencies_for(example)
+        example
+          .class
+          .ancestors
+          .select { |ancestor| ancestor.respond_to?(:dependent_methods) }
+          .flat_map(&:dependent_methods)
+      end
+
+      def generate_missing_message(missing) # rubocop:disable Metrics/MethodLength
+        [
+          'Unable to run specs with deferred example groups because the ' \
+          'following methods are not defined in the examples:',
+          *missing
+            .group_by { |item| item[:deferred_group] }
+            .map do |deferred_group, dependencies|
+              message_for_group(deferred_group, dependencies)
+            end,
+          'Please define the missing methods or :let helpers.'
+        ]
+          .join("\n\n")
+      end
+
+      def message_for_group(deferred_group, dependencies)
+        message = "Missing methods for #{deferred_group.description.inspect}:"
+
+        dependencies.each do |hsh|
+          message += "\n  ##{hsh[:method_name]}"
+          message += ": #{hsh[:description]}" if hsh[:description]
+        end
+
+        message
+      end
+
+      def missing_dependencies_for(example)
+        all_dependencies_for(example).reject do |hsh|
+          example.respond_to?(hsh[:method_name])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/call'
+require 'rspec/sleeping_king_studios/deferred/dsl'
+
+module RSpec::SleepingKingStudios::Deferred::Dsl # rubocop:disable Style/Documentation
+  # Domain-specific language for defining deferred example constants.
+  #
+  # @see RSpec::SleepingKingStudios::Concerns::ExampleConstants.
+  module ExampleConstants
+    # Defines a deferred temporary class scoped to the current example.
+    #
+    # @param class_name [String] the qualified name of the class.
+    # @param base_class [Class, String] the base class or name of the base
+    #   class. This can be the name of another example class, as long as the
+    #   base class is defined earlier in the example group or in a parent
+    #   example group.
+    #
+    # @yield definitions for the temporary class.  This block is evaluated in
+    #     the context of the example, meaning that methods or memoized helpers
+    #     can be referenced.
+    # @yieldparam klass [Class] the temporary class.
+    def example_class(class_name, base_class = nil, &)
+      deferred_calls <<
+        RSpec::SleepingKingStudios::Deferred::Call.new(
+          :example_class,
+          class_name,
+          base_class,
+          &
+        )
+
+      nil
+    end
+
+    # @overload example_constant(constant_name, constant_value)
+    #   Defines a deferred temporary constant scoped to the current example.
+    #
+    #   @param constant_name [String] the qualified name of the constant.
+    #   @param constant_value [Object] the value of the constant.
+    #
+    # @overload example_constant(constant_name, &block)
+    #   Defines a deferred temporary constant scoped to the current example.
+    #
+    #   @param constant_name [String] the qualified name of the constant.
+    #
+    #   @yield generates the constant value. This block is evaluated in the
+    #     context of the example, meaning that methods or memoized helpers can
+    #     be referenced.
+    #   @yieldreturn the value of the constant.
+    #
+    # @deprecated 2.8.0 with force: true parameter.
+    def example_constant(
+      qualified_name,
+      constant_value = nil,
+      force: false,
+      &block
+    )
+      deferred_calls <<
+        RSpec::SleepingKingStudios::Deferred::Call.new(
+          :example_constant,
+          qualified_name,
+          *(constant_value.nil? ? [] : [constant_value]),
+          force:,
+          &block
+        )
+
+      nil
+    end
+  end
+
+  include ExampleConstants
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/calls/example_group'
+require 'rspec/sleeping_king_studios/deferred/dsl'
+
+module RSpec::SleepingKingStudios::Deferred::Dsl # rubocop:disable Style/Documentation
+  # Methods for defining deferred example groups.
+  module ExampleGroups
+    # Meta-methods for defining deferred example groups.
+    module Macros
+      # Registers a method for deferring an example group.
+      #
+      # @param method_name [String, Symbol] the name of the deferred method.
+      #
+      # @return [void]
+      def define_example_group_method(method_name) # rubocop:disable Metrics/MethodLength
+        define_method(method_name) do |*args, **kwargs, &block|
+          deferred_calls <<
+            RSpec::SleepingKingStudios::Deferred::Calls::ExampleGroup.new(
+              method_name,
+              *args,
+              **kwargs,
+              deferred_example_group: self,
+              &block
+            )
+
+          nil
+        end
+      end
+    end
+
+    extend Macros
+
+    # @!macro [new] define_example_group_method
+    #   @!method $1(doc_string = nil, *flags, **metadata, &block)
+    #     Defines a deferred example group using the $1 method.
+    #
+    #     @param doc_string [String] the example group's doc string.
+    #     @param flags [Array<Symbol>] metadata flags for the example group.
+    #       Will be transformed into metadata entries with true values.
+    #     @param metadata [Hash] metadata for the example group.
+    #     @param block [Proc] the implementation of the example group.
+    #
+    #     @return [void]
+
+    # @!macro define_example_group_method
+    define_example_group_method :context
+
+    # @!macro define_example_group_method
+    define_example_group_method :describe
+
+    # @!macro define_example_group_method
+    define_example_group_method :example_group
+
+    # @!macro define_example_group_method
+    define_example_group_method :fcontext
+
+    # @!macro define_example_group_method
+    define_example_group_method :fdescribe
+
+    # @!macro define_example_group_method
+    define_example_group_method :xcontext
+
+    # @!macro define_example_group_method
+    define_example_group_method :xdescribe
+  end
+
+  include ExampleGroups
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/calls/example'
+require 'rspec/sleeping_king_studios/deferred/dsl'
+
+module RSpec::SleepingKingStudios::Deferred::Dsl # rubocop:disable Style/Documentation
+  # Methods for defining deferred examples.
+  module Examples
+    # Meta-methods for defining deferred examples.
+    module Macros
+      # Registers a method for deferring an example.
+      #
+      # @param method_name [String, Symbol] the name of the deferred method.
+      #
+      # @return [void]
+      def define_example_method(method_name) # rubocop:disable Metrics/MethodLength
+        define_method(method_name) do |*args, **kwargs, &block|
+          deferred_calls <<
+            RSpec::SleepingKingStudios::Deferred::Calls::Example.new(
+              method_name,
+              *args,
+              **kwargs,
+              deferred_example_group: self,
+              &block
+            )
+
+          nil
+        end
+      end
+    end
+
+    extend Macros
+
+    # @!macro [new] define_example_method
+    #   @!method $1(doc_string = nil, *flags, **metadata, &block)
+    #     Defines a deferred example using the $1 method.
+    #
+    #     @param doc_string [String] the example's doc string.
+    #     @param flags [Array<Symbol>] metadata flags for the example. Will be
+    #       transformed into metadata entries with true values.
+    #     @param metadata [Hash] metadata for the example.
+    #     @param block [Proc] the implementation of the example.
+    #
+    #     @return [void]
+
+    # @!macro define_example_method
+    define_example_method :example
+
+    # @!macro define_example_method
+    define_example_method :fexample
+
+    # @!macro define_example_method
+    define_example_method :fit
+
+    # @!macro define_example_method
+    define_example_method :focus
+
+    # @!macro define_example_method
+    define_example_method :fspecify
+
+    # @!macro define_example_method
+    define_example_method :it
+
+    # @!macro define_example_method
+    define_example_method :pending
+
+    # @!macro define_example_method
+    define_example_method :skip
+
+    # @!macro define_example_method
+    define_example_method :specify
+
+    # @!macro define_example_method
+    define_example_method :xexample
+
+    # @!macro define_example_method
+    define_example_method :xit
+
+    # @!macro define_example_method
+    define_example_method :xspecify
+  end
+
+  include Examples
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/calls/hook'
+require 'rspec/sleeping_king_studios/deferred/dsl'
+
+module RSpec::SleepingKingStudios::Deferred::Dsl # rubocop:disable Style/Documentation
+  # Domain-specific language for defining deferred hooks.
+  module Hooks
+    # @overload after(scope, *flags, **conditions, &block)
+    #   Defines a deferred hook using the #after method.
+    #
+    #   @param scope [Symbol] the scope for the hook. Must be one of :context,
+    #     :each, or :example.
+    #   @param flags [Array<Symbol>] condition flags for the hook. Will be
+    #     transformed into conditions entries with true values.
+    #   @param block [Proc] the implementation of the hook.
+    #
+    #   @return [void]
+    def after(scope, *flags, **conditions, &)
+      deferred_hooks << RSpec::SleepingKingStudios::Deferred::Calls::Hook.new(
+        :after,
+        scope,
+        *flags,
+        **conditions,
+        &
+      )
+    end
+
+    # @overload append_after(scope, *flags, **conditions, &block)
+    #   Defines a deferred hook using the #append_after method.
+    #
+    #   @param scope [Symbol] the scope for the hook. Must be one of :context,
+    #     :each, or :example.
+    #   @param flags [Array<Symbol>] condition flags for the hook. Will be
+    #     transformed into conditions entries with true values.
+    #   @param block [Proc] the implementation of the hook.
+    #
+    #   @return [void]
+    def append_after(scope, *flags, **conditions, &)
+      deferred_hooks << RSpec::SleepingKingStudios::Deferred::Calls::Hook.new(
+        :append_after,
+        scope,
+        *flags,
+        **conditions,
+        &
+      )
+    end
+
+    # @overload around(scope, *flags, **conditions, &block)
+    #   Defines a deferred hook using the #around method.
+    #
+    #   @param scope [Symbol] the scope for the hook. Must be one of :context,
+    #     :each, or :example.
+    #   @param flags [Array<Symbol>] condition flags for the hook. Will be
+    #     transformed into conditions entries with true values.
+    #   @param block [Proc] the implementation of the hook.
+    #
+    #   @return [void]
+    def around(scope, *flags, **conditions, &)
+      deferred_hooks << RSpec::SleepingKingStudios::Deferred::Calls::Hook.new(
+        :around,
+        scope,
+        *flags,
+        **conditions,
+        &
+      )
+    end
+
+    # @overload before(scope, *flags, **conditions, &block)
+    #   Defines a deferred hook using the #before method.
+    #
+    #   @param scope [Symbol] the scope for the hook. Must be one of :context,
+    #     :each, or :example.
+    #   @param flags [Array<Symbol>] condition flags for the hook. Will be
+    #     transformed into conditions entries with true values.
+    #   @param block [Proc] the implementation of the hook.
+    #
+    #   @return [void]
+    def before(scope, *flags, **conditions, &)
+      deferred_hooks << RSpec::SleepingKingStudios::Deferred::Calls::Hook.new(
+        :before,
+        scope,
+        *flags,
+        **conditions,
+        &
+      )
+    end
+
+    # (see RSpec::SleepingKingStudios::Deferred::Definitions#call)
+    def call(example_group)
+      super
+
+      deferred_hooks.reverse_each do |deferred_hook|
+        deferred_hook.call(example_group)
+      end
+    end
+
+    # @private
+    def deferred_hooks
+      @deferred_hooks ||= []
+    end
+
+    # @overload prepend_before(scope, *flags, **conditions, &block)
+    #   Defines a deferred hook using the #prepend_before method.
+    #
+    #   @param scope [Symbol] the scope for the hook. Must be one of :context,
+    #     :each, or :example.
+    #   @param flags [Array<Symbol>] condition flags for the hook. Will be
+    #     transformed into conditions entries with true values.
+    #   @param block [Proc] the implementation of the hook.
+    #
+    #   @return [void]
+    def prepend_before(scope, *flags, **conditions, &)
+      deferred_hooks << RSpec::SleepingKingStudios::Deferred::Calls::Hook.new(
+        :prepend_before,
+        scope,
+        *flags,
+        **conditions,
+        &
+      )
+    end
+  end
+
+  include Hooks
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred/dsl'
+
+module RSpec::SleepingKingStudios::Deferred::Dsl # rubocop:disable Style/Documentation
+  # DSL for defining memoized helpers for deferred examples.
+  module MemoizedHelpers
+    # Callback invoked when the module is extended into another module or class.
+    #
+    # Defines a HelperImplementations module on the module and includes it in
+    # the module.
+    #
+    # @param other [Module] the other module or class.
+    def self.extended(other)
+      super
+
+      return if other.const_defined?(:HelperImplementations, true)
+
+      other.const_set(
+        :HelperImplementations,
+        Module.new do
+          named = Module.new
+
+          const_set(:NamedSuper, named)
+
+          include named
+        end
+      )
+    end
+
+    # (see RSpec::SleepingKingStudios::Deferred::Definitions#call)
+    def call(example_group)
+      super
+
+      include self::HelperImplementations
+    end
+
+    # @overload let(helper_name = nil, &block)
+    #   Defines a memoized helper.
+    #
+    #   @param helper_name [String, Symbol] the name of the helper method.
+    #   @param block [Block] the implementation of the helper method.
+    #
+    #   @return [void]
+    def let(helper_name, &)
+      helper_name = helper_name.to_sym
+
+      self::HelperImplementations.define_method(helper_name, &)
+
+      define_method(helper_name) do
+        helper_values = @memoized_helper_values ||= {}
+
+        helper_values.fetch(helper_name) do
+          helper_values[helper_name] = super()
+        end
+      end
+    end
+
+    # @overload let!(helper_name = nil, &block)
+    #   Defines a memoized helper and adds a hook to evaluate it before examples.
+    #
+    #   @param helper_name [String, Symbol] the name of the helper method.
+    #   @param block [Block] the implementation of the helper method.
+    #
+    #   @return [void]
+    def let!(helper_name, &)
+      let(helper_name, &)
+
+      before(:example) { send(helper_name) }
+    end
+
+    # Defines an optional memoized helper.
+    #
+    # The helper will use the parent value if defined; otherwise, will use the
+    # given value.
+    #
+    # @param helper_name [String, Symbol] the name of the helper method.
+    # @param block [Block] the implementation of the helper method.
+    #
+    # @return [void]
+    def let?(helper_name, &block)
+      wrapped = lambda do
+        next super() if defined?(super())
+
+        instance_exec(&block)
+      end
+
+      let(helper_name, &wrapped)
+    end
+
+    # @overload subject(helper_name = nil, &block)
+    #   Defines a memoized subject helper.
+    #
+    #   @param helper_name [String, Symbol] the name of the helper method.
+    #   @param block [Block] the implementation of the helper method.
+    #
+    #   @return [void]
+    def subject(helper_name = nil, &)
+      let(:subject, &)
+
+      define_method(helper_name) { subject } if helper_name
+
+      self::HelperImplementations::NamedSuper.define_method(:subject) do
+        raise NotImplementedError, '`super` in named subjects is not supported'
+      end
+    end
+
+    # @overload subject!(helper_name = nil, &block)
+    #   Defines a memoized subject helper and adds a hook to evaluate it.
+    #
+    #   @param helper_name [String, Symbol] the name of the helper method.
+    #   @param block [Block] the implementation of the helper method.
+    #
+    #   @return [void]
+    def subject!(helper_name = nil, &)
+      subject(helper_name, &)
+
+      before(:example) { send(helper_name) }
+    end
+  end
+
+  include MemoizedHelpers
+end