rspec-sleeping_king_studios 2.0.0.beta.0 → 2.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 29c1c209fa47ee1227c9385fdb0381a81eda028f
-  data.tar.gz: 8e7c6a833de4df42900de5e57fa48b1bc7ce4590
+  metadata.gz: 4f6b435b34abdf1b87b2496605d4472339e97b51
+  data.tar.gz: 9ab33137c4cdb76bdd1957e060814a5a8a6a23cd
 SHA512:
-  metadata.gz: ea8a1a387419691c5ade0edb948b331415aa4b4e56bfbcf24cb51144d3f1c7f8b2a2a429b2d0d1cac7e8177357084336bba42eaf23a8a5e7d4ddc6677e3b20af
-  data.tar.gz: 99ce1c09c14adbe4a14291a7bef9551172a84c694e856b13e028069ede03aef6a9eefb052a4c360b14ef0faff11aa93210df536cf160dac186b9d07498a3cb69
+  metadata.gz: 3fadfe034ff61756ef19b23eb4d4f15e7239b0e26a770cfa9711445d216e27efb487206b20848cae983732def47b3c45c2225778ddd9dc00023d2a742a5996ff
+  data.tar.gz: 6ea0170359b50b8b5a012085430ea5fa3cb92ee9fe563b38dcdc53ffdcee2ae7f0a9802c31d6f394a6d5b91759e4f5c15c90c225996eee865dd3ba6034348067

data/CHANGELOG.md

@@ -2,28 +2,99 @@
 
 ## 2.0.0
 
-Update the entire library to support RSpec 3. Most of the updates are purely
-internal, but there are a few changes that are not backward compatible to be
-aware of.
+Update the entire library to support RSpec 3. Most of the updates are purely internal, but there are a few changes that are not backward compatible to be aware of.
 
-### Matchers
+### Ruby 1.9.3 Support
+
+Support for Ruby 1.9.3 is officially dropped.
+
+### Concerns
+
+Added module RSpec::SleepingKingStudios::Examples::SharedExampleGroup as a mixin for defining scoped shared example groups. Extend into a module to define shared example groups scoped to that module (and automatically included in example groups when the module is included), or extend into an example group to allow aliasing shared example groups with alternate or more expressive names.
+
+### Custom Examples
+
+Added custom shared example groups for easier/more expressive tests.
+
+#### Property Examples
+
+Added 'has reader', 'has writer', and 'has property' examples as shorthand for defining property and attribute expectations.
+
+#### RSpec Matcher Examples
+
+Added custom examples for testing RSpec matchers. Replaces the (now removed) `pass_with_actual` and `fail_with_actual` matchers, which were fiddly and confusing (even for me) and couldn't handle all cases (such as failing on both `expect().to` and `expect().not_to`).
+
+### Custom Matchers
 
 All matchers have been updated to support the RSpec 3 matcher API.
 
-#### fail_with_actual Matcher
+#### `construct` Matcher
+
+Now has a fluent method for both `#argument` and `#arguments` to support the singular and plural use cases, similar to the built-in `respond_to` matcher.
+
+    expect(FooClass).to construct.with(1).argument
+    expect(BarClass).to construct.with(3).arguments
+
+#### `fail_with_actual` Matcher
+
+Removed. To test custom matchers, use the new shared examples (see Shared Examples, below).
+
+#### `have_errors` Matcher
+
+Adds the `#with` fluent method as an alias to `#with_messages`, as follows:
+
+    expect(model).to have_errors.on(:my_field).with("can't be blank")
+
+In addition, the have_errors matcher will fail on both a positive expectation (`expect().to`) and a negative expectation (`expect().not_to` or `expect().to_not`) if the actual object does not respond to `#valid?`. The failure message has also been clarified for cases like `expect().not_to have_errors.on(attribute)`.
 
-Now correctly handles the #does_not_match? case for the new matcher API.
+#### `have_property` Matcher
 
