rspec-sleeping_king_studios 2.3.0 → 2.4.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: db3edfd1090162224fb44315c4253e09c25dc877
-  data.tar.gz: a2bef1ddd86161949fb43158c5418b4fd1c9842a
+SHA256:
+  metadata.gz: 28e0a03888a052a73c2094ae42046f6f90467e1f01a85f2b8ac77ba2cdfddd18
+  data.tar.gz: ab77b0ad4c36165524e295910e38f16d7beea2a3bcac75c95589d8ab968a767e
 SHA512:
-  metadata.gz: d107e3d8247775cd7467f086eeb7ac5cdd2f5ab7086ff38250e081f4c26c963f212a10162edbb8edcc8871e5b329dcd1f21f7993e7ef97ed87a4ce07c164489c
-  data.tar.gz: dbc685520978c20ce0e9a72c996e1bbc60d97fe4b80a326cf682bebcbe2dbdbf8f895e233f638524aa03922cfd994c9187f7fdd1d619f83c7fb6d38b1c65a35b
+  metadata.gz: 83993d0ad852dd78792adf0bb00db3d763d50d137b484cf859d83cab359f3e5ceaf3bc0a18f6cfe9a50758cbf77ca22b36d6df61b7b971e70d5fdc969a6502f2
+  data.tar.gz: d1c5891ef2a2c7f38f1ffb12053f83126a65ee7e3fea6a1fe5ab9c2e39aad2acb803f33b2b059bb8d4df13ea406c54fe85a4701cedebb5a708f53b8dae2b665a

data/CHANGELOG.md

@@ -1,8 +1,46 @@
 # Changelog
 
+## 2.4.0
+
+Dropped support for RSpec 3.3.
+
+Added RSpec::SleepingKingStudios.gem_path helper.
+
+### Concerns
+
+Permit terse syntax for the example_class helper, e.g `example_class :MyClass, BaseClass` instead of `example_class :MyClass, base_class: BaseClass`.
+
+Fixed a bug when using the example_class helper with a base_class that was another temporary class.
+
+### Examples
+
+Improved failure messages for "has property" examples.
+
+Aliased property matcher examples as 'should define \*', e.g. 'should have reader' is now aliased as 'should define reader'.
+
+Fixed a bug when skipping shared examples with 'xinclude_examples' incorrectly generating a context of '(focused)' instead of '(skipped)'.
+
+### Matchers
+
+Implemented the HaveChangedMatcher.
+
+    value = watch_value(object, :foo) # Create a value spy.
+
+    do_something
+
+    expect(value).to have_changed.from('initial value').to('final value')
+
+Aliased HaveConstantMatcher#immutable as #frozen.
+
+Aliased property matcher macros as define_*, e.g. have_reader is now aliased as define_reader.
+
+### Support
+
+Implemented the ValueSpy for watching changes to an object method or a block.
+
 ## 2.3.0
 
-Added RSpec::SleepingKingStudios#version helper.
+Added RSpec::SleepingKingStudios.version helper.
 
 Dropped support for RSpec 3.0 to 3.2.
 
