rspec-sleeping_king_studios 2.7.0 → 2.8.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54fafe35b632818612bf767e1a2ad05e9338fd4dd68a7356f4540473423c9888
-  data.tar.gz: 6cfa48a9b350c0b19ac7fdd6a1d6a14a274b0a26ef873842b84d5e9d82438062
+  metadata.gz: f0fdf0b5b82bec68224de25df61b57af9d3910c48b30676fd96dafc0862ed5c3
+  data.tar.gz: 96e93e8c3438a94ab2f549cb5487ff6f3f1d3a72f8d935973eab796126eb5aa1
 SHA512:
-  metadata.gz: f342e4dc730b32e64339aaac823350f8de678ec8d3820c9f64ea6a8037e29df4fc0d91e6e02cc8d13a8e0b1368003907c749a3801f64060a2669519933bd2b52
-  data.tar.gz: 0f4f12cb9d5c1e350363759f2672bb9e96876f570b1bcc3aa4068171b47fcb6a752b51a9d8ca6ce184e172b3f9a1de0ef1b5bcc4e2cbbb80b6ccdef7f5761438
+  metadata.gz: f2d2c014fccc9f46abf5a1a45d14571b46e33f56edc6c3d7bb23326b8da15624ff02a24383f9da135d38a6c15fd39a171da5037c81d5d63dabeabadc68736699
+  data.tar.gz: b972588c34e3dbf36778330e3006e432c62c000823686186b1004a9b50a3b2ee4193b6d0f6d932f59a8daeb5eef7218bc5a45db4813b411d88b1a803842a6174

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 2.8.0
+
+Updated minimum `Hashdiff` version to `~> 1.1`.
+
+Extracted `rubocop-rspec` configuration. To add support for `RSpec::SleepingKingStudios` extensions to `rubocop-rspec`, add the following to your `.rubocop.yml` configuration file:
+
+```yml
+inherit_gem:
+  rspec-sleeping_king_studios: 'config/rubocop-rspec.yml'
+```
+
+### Concerns
+
+#### Memoized Helpers
+
+Implemented the `let?` memoized helper, which defines a helper method if there is not already a method with the given name.
+
+### Deferred Examples
+
+Implemented deferred examples, which provide an alternative implementation for sharing specifications between projects.
+
+### Sandbox
+
+Implemented `RSpec::SleepingKingStudios::Sandbox` for running test files in an isolated environment.
+
 ## 2.7.0
 
 ### Concerns

data/README.md

@@ -1,16 +1,32 @@
-# RSpec::SleepingKingStudios [![Build Status](https://travis-ci.org/sleepingkingstudios/rspec-sleeping_king_studios.svg?branch=master)](https://travis-ci.org/sleepingkingstudios/rspec-sleeping_king_studios)
+# RSpec::SleepingKingStudios
 
 A collection of matchers and extensions to ease TDD/BDD using RSpec. Extends built-in matchers with new functionality, such as support for Ruby 2.0+ keyword arguments, and adds new matchers for testing boolean-ness, object reader/writer properties, object constructor arguments, ActiveModel validations, and more. Also defines shared example groups for more expressive testing.
 
+<blockquote>
+  Read The
+  <a href="https://www.sleepingkingstudios.com/rspec-sleeping_king_studios" target="_blank">
+    Documentation
+  </a>
+</blockquote>
+
 ## About
 
+### Setup
+
+To add support for `RSpec::SleepingKingStudios` extensions to `rubocop-rspec`, add the following to your `.rubocop.yml` configuration file:
+
+```yml
+inherit_gem:
+  rspec-sleeping_king_studios: 'config/rubocop-rspec.yml'
+```
+
 ### Compatibility
 
 RSpec::SleepingKingStudios is tested against the following dependencies:
 
-- Ruby (MRI) 2.7 through 3.1
-- RSpec versions 3.4 through 3.10
-- ActiveModel versions 3.0 through 6.1
+- Ruby (MRI) 3.1 through 3.4
+- RSpec versions 3.9 through 3.13
+- ActiveModel versions 6.1 through 8.0
 
 ### Documentation
 