-#### respond\_to Matcher
+Removed the functionality checking the value of `:property` after `:property=` has been invoked. The syntax for doing so was not expressive, and the feature was rarely used. To verify that invoking `:property=` will change `:property` to the desired value, set up the change expectation directly using a `#change` matcher.
 
-The #and fluent method has been removed, and the #a_block method for verifying
-the presence of a block argument has been renamed to #with_a_block.
+Now supports composable matchers, as follows:
+
+    expect(object).to have_property(:my_method).with(an_instance_of(Fixnum))
+
+Also added `#with_value` as an alias for `with`, and the error messages have been edited for clarity.
+
+#### `have_reader` Matcher
+
+Now supports composable matchers, as follows:
+
+    expect(object).to have_reader(:my_method).with(an_instance_of(String))
+
+Also added `#with_value` as an alias for `with`, and the error messages have been edited for clarity.
+
+#### `have_writer` Matcher
+
+Removed the functionality checking the value of `:property` after `:property=` has been invoked. The syntax for doing so was not expressive, and the feature was rarely used. To verify that invoking `:property=` will change `:property` to the desired value, set up the change expectation directly using a `#change` matcher.
+
+The error messages have also been edited for clarity.
+
+#### `pass_with_actual` Matcher
+
+Removed. To test custom matchers, use the new shared examples (see Shared Examples, below).
+
+#### `respond_to` Matcher
+
+The `#and` fluent method has been removed, and the `#a_block` method for verifying the presence of a block argument has been renamed to `#with_a_block`. In addition, by passing in `true` as the last argument, can check for the presence and arguments of protected or private methods, similar to the Ruby `Object#respond_to?` method.
 
 ### Mocks
 
-The #custom_double mock method has been completely removed. The recommended
-solution for that use case is `double('My Double').extend(MyModule)`, for some
-`MyModule` that implements the desired actual (non-stubbed) functionality.
+The #custom_double mock method has been completely removed. The recommended solution for that use case is `double('My Double').extend(MyModule)`, for some `MyModule` that implements the desired actual (non-stubbed) functionality.
+
+### Shared Examples
+
+Adds a new category of features, Shared Example groups, that can be included for easier or more expressive spec definitions.
+
+#### Examples for Custom RSpec Matchers
+
+Added four new shared examples to test custom matchers:
+
+    include_examples 'passes with a positive expectation'
+    include_examples 'passes with a negative expectation'
+    include_examples 'fails with a positive expectation'
+    include_examples 'fails with a negative expectation'
 
 ## 1.0.1
 
@@ -31,7 +102,7 @@ solution for that use case is `double('My Double').extend(MyModule)`, for some
 
 * The #construct and #respond_to matchers now support 2.1.0 required keyword
   arguments, of the form def foo(bar:, baz:). If the class constructor or
-  method requires one or more keyword arguments, and one or more of those 
+  method requires one or more keyword arguments, and one or more of those
   keywords are not provided when checking arguments using the #with
   method, the matcher will fail with the message "missing keywords" and a list
   of the keywords that were not provided as arguments to #with.

data/DEVELOPMENT.md