@@ -60,7 +98,7 @@ Updated matcher testing examples (e.g. 'should pass with positive expectation',
 
 ### Matchers
 
-Internally refactored all matcher definitions to *\_matcher.rb, while the previous *.rb files define the macros which are added to example groups. The file names now accurately reflect what they define. In addition, the matchers can be required separately from the macros, e.g. to get around a naming conflict with another library. Also added support for aliasing matchers.
+Internally refactored all matcher definitions to \*\_matcher.rb, while the previous \*.rb files define the macros which are added to example groups. The file names now accurately reflect what they define. In addition, the matchers can be required separately from the macros, e.g. to get around a naming conflict with another library. Also added support for aliasing matchers.
 
 #### `alias_method` Matcher
 

data/DEVELOPMENT.md

@@ -1,10 +1,12 @@
 # Development Notes
 
-## Version 2.3
+## Version 2.4
 
-## Version 2.3.1
+### Bug Fixes
+
+- when skipping a shared example group with xinclude_examples, the generated context is named '(focused)'. It should instead be named '(skipped)'.
 
-### Features - Syntactic Sugar
+### Features
 
 - Alias `have_reader`, etc as `define_reader`.
   - Also alias shared examples.
@@ -12,30 +14,55 @@
   - Alias #immutable as #frozen.
   - Also alias shared examples.
 
-## Future Tasks
+### Maintenance
+
+- Refactor all macro specs from spec/rspec/sleeping_king_studios/matchers/macros to the directories corresponding to the source files.
+
+## Version 3.0
+
+- Extract out Rails-specific matchers to RSpec::SleepingKingStudios::Rails.
+- Refactor property, constant matchers to Define$1Matcher.
+  - HaveConstantMatcher, HaveReaderMatcher, HavePredicateMatcher, HavePropertyMatcher, HaveWriterMatcher.
+  - Designate define_* macros as primary, have_* as aliases.
+  - Designate 'should define \*' examples as primary.
+- Add RuboCop CI step.
+  - Modernize code conventions.
+- Add SimpleCov CI step.
 
-- Resolve Aruba deprecation warnings.
+## Future Tasks
 
 ### Bug Fixes
 
 - false negative on #alias_method?
   - need reproduction steps!
   - compare via Method#source_location equality and Method#original_name is expected?
+- when using a shared example from another context, ensure that the rspec-sleeping_king_studios definitions are NOT excluded from the backtrace on a failure.
+  - can do this for now: |
 
-### Features - Functionality
+    RSpec.configure do |config|
+      examples_path = File.join(RSpec::SleepingKingStudios.gem_path, 'lib', 'rspec', 'sleeping_king_studios', 'examples')
 
-- Add spy+matcher for expect(my_object, :my_method).to have_changed ?
+      config.project_source_dirs << examples_path
+    end
 
-### Features - Quality of Life
+### Features - Core
 
-- Implement RespondToMatcher#with_optional_keywords, #with_required_keywords.
-- Implement be_immutable matcher.
-- Enhance RSpec matcher examples to display the #failure_message on a failed "should pass/fail with" example.
 - let?(:name) { } # Defines a memoized helper, but only if one is not already defined.
 
-### Features - Syntactic Sugar
+### Features - Examples
+
+- matcher examples:
+  - Enhance RSpec matcher examples to display the #failure_message on a failed "should pass/fail with" example.
+
+### Features - Matchers
 
-- Implement RespondToMatcher#with_at_least(N).arguments, equivalent to with(N).arguments.and_unlimited_arguments.
+- BeImmutableMatcher (NEW):
+  - Implement be_immutable matcher.
+- HaveChangedMatcher (NEW):
+  - Add spy+matcher for expect(my_object, :my_method).to have_changed ?
+- RespondToMatcher:
+  - Implement RespondToMatcher#with_optional_keywords, #with_required_keywords.
+  - Implement RespondToMatcher#with_at_least(N).arguments, equivalent to with(N).arguments.and_unlimited_arguments.
 
 ### Maintenance
 
@@ -49,28 +76,16 @@
   - Use matcher class name instead of macro names?
   - Clarify documentation of parameters - YARD-like?
 - Integration specs for shared example groups
-  - Run in external process, parse output for expected values (similar to Aruba)
+  - Run in external process, parse output for expected values (use Aruba?)
   - Allows testing of failing example groups
 - Pare down Cucumber features for matchers - repurpose as documentation/examples only.
   - Break down into smaller (bite-sized?) individual examples.
 - RuboCop - use RSpec rule file as starting point?
+- frozen_string_literals pragma?
 
 ## Icebox
 
-- Chainable examples: |
-
-  it 'should do something' do
-    # Always run.
-  end.
-    then 'should do something else' do
-      # Only runs if first example passes.
-    end.
-    then 'should do a third thing' do
-      # Only runs if first and second examples pass.
-    end
-
 - Implement Matchers::define_negated_matcher.
-- Implement RespondTo#with_optional_keywords.
 - Implement negated compound matchers, e.g. expect().to match().and_not other_match()
   - Alias as "but_not"?
 - Implement benchmarking specs:
@@ -85,9 +100,10 @@
   - Implement shared example group for Rails routing, 'should route to'
 - Add alt doc test formatter - --format=list ? --format=documentation-list ?
   - Prints full expanded example name for each example
+  - Allows basic diffing of "what tests were run?"
 - Add minimal test formatter - --format=smoke ? --format=librarian ? --format=quiet ?
   - Prints nothing for examples
-  - Suppress STDOUT output? As configurable option for any formatted?
+  - Suppress STDOUT output? As configurable option for any formatter?
 - Add DSL for shared_examples-heavy specs?
   - #should(name) => include_examples "should #{name}"
   - #with(name)   => wrap_context "with #{name}"
@@ -95,3 +111,7 @@
 - General project for using matchers as Ruby objects
   - Inspectable - expectations, comparison results exposed via readers
   - Favor readers over instance variables.
+- Ordering options:
+  - group_by: option - allows grouping of examples, e.g. group_by: :fixtures. Groups all examples by each value of the given metadata. Also before/after/around(:group, fixtures: true)?
+  - example group-level ordering
+    - order :defined_and_fail_fast - run the specs in given order, but after a spec fails all further specs in that example group are marked as pending.

data/README.md

@@ -4,13 +4,13 @@ A collection of matchers and extensions to ease TDD/BDD using RSpec. Extends bui
 
 ## Support
 
-RSpec::SleepingKingStudios is tested against RSpec 3.3 through 3.6.
+RSpec::SleepingKingStudios is tested against RSpec 3.3 through 3.7.
 
 Currently, the following versions of Ruby are officially supported:
 
-* 2.2
 * 2.3
 * 2.4
+* 2.5
 
 For Ruby 2.0 support, use version 2.1 or earlier: `gem "rspec-sleeping_king_studios", "~> 2.1.1"`.
 
@@ -517,6 +517,34 @@ Checks if the actual object forwards the specified method to the specified targe
 * **`#with_a_block:`** (also `and_a_block`) Specifies that when the method is called on the actual object a block argument, thhe block is then passed on to the target object when the method is called on the target.
 * **`#and_return`:** Expects one or more arguments. The method is called on the actual object one time for each value passed into `#and_return`. Specifies that the return value of calling the method on the actual object is the corresponding value passed into `#and_return`.
 
+#### `#have_changed` Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/core/have_changed'
+
+Checks that a watched value has changed. The `have_changed` matcher must be paired with a value spy (see `#watch_value`, below), which is typically created with the `watch_value` helper. This is an alternative to the core RSpec `change` matcher, but allows you track changes to multiple values without nested expectations or other workarounds.
+
+**How To Use**
+
+    spy = watch_value(object, property)
+
+    object.property = 'new value'
+
+    expect(spy).to have_changed
+
+You can also create a value spy with a block:
+
+    spy = watch_value { object.property }
+
+**Parameters:** None.
+
+**Chaining:**
+
+* **by:** Expects one argument. If the value has changed, then the current value will be subtracted from the initial value and the difference compared with the expected value given to `#by`. *Note:* `not_to have_changed.by()` is not supported and will raise an error.
+* **from:** Expects one argument. The initial value of the spy (at the time the spy was initialized) must be equal to the given value.
+* **to:** Expects one argument. The current value of the spy (at the time `expect().to have_changed` is evaluated) must be equal to the given value.
+
+**Warning:** Make sure that the value spy is initialized before running whatever code is expected to change the value. In particular, if you are setting up your spies using RSpec `let()` statements, it is recommended to use the imperative `let!()` form to ensure that the spies are initialized before running the example.
+
 #### `#have_constant` Matcher
 
     require 'rspec/sleeping_king_studios/matchers/core/have_constant'
@@ -525,11 +553,11 @@ Checks for the presence of a defined constant `:CONSTANT_NAME` and optionally th
 
 **How To Use:**
 
-  expect(instance).to have_constant(:FOO)
+    expect(instance).to have_constant(:FOO)
 
-  expect(instance).to have_constant(:BAR).with_value('Bar')
+    expect(instance).to have_constant(:BAR).with_value('Bar')
 
-  expect(instance).to have_immutable_constant(:BAZ).with_value('Baz')
+    expect(instance).to have_immutable_constant(:BAZ).with_value('Baz')
 
 **Parameters:** Constant name. Expects a string or symbol that is a valid identifier.
 
@@ -619,6 +647,26 @@ Checks if the actual object responds to `#property=`.
 
 `option allow_private [Boolean]` Defaults to false. If true, the matcher will also match a private or protected method.
 
+#### `#watch_value` Helper
+
+    require 'rspec/sleeping_king_studios/matchers/core/have_changed'
+
+Creates a value spy that watches the value of a method call or block. The spy also caches the initial value at the time the spy was created; this allows comparisons between the initial and current values. Value spies are used with the `#have_changed` matcher (see above).
+
+**How To Use:**
+
+    spy = watch_value(object, property)
+
+    spy = watch_value { object.property }
+
+**Parameters:**
+
+`param object [Object]` The object to watch. Ignored if given a block.
+
+`param method_name [String, Symbol]` The name of the method to watch. Ignored if given a block.
+
+**Chaining:** None.
+
 ## Shared Examples
 
 To use a custom example group, `require` the associated file and then `include`
@@ -679,9 +727,9 @@ Delegates to the `#have_writer` matcher (see Core/#have_writer, above) and passe
 
 Delegates to the `#have_constant` matcher (see Core/#have_constant, above) and passes if the described class defines the specified constant. If a value is specified, the class or module must define the constant with the specified value. Alternatively, you can set a proc as the expected value, which can contain a comparison, an RSpec expectation, or a more complex expression:
 
-    include_examples 'should have property', :BAR, ->() { an_instance_of(String) }
+    include_examples 'should have constant', :BAR, ->() { an_instance_of(String) }
 
-    include_examples 'should have property', :BAZ, ->(value) { value.count = 3 }
+    include_examples 'should have constant', :BAZ, ->(value) { value.count = 3 }
 
 #### Should Have Immutable Constant
 

data/lib/rspec/sleeping_king_studios.rb

@@ -5,6 +5,13 @@ require 'rspec/core'
 module RSpec
   # Hic Iacet Arthurus, Rex Quondam, Rexque Futurus.
   module SleepingKingStudios
+    def self.gem_path
+      pattern =
+        /#{File::SEPARATOR}lib#{File::SEPARATOR}rspec#{File::SEPARATOR}?\z/
+
+      __dir__.sub(pattern, '')
+    end
+
     def self.version
       @version ||= RSpec::SleepingKingStudios::Version.to_gem_version
     end # class method version

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

@@ -35,6 +35,16 @@ module RSpec::SleepingKingStudios::Concerns
       raise NameError, message
     end # class method guard_existing_constant!
 
+    def self.resolve_base_class value
+      value = value.fetch(:base_class, nil) if value.is_a?(Hash)
+
+      return Object if value.nil?
+
+      return Object.const_get(value) if value.is_a?(String)
+
+      value
+    end
+
     def self.resolve_namespace module_names
       last_defined = nil
 
@@ -54,10 +64,11 @@ module RSpec::SleepingKingStudios::Concerns
       end # if
     end # class method resolve_namespace
 
-    def example_class class_name, base_class: Object, &block
+    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
-        base_class = Object.const_get(base_class) if base_class.is_a?(String)
-        klass      = Class.new(base_class)
+        klass = Class.new(ExampleConstants.resolve_base_class(base_class))
 
         klass.define_singleton_method(:name) { class_name }
         klass.singleton_class.send(:alias_method, :inspect, :name)

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

@@ -57,7 +57,7 @@ module RSpec::SleepingKingStudios::Concerns
     #   automatically skip such groups.
     # groups.
     def xinclude_examples name, *args, **kwargs, &block
-      xdescribe '(focused)' do
+      xdescribe '(skipped)' do
         if kwargs.empty?
           include_examples name, *args, &block
         else

data/lib/rspec/sleeping_king_studios/configuration.rb

@@ -8,10 +8,10 @@ module RSpec::SleepingKingStudios
     # Configuration options for RSpec::SleepingKingStudios::Examples.
     class Examples
       # Permitted options for :handle_missing_failure_message_with.
-      MISSING_FAILURE_MESSAGE_HANDLERS = %w(ignore pending exception).map(&:intern)
+      MISSING_FAILURE_MESSAGE_HANDLERS = %i[ignore pending exception].freeze
 
       # Options for matching failure messages to strings.
-      STRING_FAILURE_MESSAGE_MATCH_OPTIONS = %w(exact substring).map(&:intern)
+      STRING_FAILURE_MESSAGE_MATCH_OPTIONS = %i[exact substring].freeze
 
       # Gets the handler for missing failure messages when using the matcher
       # examples, and sets to :pending if unset.
@@ -30,6 +30,8 @@ module RSpec::SleepingKingStudios
       # @raise ArgumentError If the handler is not one of the recognized
       #   values.
       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 ', '}"
 
@@ -55,6 +57,7 @@ module RSpec::SleepingKingStudios
       # @raise ArgumentError If the handler is not one of the recognized
       #   values.
       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)
@@ -120,21 +123,21 @@ module RSpec::SleepingKingStudios
     # Get or set the configuration options for
     # RSpec::SleepingKingStudios::Examples.
     def examples &block
-      (@examples ||= RSpec::SleepingKingStudios::Configuration::Examples.new).tap do |config|
-        if block_given?
-          config.instance_eval &block
-        end # if
-      end # tap
+      @examples ||= RSpec::SleepingKingStudios::Configuration::Examples.new
+
+      @examples.instance_eval(&block) if block_given?
+
+      @examples
     end # method examples
 
     # Get or set the configuration options for
     # RSpec::SleepingKingStudios::Matchers.
     def matchers &block
-      (@matchers ||= RSpec::SleepingKingStudios::Configuration::Matchers.new).tap do |config|
-        if block_given?
-          config.instance_eval &block
-        end # if
-      end # tap
+      @matchers ||= RSpec::SleepingKingStudios::Configuration::Matchers.new
+
+      @matchers.instance_eval(&block) if block_given?
+
+      @matchers
     end # method matchers
   end # class
 end # module
@@ -142,10 +145,10 @@ end # module
 class RSpec::Core::Configuration
   # Get or set the configuration options for RSpec::SleepingKingStudios.
   def sleeping_king_studios &block
-    (@sleeping_king_studios ||= RSpec::SleepingKingStudios::Configuration.new).tap do |config|
-      if block_given?
-        config.instance_eval &block
-      end # if
-    end # tap
+    @sleeping_king_studios ||= RSpec::SleepingKingStudios::Configuration.new
+
+    @sleeping_king_studios.instance_eval(&block) if block_given?
+
+    @sleeping_king_studios
   end # method sleeping_king_studios
 end # class

data/lib/rspec/sleeping_king_studios/examples/property_examples/class_properties.rb

@@ -11,6 +11,21 @@ module RSpec::SleepingKingStudios::Examples
     module ClassProperties
       extend RSpec::SleepingKingStudios::Concerns::SharedExampleGroup
 
+      shared_examples 'should have class property' do |property, expected_value = UNDEFINED_VALUE_EXPECTATION|
+        it "should have class property :#{property}" do
+          if expected_value == UNDEFINED_VALUE_EXPECTATION
+            expect(described_class).to have_property(property)
+          else
+            expected_value = format_expected_value(expected_value)
+
+            expect(described_class).to have_property(property).with_value(expected_value)
+          end # if-else
+        end # it
+      end # shared_examples
+      alias_shared_examples 'defines class property', 'should have class property'
+      alias_shared_examples 'has class property', 'should have class property'
+      alias_shared_examples 'should define class property', 'should have class property'
+
       shared_examples 'should have class reader' do |property, expected_value = UNDEFINED_VALUE_EXPECTATION|
         it "should have class reader :#{property}" do
           if expected_value == UNDEFINED_VALUE_EXPECTATION
@@ -22,14 +37,29 @@ module RSpec::SleepingKingStudios::Examples
           end # if-else
         end # it
       end # shared_examples
+      alias_shared_examples 'defines class reader', 'should have class reader'
       alias_shared_examples 'has class reader', 'should have class reader'
+      alias_shared_examples 'should define class reader', 'should have class reader'
+
+      shared_examples 'should have class writer' do |property|
+        writer_name = property.to_s.sub /\=\z/, ''
+
+        it "should have class writer :#{writer_name}" do
+          expect(described_class).to have_writer(property)
+        end # it
+      end # shared_examples
+      alias_shared_examples 'defines class writer', 'should have class writer'
+      alias_shared_examples 'has class writer', 'should have class writer'
+      alias_shared_examples 'should define class writer', 'should have class writer'
 
       shared_examples 'should not have class reader' do |property|
         it "should not have class reader :#{property}" do
           expect(described_class).not_to have_reader(property)
         end # it
       end # shared_examples
+      alias_shared_examples 'does not define class reader', 'should not have class reader'
       alias_shared_examples 'does not have class reader', 'should not have class reader'
+      alias_shared_examples 'should not define class reader', 'should not have class reader'
 
       shared_examples 'should not have class writer' do |property|
         writer_name = property.to_s.sub /\=\z/, ''
@@ -38,29 +68,9 @@ module RSpec::SleepingKingStudios::Examples
           expect(described_class).not_to have_writer(property)
         end # it
       end # shared_examples
+      alias_shared_examples 'does not define class writer', 'should not have class writer'
       alias_shared_examples 'does not have class writer', 'should not have class writer'
-
-      shared_examples 'should have class writer' do |property|
-        writer_name = property.to_s.sub /\=\z/, ''
-
-        it "should have class writer :#{writer_name}" do
-          expect(described_class).to have_writer(property)
-        end # it
-      end # shared_examples
-      alias_shared_examples 'has class writer', 'should have class writer'
-
-      shared_examples 'should have class property' do |property, expected_value = UNDEFINED_VALUE_EXPECTATION|
-        it "should have class property :#{property}" do
-          if expected_value == UNDEFINED_VALUE_EXPECTATION
-            expect(described_class).to have_property(property)
-          else
-            expected_value = format_expected_value(expected_value)
-
-            expect(described_class).to have_property(property).with_value(expected_value)
-          end # if-else
-        end # it
-      end # shared_examples
-      alias_shared_examples 'has class property', 'should have class property'
+      alias_shared_examples 'should not define class writer', 'should not have class writer'
     end # module
   end # module
 end # module