@@ -18,7 +34,7 @@ Documentation is generated using [YARD](https://yardoc.org/), and can be generat
 
 ### License
 
-Copyright (c) 2013-2021 Rob Smith
+Copyright (c) 2013-2025 Rob Smith
 
 RSpec::SleepingKingStudios is released under the [MIT License](https://opensource.org/licenses/MIT).
 
@@ -34,7 +50,6 @@ To contribute code, please fork the repository, make the desired updates, and th
 
 Please note that the `RSpec::SleepingKingStudios` project is released with a [Contributor Code of Conduct](https://github.com/sleepingkingstudios/rspec-sleeping_king_studios/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
 
-
 ## Configuration
 
 RSpec::SleepingKingStudios now has configuration options available through `RSpec.configuration`. For example, to set the behavior of the matcher examples when a failure message expectation is undefined (see RSpec Matcher Examples, below), put the following in your `spec_helper` or other configuration file:
@@ -302,6 +317,44 @@ A simplified syntax for re-using shared context or examples without having to ex
 
 (also `::xinclude_context`) A shortcut for skipping the example group by wrapping it in a `describe` block, similar to the built-in `xit` and `xdescribe` methods.
 
+### Memoized Helpers
+
+```ruby
+require 'rspec/sleepingkingstudios/concerns/memoized_helpers'
+```
+
+Methods for defining memoized helpers, similar to the core RSpec `let` method.
+
+#### `.let?`
+
+The `.let?` class method defines a memoized helper if and only if there is not an existing method with the same name defined in the example group. Among other use cases, this allows for defining default values in shared examples.
+
+```ruby
+RSpec.describe Rocket do
+  subject(:rocket) { described_class.new(name: 'Imp IV') }
+
+  shared_examples 'should launch the rocket' do
+    let?(:launch_site) { 'KSC' }
+
+    it 'should launch the rocket' do
+      expect { rocket.launch_from(launch_site) }
+        .to change(rocket, :launched?)
+        .to be true
+    end
+  end
+
+  describe '#launch_from' do
+    include_examples 'should launch the rocket'
+
+    describe 'with launch_site: value' do
+      let(:launch_site) { 'Baikerbanur' }
+
+      include_examples 'should launch the rocket'
+    end
+  end
+end
+```
+
 ### Shared Example Groups
 
     require 'rspec/sleeping_king_studios/concerns/shared_example_group'
@@ -439,7 +492,7 @@ A simplified syntax for re-using shared context or examples without having to ex
 ## Contracts
 
 ```ruby
-require 'rspec/sleepingkingstudios/contract'
+require 'rspec/sleeping_king_studios/contract'
 ```
 
 An `RSpec::SleepingKingStudios::Contract` object encapsulates a partial RSpec specification. Unlike a traditional shared example group, a contract can be reused across projects, allowing a library to define an interface, provide a reference implementation, and publish tests that validate other implementations.
@@ -450,7 +503,9 @@ Contracts can be added to an example group either through the `.apply` method or
 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 < RSpec::SleepingKingStudios::Contract
+  class ShouldBeEnumerableContract
+    extend RSpec::SleepingKingStudios::Contract
+
     # @!method apply(example_group)
     #   Adds the contract to the example group.
 
@@ -786,7 +841,7 @@ When the value does not match the expectation, the failure message will provide
     #   expected: == {:body=>{:order=>{:id=>an instance of Integer, :total=>"9.99"}}, :status=>200}
     #        got:    {:status=>400, :body=>{:order=>{:fulfilled=>false, :total=>"19.99"}}, :errors=>["Insufficient funds"]}
     #
-    #   (compared using HashDiff)
+    #   (compared using Hashdiff)
     #
     #   Diff:
     #   + :body.:order.:fulfilled => got false
@@ -961,6 +1016,170 @@ Creates a value spy that watches the value of a method call or block. The spy al
 
 **Chaining:** None.
 
+## Sandbox
+
+The `RSpec::SleepingKingStudios::Sandbox` module allows for running a spec file or files in an isolated environment and capturing the results. This can be useful for testing code meant to enhance your tests, such as a custom RSpec matcher or a shared example group.
+
+First, define a spec file to run. As a recommended convention, spec files to be run in a sandbox should be given the `spec.fixture.rb` suffix to ensure they are not accidentally run with the main test suite.
+
+```ruby
+# frozen_string_literal: true
+
+# In spec/rocket_spec.fixture.rb:
+RSpec.describe Rocket do
+  describe '#launch' do
+    it 'should launch the rocket' do
+      expect { subject.launch }.to change(subject, :launched?).to be true
+    end
+  end
+end
+```
+
+Defining fixture files rather than generating temporary files is recommended for performance reasons, but both approaches are possible. Once the file is defined, it can be run in a sandbox:
+
+```ruby
+result = RSpec::SleepingKingStudios::Sandbox.run('spec/rocket_spec.fixture.rb')
+
+result.class #=> RSpec::SleepingKingStudios::Sandbox::Result
+result.output #=> """
+# Rocket
+#   #launch
+#     should launch the rocket
+#
+# 1 example, 0 failures
+# """
+result.status #=> 1
+result.summary #=> 1 example, 0 failures
+result.example_descriptions #=> [
+#   'Rocket#launch should launch the rocket'
+# ]
+```
+
+The `.run` method returns an instance of `RSpec::SleepingKingStudios::Sandbox::Result`, which wraps the result of running the specified spec files. It defines the following methods:
+
+- `#errors`: The output captured from STDERR when running the files.
+- `#example_descriptions`: The full description for each evaluated example.
+- `#json`: The json output from running the files.
+- `#output`: The output captured from STDOUT when running the files. The specs are run with the `--format=doc` flag, so this will include the individual examples as well as the summary.
+- `#summary`: The summary line for the tests.
+
+## Deferred Examples
+
+`RSpec::SleepingKingStudios::Deferred` provides a mechanism for defining specifications that can be reused and shared between projects. For example, a library could use deferred examples to define an interface and test a reference implementation; projects that use that library could then use the published deferred examples to validate their own implementations of that interface.
+
+At its core, a deferred example group is a Ruby `module`, and hooks into the inheritance hierarchy when `include`d into an example group. This gives certain advantages relative to traditional shared examples (and contracts):
+
+- Deferred examples are defined in a specific context, and can be shared by simply `include`-ing the containing module (or the deferred examples directly). There is no global namespace, and using deferred examples (even from other projects) is as simple as an `include` call.
+- Deferred examples stack, rather than conflict. This means helper methods and memoized helpers can reference other included examples using `super()`, rather than simply overwriting other helpers at the same "level".
+- Unlike shared example groups, deferred examples defined via a `Provider` (see [Parameterized Examples](#parameterized-examples), below) can accept a block parameter.
+
+```ruby
+module ShouldBeAVehicleExamples
+  include RSpec::SleepingKingStudios::Deferred::Examples
+
+  describe '#type' do
+    it { expect(subject).to respond_to(:type).with(0).arguments }
+
+    it { expect(subject.type).to be == expected_type }
+  end
+end
+
+RSpec.describe Rocket do
+  include ShouldBeAVehicleExamples
+
+  subject(:rocket) { described_class.new }
+
+  let(:expected_type) { :rocket }
+
+  describe '#launch' do
+    it { expect(rocket).to respond_to(:launch) }
+  end
+end
+```
+
+### Parameterized Examples
+
+Deferred examples can also be defined with parameters using the `Deferred::Provider` DSL. Defining a parameterized example group allows for defining and sharing specs that describe complex and conditional behavior.
+
+For deferred specs that set up a context rather than examples, `deferred_context` is provided as an alias to `Provider.deferred_examples`.
+
+```ruby
+module VehicleExamples
+  include RSpec::SleepingKingStudios::Deferred::Provider
+
+  deferred_context 'when the vehicle needs to be serviced' \
+  do |serviced_at: '2020-01-01'|
+    before(:example) do
+      vehicle.last_serviced_at = serviced_at
+    end
+  end
+
+  deferred_examples 'should be a Vehicle' do |vehicle_type:|
+    it { expect(subject).to be_a Spec::Models::Vehicle }
+
+    describe '#type' do
+      it { expect(subject.type).to be == vehicle_type }
+    end
+  end
+end
+```
+
+The deferred examples can be included in example groups using the `Deferred::Consumer` DSL.
+
+```ruby
+RSpec.describe Car do
+  include RSpec::SleepingKingStudios::Deferred::Consumer
+  include VehicleExamples
+
+  subject(:car) { described_class.new }
+
+  include_deferred 'should be a Vehicle', vehicle_type: :car
+end
+
+RSpec.describe Rocket do
+  include RSpec::SleepingKingStudios::Deferred::Consumer
+  include VehicleExamples
+
+  subject(:rocket) { described_class.new }
+
+  include_deferred 'should be a Vehicle', vehicle_type: :rocket
+end
+```
+
+`Deferred::Consumer` also defines support for wrapped deferred examples, which automatically generate a new context and include the deferred examples in the new example group. If `#wrap_deferred` is passed a block, that block will automatically be evaluated in the context of the example group, allowing you to define additional context or examples.
+
+```ruby
+RSpec.describe Car do
+  include RSpec::SleepingKingStudios::Deferred::Consumer
+  include VehicleExamples
+
+  subject(:car) { described_class.new }
+
+  wrap_deferred 'when the vehicle needs to be serviced' do
+    it { expect(car.last_serviced_at).to be == '2020-01-01' }
+  end
+end
+```
+
+`Deferred::Consumer` also includes the shortcuts `#finclude_deferred` and `#fwrap_deferred` to automatically focus deferred examples, or `#xinclude_deferred` and `#xwrap_deferred` to skip deferred examples.
+
+The `defined_deferred_examples?` and `defined_deferred_context?` methods allow checking for the presence of a deferred example group.
+
+```ruby
+RSpec.describe Boat do
+  include RSpec::SleepingKingStudios::Deferred::Consumer
+  include VehicleExamples
+
+  subject(:boat) { described_class.new }
+
+  if defined_deferred_examples?('should be a water Vehicle')
+    include_deferred 'should be a water Vehicle'
+  else
+    pending 'deferred examples "should be a water Vehicle" is not defined'
+  end
+end
+```
+
 ## Shared Examples
 
 To use a custom example group, `require` the associated file and then `include`

data/config/rubocop-rspec.yml

@@ -0,0 +1,41 @@
+RSpec:
+  Language:
+    ExampleGroups:
+      Regular:
+        - context
+        - describe
+        - wrap_context
+        - wrap_deferred
+      Skipped:
+        - xcontext
+        - xdescribe
+        - xwrap_context
+        - xwrap_deferred
+      Focused:
+        - fcontext
+        - fdescribe
+        - fwrap_context
+        - fwrap_deferred
+    Helpers:
+      - let
+      - let!
+      - let?
+    Includes:
+      Examples:
+        - finclude_contract
+        - finclude_deferred
+        - finclude_examples
+        - fwrap_examples
+        - include_contract
+        - include_deferred
+        - include_examples
+        - wrap_examples
+        - xinclude_contract
+        - xinclude_deferred
+        - xinclude_examples
+        - xwrap_examples
+    SharedGroups:
+      Examples:
+        - deferred_examples
+      Context:
+        - deferred_context

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

@@ -1,107 +1,140 @@
-# lib/rspec/sleeping_king_studios/concerns/example_constants.rb
+# frozen_string_literal: true
 
 require 'rspec/sleeping_king_studios/concerns'
 
 module RSpec::SleepingKingStudios::Concerns
-  module ExampleConstants
+  # Methods for defining example-scoped classes and constants.
+  module ExampleConstants # rubocop:disable Metrics/ModuleLength
     DEFAULT_VALUE = Object.new.freeze
     private_constant :DEFAULT_VALUE
 
-    def self.assign_constant namespace, constant_name, constant_value
-      prior_value = DEFAULT_VALUE
+    class << self
+      # @api private
+      def define_class(class_name:, example:, base_class: nil, &block)
+        klass = Class.new(resolve_base_class(base_class))
 
-      if namespace.const_defined?(constant_name)
-        prior_value = namespace.const_get(constant_name)
-      end # if
+        klass.define_singleton_method(:name) { class_name }
+        klass.singleton_class.send(:alias_method, :inspect, :name)
+        klass.singleton_class.send(:alias_method, :to_s,    :name)
 
-      namespace.const_set(constant_name, constant_value)
+        example.instance_exec(klass, &block) if block_given?
 
-      yield
-    ensure
-      if prior_value == DEFAULT_VALUE
-        namespace.send :remove_const, constant_name
-      else
-        namespace.const_set(constant_name, prior_value)
-      end # if-else
-    end # class method assign_constant
+        klass
+      end
 
-    def self.guard_existing_constant! namespace, constant_name
-      return unless namespace.const_defined?(constant_name)
+      # @api private
+      def with_constant( # rubocop:disable Metrics/MethodLength
+        constant_name:,
+        constant_value:,
+        namespace:,
+        force: false
+      )
+        guard_existing_constant!(namespace, constant_name) unless force
 
-      message =
-        "constant #{constant_name} is already defined with value "\
-        "#{namespace.const_get(constant_name).inspect}"
+        prior_value = DEFAULT_VALUE
 
-      raise NameError, message
-    end # class method guard_existing_constant!
+        if namespace.const_defined?(constant_name)
+          prior_value = namespace.const_get(constant_name)
+        end
 
-    def self.resolve_base_class value
-      value = value.fetch(:base_class, nil) if value.is_a?(Hash)
+        namespace.const_set(constant_name, constant_value)
 
-      return Object if value.nil?
+        yield
+      ensure
+        if prior_value == DEFAULT_VALUE
+          namespace.send :remove_const, constant_name
+        else
+          namespace.const_set(constant_name, prior_value)
+        end
+      end
 
-      return Object.const_get(value) if value.is_a?(String)
+      # @api private
+      def with_namespace(module_names) # rubocop:disable Metrics/MethodLength
+        last_defined = nil
 
-      value
-    end
+        resolved =
+          module_names.reduce(Object) do |namespace, module_name|
+            if namespace.const_defined?(module_name)
+              next namespace.const_get(module_name)
+            end
 
-    def self.resolve_namespace module_names
-      last_defined = nil
+            last_defined ||= { namespace:, module_name: }
 
-      resolved =
-        module_names.reduce(Object) do |ns, module_name|
-          next ns.const_get(module_name) if ns.const_defined?(module_name)
+            namespace.const_set(module_name, Module.new)
+          end
 
-          last_defined ||= { :namespace => ns, :module_name => module_name }
+        yield resolved
+      ensure
+        if last_defined
+          last_defined[:namespace]
+            .send(:remove_const, last_defined[:module_name])
+        end
+      end
 
-          ns.const_set(module_name, Module.new)
-        end # reduce
+      private
 
-      yield resolved
-    ensure
-      if last_defined
-        last_defined[:namespace].send(:remove_const, last_defined[:module_name])
-      end # if
-    end # class method resolve_namespace
+      def guard_existing_constant!(namespace, constant_name)
+        return unless namespace.const_defined?(constant_name)
 
-    def example_class class_name, base_class = nil, &block
-      class_name = class_name.to_s if class_name.is_a?(Symbol)
+        message =
+          "constant #{constant_name} is already defined with value " \
+          "#{namespace.const_get(constant_name).inspect}"
 
-      example_constant(class_name) do
-        klass = Class.new(ExampleConstants.resolve_base_class(base_class))
+        raise NameError, message
+      end
 
-        klass.define_singleton_method(:name) { class_name }
-        klass.singleton_class.send(:alias_method, :inspect, :name)
-        klass.singleton_class.send(:alias_method, :to_s,    :name)
+      def resolve_base_class(value)
+        value = value.fetch(:base_class, nil) if value.is_a?(Hash)
 
-        instance_exec(klass, &block) if block_given?
+        return Object if value.nil?
 
-        klass
-      end # example_constant
-    end # method example_class
+        return Object.const_get(value) if value.is_a?(String)
 
-    def example_constant qualified_name, constant_value = DEFAULT_VALUE, force: false, &block
-      around(:example) do |wrapped_example|
-        example = wrapped_example.example
+        value
+      end
+    end
+
+    def example_class(class_name, base_class = nil, &block)
+      class_name = class_name.to_s if class_name.is_a?(Symbol)
+
+      example_constant(class_name) do
+        ExampleConstants.define_class(
+          base_class:,
+          class_name:,
+          example:    self,
+          &block
+        )
+      end
+    end
 
+    def example_constant( # rubocop:disable Metrics/MethodLength
+      qualified_name,
+      constant_value = DEFAULT_VALUE,
+      force: false,
+      &block
+    )
+      around(:example) do |wrapped_example|
         resolved_value =
-          if constant_value == DEFAULT_VALUE
-            block ? example.instance_exec(&block) : nil
+          if constant_value == DEFAULT_VALUE && block_given?
+            wrapped_example.example.instance_exec(&block)
           else
             constant_value
-          end # if
-
-        module_names  = qualified_name.to_s.split('::')
-        constant_name = module_names.pop
-
-        ExampleConstants.resolve_namespace(module_names) do |namespace|
-          ExampleConstants.guard_existing_constant!(namespace, constant_name) unless force
-
-          ExampleConstants.assign_constant(namespace, constant_name, resolved_value) do
+          end
+
+        *module_names, constant_name = qualified_name.to_s.split('::')
+
+        ExampleConstants.with_namespace(module_names) do |namespace|
+          ExampleConstants.with_constant(
+            constant_name:,
+            constant_value: resolved_value,
+            namespace:,
+            force:
+          ) \
+          do
             wrapped_example.call
-          end # assign_constant
-        end # resolve_namespace
-      end # before example
-    end # method example_constant
-  end # module
-end # module
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/concerns'
+
+module RSpec::SleepingKingStudios::Concerns
+  # Methods for defining memoized helpers in example groups.
+  module MemoizedHelpers
+    # Defines a memoized helper if a method of the same name is not defined.
+    #
+    # @param method_name [String] the name of the helper method.
+    #
+    # @yieldreturn [Object] the value of the memoized helper method.
+    def let?(method_name, &)
+      return method_name if method_defined?(method_name)
+
+      let(method_name, &)
+    end
+  end
+end

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

@@ -69,8 +69,11 @@ module RSpec::SleepingKingStudios::Concerns
     # example group by including the module. The shared examples must be
     # defined before including the module, or they will not be available in the
     # example group.
-    def shared_examples name, *metadata_args, &block
-      RSpec.world.shared_example_group_registry.add(self, name, *metadata_args, &block)
+    def shared_examples(name, *metadata_args, **metadata_kwargs, &block)
+      RSpec
+        .world
+        .shared_example_group_registry
+        .add(self, name, *metadata_args, **metadata_kwargs, &block)
     end # method shared_examples
     alias_method :shared_context, :shared_examples
 

data/lib/rspec/sleeping_king_studios/concerns.rb

@@ -1,8 +1,13 @@
-# lib/rspec/sleeping_king_studios/concerns.rb
+# frozen_string_literal: true
 
 require 'rspec/sleeping_king_studios'
 
 module RSpec::SleepingKingStudios
   # RSpec-related concerns to mix into classes or objects.
-  module Concerns; end
-end # module
+  module Concerns
+    autoload :ExampleConstants,
+      'rspec/sleeping_king_studios/concerns/example_constants'
+    autoload :MemoizedHelpers,
+      'rspec/sleeping_king_studios/concerns/memoized_helpers'
+  end
+end