@@ -0,0 +1,16 @@
+# Development Notes
+
+## Tasks
+
+### High Priority
+
+### Medium Priority
+
+[RC1]
+- Thorough documentation pass.
+- Test against both RSpec 3.0 and 3.1 (multiple gemfiles? See ActiveModel::Collection for how it's done)
+
+### Low Priority
+
+[RC1]
+- Cucumber features for testing matchers, including returned text?

data/README.md

@@ -1,15 +1,11 @@
 # 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)
 
-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.
+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.
 
 ## Supported Ruby Versions
 
 Currently, the following versions of Ruby are officially supported:
 
-* 1.9.3
 * 2.0.0
 * 2.1.0
 
@@ -19,30 +15,70 @@ Currently, the following versions of Ruby are officially supported:
 
 ### A Note From The Developer
 
-Hi, I'm Rob Smith, the maintainer of this library. As a professional Ruby
-developer, I use these tools every day. If you find this project helpful in
-your own work, or if you have any questions, suggestions or critiques, please
-feel free to get in touch! I can be reached on GitHub (see above, and feel
-encouraged to submit bug reports or merge requests there) or via email at
-merlin@sleepingkingstudios.com. I look forward to hearing from you!
+Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use these tools every day, but they're not just written for me. If you find this project helpful in your own work, or if you have any questions, suggestions or critiques, please feel free to get in touch! I can be reached on GitHub (see above, and feel encouraged to submit bug reports or merge requests there) or via email at `merlin@sleepingkingstudios.com`. I look forward to hearing from you!
 
-## The Matchers
+## 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:
+
+    RSpec.configure do |config|
+      config.sleeping_king_studios do |config|
+        config.examples do |config|
+          config.handle_missing_failure_message_with = :ignore
+        end # config
+      end # config
+    end # config
+
+### Configuration Options
+
+#### Handle Missing Failure Message With
+
+This option is used with the RSpec matcher examples (see Examples, below), and determines the behavior when a matcher is expected to fail, but the corresponding failure message is not defined (via `let(:failure_message)` or `let(:failure_message_when_negated)`). The default option is `:pending`, which marks the generated example as skipped (and will show up as pending in the formatter). Other options include `:skip`, which marks the generated example as passing, and `:exception`, which marks the generated example as failing.
+
+## Concerns
+
+RSpec::SleepingKingStudios defines a few concerns that can be included in or extended into modules or example groups for additional functionality.
+
+### Shared Example Groups
+
+    require 'rspec/sleeping_king_studios/examples/shared_example_group'
+
+    module MyCustomExamples
+      extend RSpec::SleepingKingStudios::Examples::SharedExampleGroup
+
+      shared_examples 'has custom behavior' do
+        # Define expectations here...
+      end # shared_examples
+      alias_shared_examples 'should have custom behavior', 'has custom behavior'
+    end # module
+
+Utility functions for defining shared examples. If included in a module, any shared examples defined in that module are scoped to the module, rather than placed in a global scope. This allows you to define different shared examples with the same name in different contexts, similar to the current behavior when defining a shared example inside an example group. To use the defined examples, simply `include` the module in an example group. **Important Note:** Shared examples and aliases must be defined **before** including the module in an example group. Any shared examples or aliases defined afterword will not be available inside the example group.
+
+### `::alias_shared_examples`
+
+Aliases a defined shared example group, allowing it to be accessed using a new name. The example group must be defined in the current context using `shared_examples`. The aliases must be defined before including the module into an example group, or they will not be available in the example group.
+
+### `::shared_examples`
+
+Defines a shared example group within the context of the current module. Unlike a top-level example group defined using RSpec#shared_examples, these examples are not globally available, and must be mixed into an 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.
+
+## Custom Matchers
 
 To enable a custom matcher, simply require the associated file. Matchers can be
 required individually or by category:
 
-    require 'rspec/sleeping_king_studios'
+    require 'rspec/sleeping_king_studios/all'
     #=> requires all features, including matchers
 
-    require 'rspec/sleeping_king_studios/matchers/core'
+    require 'rspec/sleeping_king_studios/matchers/core/all'
     #=> requires all of the core matchers
-    
+
     require 'rspec/sleeping_king_studios/matchers/core/construct'
     #=> requires only the :construct matcher
 
 ### ActiveModel
 
-    require 'rspec/sleeping_king_studios/matchers/active_model'
+    require 'rspec/sleeping_king_studios/matchers/active_model/all'
 
 These matchers validate ActiveModel functionality, such as validations.
 
@@ -56,21 +92,26 @@ individual fields to validate, or even specific messages for each attribute.
 **How To Use:**
 
     expect(instance).to have_errors
-    
+
     expect(instance).to have_errors.on(:name)
-    
+
     expect(instance).to have_errors.on(:name).with_message('not to be nil')
 
 **Chaining:**
 
 * **on:** [String, Symbol] Adds a field to validate; the matcher only passes if
   all validated fields have errors.
+* **with:** [Array<String>] Adds one or more messages to the previously-defined
+  field validation. Raises ArgumentError if no field was previously set.
 * **with\_message:** [String] Adds a message to the previously-defined field
   validation. Raises ArgumentError if no field was previously set.
+* **with\_messages:** [Array<String>] Adds one or more messages to the
+  previously-defined field validation. Raises ArgumentError if no field was
+  previously set.
 
 ### BuiltIn
 
-    require 'rspec/sleeping_king_studios/matchers/built_in'
+    require 'rspec/sleeping_king_studios/matchers/built_in/all'
 
 These extend the built-in RSpec matchers with additional functionality.
 
@@ -104,41 +145,24 @@ now accepts an optional block as a shortcut for adding a proc expectation.
 
     require 'rspec/sleeping_king_studios/matchers/built_in/respond_to'
 
-Now has additional chaining functionality to validate the number of arguments
-accepted by the method, and whether the method accepts a block argument.
+Now has additional chaining functionality to validate the number of arguments accepted by the method, the keyword arguments (if any) accepted by the method, and whether the method accepts a block argument.
 
 **How To Use:**
 
+    # With a variable number of arguments.
     expect(instance).to respond_to(:foo).with(2..3).arguments.with_a_block
 
-**Chaining:**
-
-* **with:** Expects one Integer or Range argument. If an Integer, verifies that
-  the method accepts that number of arguments; if a Range, verifies that the
-  method accepts both the minimum and maximum number of arguments.
-* **with\_a\_block:** No parameters. Verifies that the method requires a block
-  argument of the form &my_argument. _Important note:_ A negative result does
-  _not* mean the method cannot accept a block, merely that it does not require
-  one. Also, does _not_ check whether the block is called or yielded.
-
-##### Ruby 2.0+
-
-Has additional functionality to support Ruby 2.0 keyword arguments.
-
-**How To Use:**
-  expect(instance).to respond_to(:foo).with(0, :bar, :baz)
+    # With keyword arguments.
+    expect(instance).to respond_to(:foo).with(0, :bar, :baz)
 
 **Chaining:**
 
-* **with:** Expects at most one Integer or Range argument, and zero or more
-  Symbol arguments corresponding to optional keywords. Verifies that the method
-  accepts that keyword, or has a variadic keyword of the form \*\*params. As 
-  of 2.1.0 and required keywords, verifies that all required keywords are 
-  provided.
+* **with:** Expects at most one Integer or Range argument, and zero or more Symbol arguments corresponding to optional keywords. Verifies that the method accepts that keyword, or has a variadic keyword of the form `**params`. As of 2.1.0 and required keywords, verifies that all required keywords are provided.
+* **with\_a\_block:** No parameters. Verifies that the method requires a block argument of the form `&my_argument`. _Important note:_ A negative result _does not_ mean the method cannot accept a block, merely that it does not require one. Also, _does not_ check whether the block is called or yielded.
 
 ### Core
 
-    require 'rspec/sleeping_king_studios/matchers/core'
+    require 'rspec/sleeping_king_studios/matchers/core/all'
 
 These matchers check core functionality, such as object boolean-ness, the
 existence of properties, and so on.
@@ -187,28 +211,28 @@ Has additional functionality to support Ruby 2.0 keyword arguments.
 * **with:** Expects one Integer, Range, or nil argument, and zero or more
   Symbol arguments corresponding to optional keywords. Verifies that the
   class's constructor accepts that keyword, or has a variadic keyword of the
-  form \*\*params.  As of 2.1.0 and required keywords, verifies that all 
+  form \*\*params.  As of 2.1.0 and required keywords, verifies that all
   required keywords are provided.
 
 #### have\_property Matcher
 
     require 'rspec/sleeping_king_studios/matchers/core/have_property'
 
-Checks if the actual object responds to :property and :property=, and
-optionally if a value written to actual.property= can then be read by
-actual.property.
+Checks if the actual object responds to :property and :property=, and optionally if the curernt value of actual.property is equal to a specified value.
 
 **How To Use:**
 
     expect(instance).to have_property(:foo).with("foo")
 
-**Parameters:** Property. Expects a string or symbol that is a valid
-identifier.
+**Parameters:** Property. Expects a string or symbol that is a valid identifier.
 
 **Chaining:**
 
-* **with:** Expects one object, which is written to actual.property= and then
-  read from actual.property.
+* **with:** Expects one object, which is checked against the current value of actual.property if actual responds to :property. Can also be used with an RSpec matcher:
+
+    expect(instance).to have_property(:bar).with(an_instance_of(String))
+
+* **with_value:** Alias for `#with`, above.
 
 #### have\_reader Matcher
 
@@ -221,37 +245,30 @@ current value of actual.property is equal to a specified value.
 
     expect(instance).to have_reader(:foo).with("foo")
 
-**Parameters:** Property. Expects a string or symbol that is a valid
-identifier.
+**Parameters:** Property. Expects a string or symbol that is a valid identifier.
 
 **Chaining:**
 
-* **with:** Expects one object, which is checked against the current value of
-  actual.property if actual responds to :property.
-  
+* **with:** Expects one object, which is checked against the current value of actual.property if actual responds to :property. Can also be used with an RSpec matcher:
+
+    expect(instance).to have_reader(:bar).with(an_instance_of(String))
+
+* **with_value:** Alias for `#with`, above.
+
 #### have\_writer Matcher
 
     require 'rspec/sleeping_king_studios/matchers/core/have_writer'
 
-Checks if the actual object responds to :property=, and optionally if setting
-object.property = value sets object.property to value.
+Checks if the actual object responds to :property=.
 
 **How To Use:**
 
-    expect(instance).to have_writer(:foo=).with("foo")
+    expect(instance).to have_writer(:foo=)
 
 **Parameters:** Property. Expects a string or symbol that is a valid
 identifier. An equals sign '=' is automatically added if the identifier does
 not already terminate in '='.
 
-**Chaining:**
-
-* **with:** Expects one object. The matcher attempts to set the actual's value
-  using actual.property=, then compare the value with actual.property.
-  
-  _Note:_ Currently, write-only properties cannot be checked using with().
-  Attempting to do so will raise an exception.
-
 #### include\_matching Matcher
 
     require 'rspec/sleeping_king_studios/matchers/core/include_matching'
@@ -265,57 +282,143 @@ matches the given pattern.
 
 **Parameters:** Pattern. Expects a Regexp.
 
-### Meta
+## Shared Examples
 
-    require 'rspec/sleeping_king_studios/matchers/meta'
+To use a custom example group, `require` the associated file and then `include`
+the module in your example group:
 
-These meta-matchers are used to test other custom matchers.
+    require 'rspec/sleeping_king_studios/examples/some_examples'
 
-#### fail\_with\_actual Matcher
+    RSpec.describe MyCustomMatcher do
+      include RSpec::SleepingKingStudios::Examples::SomeExamples
 
-    require 'rspec/sleeping_king_studios/matchers/meta/fail_with_actual'
+      # You can use the custom shared examples here.
+      include_examples 'some examples'
+    end # describe
 
-Checks if the given matcher will fail to match a specified actual object. Can
-take an optional string to check the expected failure message when the matcher
-is expected to pass, but does not.
+Unless otherwise noted, these shared examples expect the example group to define either an explicit `#instance` method (using `let(:instance) {}`) or an implicit `subject`. Their behavior is **undefined** if neither `#instance` nor `subject` is defined.
 
-_Note:_ Do not use the not\_to syntax for this matcher; instead, use the
-pass\_with\_actual matcher, below.
+### Property Examples
 
-**How To Use:**
+These examples are shorthand for defining a reader and/or writer expectation.
 
-    expect(matcher).to fail_with_actual(actual).with_message(/expected to/)
-    
-**Parameters:** Matcher. Expects an object that, at minimum, responds to
-:matches? and :failure\_message.
+#### Has Property
 
-**Chaining:**
+    include_examples 'has property', :foo, 42
 
-* **with\_message:** Expects one String or Regexp argument, which is matched
-  against the given matcher's failure\_message.
+Delegates to the `#has_reader` and `#has_writer` matchers (see Core/Has Reader and Core/Has Writer, above) and passes if the actual object responds to the specified property and property writer methods. If a value is specified, the object must respond to the property and return 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:
 
-#### pass\_with\_actual Matcher
+    include_examples 'has property', :bar, ->() { an_instance_of(String) }
 
-    require 'rspec/sleeping_king_studios/matchers/meta/pass_with_actual'
+    include_examples 'has property', :baz, ->(value) { value.count = 3 }
 
-Checks if the given matcher will match a specified actual object. Can take an
-optional string to check the expected failure message when the matcher is
-expected to fail, but does not.
+#### Has Reader
 
-_Note:_ Do not use the not\_to syntax for this matcher; instead, use the
-fail\_with\_actual matcher, above.
+    include_examples 'has reader', :foo, 42
 
-**How To Use:**
+Delegates to the `#has_reader` matcher (see Core/Has Reader, above) and passes if the actual object responds to the specified property. If a value is specified, the object must respond to the property and return 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:
 
-    expect(matcher).to pass_with_actual(actual).with_message(/expected not to/)
-  
-**Parameters:** Matcher. Expects an object that, at minimum, responds to
-:matches? and :failure\_message\_when\_negated.
+    include_examples 'has reader', :bar, ->() { an_instance_of(String) }
 
-**Chaining:**
+    include_examples 'has reader', :baz, ->(value) { value.count = 3 }
+
+#### Has Writer
+
+    include_examples 'has writer', :foo=
+
+Delegates to the `#has_writer` matcher (see Core/Has Writer, above) and passes if the actual object responds to the specified property writer.
+
+### RSpec Matcher Examples
+
+These examples are used for validating custom RSpec matchers. They are used
+internally by RSpec::SleepingKingStudios to verify the functionality of the
+new and modified matchers.
+
+    require 'rspec/sleeping_king_studios/examples/rspec_matcher_examples'
+
+    RSpec.describe MyCustomMatcher do
+      include RSpec::SleepingKingStudios::Examples::RSpecMatcherExamples
+
+      # You can use the custom shared examples here.
+    end # describe
+
+The `#instance` or `subject` for these examples should be an instance of a class matching the RSpec matcher API. For example, consider a matcher that checks if a number is a multiple of another number. This matcher would be used as follows:
+
+    expect(12).to be_a_multiple_of(3)
+    #=> true
+
+    expect(14).to be_a_multiple_of(3)
+    #=> false
+
+Therefore, the `#instance` or `subject` should be defined as `BeAMultipleMatcher.new(3)`. If the custom matcher has additional fluent methods or options, these can be added to the instance as well, e.g. `expect(15).to be_a_multiple_of(3).and_of(5)` would be tested as `BeAMultipleMatcher.new(3).and_of(5)`.
+
+In addition, all of these examples require a defined `#actual` method in the example group containing the object to be tested. The actual object is the object used in the expectation. In the above examples, the actual object is `12` in the first example, and `14` in the second. You can define the `#actual` method using `#let()`, e.g. `let(:actual) { Object.new }`.
+
+Putting it all together:
+
+    require 'rspec/sleeping_king_studios/examples/rspec_matcher_examples'
+
+    RSpec.describe BeAMultipleOfMatcher do
+      include RSpec::SleepingKingStudios::Examples::RSpecMatcherExamples
+
+      let(:instance) { BeAMultipleOfMatcher.new(3) }
+
+      describe 'with a valid number' do
+        let(:actual) { 15 }
+
+        # Include examples here.
+
+        describe 'with a second factor' do
+          let(:instance) { BeAMultipleOfMatcher.new(3).and_of(5) }
+
+          # Include examples here.
+        end # describe
+      end # describe
+    end # describe
+
+#### Passes With A Positive Expectation
+
+    include_examples 'passes with a positive expectation'
+
+Verifies that the instance matcher will pass with a positive expectation (e.g. `expect().to`). Equivalent to verifying the result of the following:
+
+    expect(actual).to match_my_custom_matcher(*expected_values)
+    #=> passes
+
+#### Passes With A Negative Expectation
+
+    include_examples 'passes with a negative expectation'
+
+Verifies that the instance matcher will pass with a negative expectation (e.g. `expect().not_to`). Equivalent to verifying the result of the following:
+
+    expect(actual).not_to match_my_custom_matcher(*expected_values)
+    #=> passes
+
+#### Fails With A Positive Expectation
+
+    include_examples 'fails with a positive expectation'
+
+Verifies that the instance matcher will fail with a positive expectation (e.g. `expect().to`), and have the expected failure message. Equivalent to verifying the result of the following:
+
+    expect(actual).to match_my_custom_matcher(*expected_values)
+    #=> fails
+
+In addition, verifies the `#failure_message` of the matcher by comparing it against a `#failure_message` method in the example group. This should be defined using `let(:failure_message) { 'expected to match' }`.
+
+The behavior if the example group does not define `#failure_message` depends on the value of the `RSpec.configure.sleeping_king_studios.examples.handle_missing_failure_message_with` option (see Configuration, above). Accepted values are `:ignore`, `:pending` (default; marks the example as pending), and `:exception` (raises an exception).
+
+#### Fails With A Negative Expectation
+
+    include_examples 'fails with a negative expectation'
+
+Verifies that the instance matcher will fail with a negative expectation (e.g. `expect().not_to`), and have the expected failure message. Equivalent to verifying the result of the following:
+
+    expect(actual).not_to match_my_custom_matcher(*expected_values)
+    #=> fails
+
+In addition, verifies the `#failure_message_when_negated` of the matcher by comparing it against a `#failure_message_when_negated` method in the example group. This should be defined using `let(:failure_message_when_negated) { 'expected not to match' }`.
 
-* **with\_message:** Expects one String or Regexp argument, which is matched
-  against the given matcher's failure\_message\_when\_negated.
+See Fails With A Positive Expectation, above, for behavior when the example group does not define `#failure_message_when_negated`.
 
 ## License
 

data/lib/rspec/sleeping_king_studios/all.rb

@@ -0,0 +1,4 @@
+# lib/rspec/sleeping_king_studios/all.rb
+
+require 'rspec/sleeping_king_studios/examples/all'
+require 'rspec/sleeping_king_studios/matchers/all'

data/lib/rspec/sleeping_king_studios/configuration.rb

@@ -0,0 +1,42 @@
+# lib/rspec/sleeping_king_studios/configuration.rb
+
+require 'rspec/sleeping_king_studios'
+
+module RSpec::SleepingKingStudios
+  class Configuration
+    class Examples
+      MISSING_FAILURE_MESSAGE_HANDLERS = %w(ignore pending exception).map(&:intern)
+
+      def handle_missing_failure_message_with
+        @handle_missing_failure_message_with ||= :pending
+      end # method missing_failure_message
+
+      def handle_missing_failure_message_with= value
+        unless MISSING_FAILURE_MESSAGE_HANDLERS.include?(value)
+          message = "unrecognized handler value -- must be in #{MISSING_FAILURE_MESSAGE_HANDLERS.join ', '}"
+          raise ArgumentError.new message
+        end # unless
+
+        @handle_missing_failure_message_with = value
+      end # message missing_failure_message=
+    end # class
+    
+    def examples &block
+      (@examples ||= RSpec::SleepingKingStudios::Configuration::Examples.new).tap do |config|
+        if block_given?
+          config.instance_eval &block
+        end # if
+      end # tap
+    end # method examples
+  end # class
+end # module
+
+class RSpec::Core::Configuration
+  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
+  end # method sleeping_king_studios
+end # class

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

@@ -0,0 +1,5 @@
+# lib/rspec/sleeping_king_studios/examples/all.rb
+
+Dir[File.join File.dirname(__FILE__), '*_examples.rb'].each do |file|
+  require file
+end # end each