rspec-sleeping_king_studios 1.0.0.rc.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a201081c88d39452f78afa3150316e817901a52d
+  data.tar.gz: 1ea674d3e88024e1d945b17e1ecd10d5c09d722a
+SHA512:
+  metadata.gz: ee4bdd1817d0d128b1e30304be501c63990545464bb7fa69dc272939073f487f26e5c32480aa7d00324c4d32d24a2cbc27738bb8ec374a671801ff09c03c1756
+  data.tar.gz: 8003b45634d319d7619a712dfece3d51df24e91394c294667e64e26e73770a2b99d6ae8986ded60be8902a055f5829a1fc25777d16f5a281d8ec2a404a47b523

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2013 Rob Smith
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,323 @@
+# RSpec::SleepingKingStudios
+
+A collection of matchers and extensions to ease TDD/BDD using RSpec.
+
+## The Extensions
+
+To enable an extension, simply require the associated file.
+
+### Mocks
+
+These extensions support the creation and use of mock objects.
+
+#### custom\_double
+
+    require 'rspec/sleeping_king_studios/mocks/custom_double'
+
+As the built-in 'double' method, but accepts a block that is passed to
+Class.new when the double is created, allowing you to create functional class
+and instance methods on the double. Useful when you need to test a function or
+sequence that repeatedly updates or checks the state of the injected object.
+
+**How To Use:**
+
+    custom_double('My Double', :foo => "Foo") { attr_accessor :bar }
+
+## The Matchers
+
+To enable a custom matcher, simply require the associated file. Matchers can be
+required individually or by category:
+
+    require 'rspec/sleeping_king_studios/matchers/core'
+    #=> 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'
+
+These matchers validate ActiveModel functionality, such as validations.
+
+#### have\_errors Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/active_model/have_errors'
+
+Verifies that the actual object has validation errors. Optionally can specify
+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\_message:** [String] Adds a message to the previously-defined field
+  validation. Raises ArgumentError if no field was previously set.
+
+### BuiltIn
+
+    require 'rspec/sleeping_king_studios/matchers/built_in'
+
+These extend the built-in RSpec matchers with additional functionality.
+
+#### be\_kind\_of Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/built_in/be_kind_of'
+
+Now accepts an Array of types. The matcher passes if the actual object is
+any of the parameter types.
+
+Also allows nil parameter as a shortcut for NilClass.
+
+**How To Use:**
+
+    expect(instance).to be_kind_of [String, Symbol, nil]
+    #=> passes iff instance is a String, a Symbol, or is nil
+
+#### include Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/built_in/include'
+
+Now accepts Proc parameters; items in the actual object are passed into
+proc#call, with a truthy response considered a match to the item. In addition,
+now accepts an optional block as a shortcut for adding a proc expectation.
+
+**How To Use:**
+
+    expect(instance).to include { |item| item =~ /pattern/ }
+
+#### respond\_to Matcher
+
+    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.
+
+**How To Use:**
+
+    expect(instance).to respond_to(:foo).with(2..3).arguments.and.a_block
+
+**Chaining:**
+
+* **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.
+* **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.
+
+##### 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)
+
+**Chaining:**
+
+* **with:** Expects one Integer, Range, or nil 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.
+
+  _Important note:_ If you do not wish to validate the number of arguments,
+  make sure to use nil as the first argument to #with; otherwise, the matcher
+  will interpret your first keyword as the number of arguments to expect. And
+  then explode.
+
+### Core
+
+    require 'rspec/sleeping_king_studios/matchers/core'
+
+These matchers check core functionality, such as object boolean-ness, the
+existence of properties, and so on.
+
+#### be_boolean Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/core/be_boolean'
+
+Checks if the provided object is true or false.
+
+**How To Use:**
+
+    expect(object).to be_boolean
+
+**Parameters:** None.
+
+#### construct Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/core/construct'
+
+Verifies that the actual object can be constructed using :new. Can take an
+optional number of arguments.
+
+**How To Use:**
+
+    expect(described_class).to construct.with(1).arguments
+
+**Parameters:** None.
+
+**Chaining:**
+
+* **with:** Expects one Integer or Range argument. If an Integer, verifies that
+  the class's constructor accepts that number of arguments; if a Range,
+  verifies that the constructor accepts both the minimum and maximum number of
+  arguments.
+
+##### Ruby 2.0
+
+Has additional functionality to support Ruby 2.0 keyword arguments.
+
+**How To Use:**
+  expect(instance).to construct.with(0, :bar, :baz)
+
+**Chaining:**
+
+* **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.
+
+  _Important note:_ If you do not wish to validate the number of arguments,
+  make sure to use nil as the first argument to #with; otherwise, the matcher
+  will interpret your first keyword as the number of arguments to expect. And
+  then explode.
+
+#### 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.
+
+**How To Use:**
+
+    expect(instance).to have_property(:foo).with("foo")
+
+**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.
+
+#### have\_reader Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/core/have_reader'
+
+Checks if the actual object responds to :property, and optionally if the
+current value of actual.property is equal to a specified value.
+
+**How To Use:**
+
+    expect(instance).to have_reader(:foo).with("foo")
+
+**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.
+  
+#### 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.
+
+**How To Use:**
+
+    expect(instance).to have_writer(:foo=).with("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'
+
+Loops through an enumerable actual object and checks if any of the items
+matches the given pattern.
+
+**How To Use:**
+
+    expect(instance).to include_matching(/[01]+/)
+
+**Parameters:** Pattern. Expects a Regexp.
+
+### Meta
+
+    require 'rspec/sleeping_king_studios/matchers/meta'
+
+These meta-matchers are used to test other custom matchers.
+
+#### fail\_with\_actual Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/meta/fail_with_actual'
+
+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.
+
+_Note:_ Do not use the not\_to syntax for this matcher; instead, use the
+pass\_with\_actual matcher, below.
+
+**How To Use:**
+
+    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\_for\_should.
+
+**Chaining:**
+
+* **with\_message:** Expects one String or Regexp argument, which is matched
+  against the given matcher's failure\_message\_for\_should.
+
+#### pass\_with\_actual Matcher
+
+    require 'rspec/sleeping_king_studios/matchers/meta/pass_with_actual'
+
+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.
+
+_Note:_ Do not use the not\_to syntax for this matcher; instead, use the
+fail\_with\_actual matcher, above.
+
+**How To Use:**
+
+    expect(matcher).to pass_with_actual(actual)
+  
+**Parameters:** Matcher. Expects an object that, at minimum, responds to
+:matches? and :failure\_message\_for\_should\_not.
+
+**Chaining:**
+
+* **with\_message:** Expects one String or Regexp argument, which is matched
+  against the given matcher's failure\_message\_for\_should\_not.
+
+## License
+
+RSpec::SleepingKingStudios is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/rspec/sleeping_king_studios.rb

@@ -0,0 +1,5 @@
+# lib/rspec/sleeping_king_studios.rb
+
+require 'rspec/sleeping_king_studios/matchers'
+
+require 'rspec/sleeping_king_studios/mocks/custom_double'

data/lib/rspec/sleeping_king_studios/matchers.rb

@@ -0,0 +1,5 @@
+# lib/rspec/sleeping_king_studios/matchers.rb
+
+%w(active_model built_in core meta).each do |dir_name|
+  require File.join File.dirname(__FILE__), 'matchers', dir_name
+end # each

data/lib/rspec/sleeping_king_studios/matchers/active_model.rb

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

data/lib/rspec/sleeping_king_studios/matchers/active_model/have_errors.rb

@@ -0,0 +1,219 @@
+# lib/rspec/sleeping_king_studios/matchers/active_model/have_errors.rb
+
+require 'rspec/sleeping_king_studios/matchers/base_matcher'
+require 'rspec/sleeping_king_studios/matchers/active_model/require'
+require 'rspec/sleeping_king_studios/matchers/active_model/have_errors/error_expectation'
+
+module RSpec::SleepingKingStudios::Matchers::ActiveModel
+  # Matcher for testing ActiveModel object validations.
+  # 
+  # @since 1.0.0
+  class HaveErrorsMatcher < RSpec::SleepingKingStudios::Matchers::BaseMatcher
+    include RSpec::SleepingKingStudios::Matchers::ActiveModel::HaveErrors
+
+    def initialize
+      super
+
+      # The error and message expectations set up through #on and
+      # #with_message.
+      @error_expectations = []
+    end # constructor
+
+    # Checks if the object can be validated, whether the object is valid, and
+    # checks the errors on the object against the expected errors and messages
+    # from #on and #with_message, if any.
+    # 
+    # @param [Object] actual the object to test against the matcher
+    # 
+    # @return [Boolean] true if the object responds to :valid?, is not valid,
+    #   and object.errors matches the specified errors and messages (if any);
+    #   otherwise false
+    # @see RSpec::SleepingKingStudios::Matchers::BaseMatcher#matches?
+    def matches? actual
+      super
+
+      return false unless @validates = actual.respond_to?(:valid?)
+
+      @actual.invalid? && attributes_have_errors?
+    end # method matches?
+
+    # Adds an error expectation. If the actual object does not have an error on
+    # the specified attribute, #matches? will return false.
+    # 
+    # @param [String, Symbol] attribute
+    # 
+    # @return [HaveErrorsMatcher] self
+    # 
+    # @example Setting an error expectation
+    #   expect(actual).to have_errors.on(:foo)
+    def on attribute
+      @error_expectations << ErrorExpectation.new(attribute)
+      
+      self
+    end # method on
+
+    # Adds a message expectation for the most recently added error attribute.
+    # If the actual object does not have an error on the that attribute with
+    # the specified message, #matches? will return false.
+    # 
+    # @param [String, Regexp] message the expected error message. If a string,
+    #   matcher will check for an exact match; if a regular expression, matcher
+    #   will check if the message matches the regexp
+    # 
+    # @raise [ArgumentError] if no error attribute has been added
+    # 
+    # @return [HaveErrorsMatcher] self
+    # 
+    # @example Setting an error and a message expectation
+    #   expect(actual).to have_errors.on(:foo).with("can't be blank")
+    # 
+    # @see #on
+    def with_message message
+      raise ArgumentError.new "no attribute specified for error message" if
+        @error_expectations.empty?
+        
+      @error_expectations.last.messages << MessageExpectation.new(message)
+      
+      self
+    end # method with_message
+
+    # Adds a set of message expectations for the most recently added error
+    # attribute.
+    # 
+    # @param [Array<String, Regexp>] messages
+    # 
+    # @see #with_message
+    def with_messages *messages
+      messages.each do |message| self.with_message(message); end
+      
+      self
+    end # method with_message
+
+    # @see BaseMatcher#failure_message_for_should
+    def failure_message_for_should
+      # Failure cases:
+      # * object is not a model ("to respond to valid")
+      # * expected one or more errors, but received none ("to have errors")
+      # * expected one or more messages on :attribute, but received none or a
+      #   subset ("to have errors on")
+
+      if !@validates
+        "expected #{@actual.inspect} to respond to :valid?"
+      elsif expected_errors.empty?
+        "expected #{@actual.inspect} to have errors"
+      else
+        "expected #{@actual.inspect} to have errors#{expected_errors_message}#{received_errors_message}"
+      end # if-elsif-else
+    end # method failure_message_for_should
+
+    # @see BaseMatcher#failure_message_for_should_not
+    def failure_message_for_should_not
+      # Failure cases:
+      # * expected one or more errors, received one or more ("not to have
+      #   errors")
+      # * expected one or more messages on attribute, received one or more
+      #   ("not to have errors on")
+      # * expected specific messages on attribute, received all ("not to have
+      #   errors on")
+      
+      if expected_errors.empty?
+        return "expected #{@actual.inspect} not to have errors#{received_errors_message}"
+      else
+        return "expected #{@actual.inspect} not to have errors#{expected_errors_message}#{received_errors_message}"
+      end # if-else
+    end # method failure_message_for_should_not
+
+    private
+    
+    def attributes_have_errors?
+      # Iterate through the received errors and match them against the expected
+      # errors and messages.
+      @actual.errors.messages.each do |attribute, messages|
+        # Find the matching error expectation, if any.
+        error_expectation = @error_expectations.detect do |error_expectation|
+          error_expectation.attribute == attribute
+        end # detect
+
+        if error_expectation
+          error_expectation.received = true
+
+          # If the error includes message expectations, iterate through the
+          # received messages.
+          unless error_expectation.messages.empty?
+            messages.each do |message|
+              # Find the matching message expectation, if any.
+              message_expectation = error_expectation.messages.detect do |message_expectation|
+                if Regexp === message_expectation.message
+                  message =~ message_expectation.message
+                else
+                  message == message_expectation.message
+                end # if-else
+              end # detect
+
+              if message_expectation
+                message_expectation.received = true
+              else
+                error_expectation.messages << MessageExpectation.new(message, false, true)
+              end # if-else
+            end # each  
+          end # unless
+        else
+          error_expectation = ErrorExpectation.new attribute, false, true
+          messages.each do |message|
+            error_expectation.messages << MessageExpectation.new(message, false, true)
+          end # each
+
+          @error_expectations << error_expectation
+        end # if-else
+      end # each
+
+      missing_errors.empty? && missing_messages.empty?
+    end # method attributes_have_errors
+
+    def expected_errors
+      @error_expectations.select do |error_expectation|
+        error_expectation.expected
+      end # select
+    end # method expected_errors
+    
+    def missing_errors
+      @error_expectations.select do |error_expectation|
+        error_expectation.expected && !error_expectation.received
+      end # select
+    end # method missing_errors
+
+    def missing_messages
+      @error_expectations.select do |error_expectation|
+        !error_expectation.messages.missing.empty?
+      end # select
+    end # method missing_messages
+
+    def unexpected_errors
+      @error_expectations.select do |error_expectation|
+        !error_expectation.expected && error_expectation.received
+      end # select
+    end # method unexpected_errors
+
+    def expected_errors_message
+      "\n  expected errors:" + expected_errors.map do |error_expectation|
+        "\n    #{error_expectation.attribute}: " + (error_expectation.messages.empty? ?
+          "(any)" :
+          error_expectation.messages.expected.map(&:message).map(&:inspect).join(", "))
+      end.join # map
+    end # method expected_errors_message
+
+    def received_errors_message
+      return "" unless @validates
+      "\n  received errors:" + @actual.errors.messages.map do |attr, ary|
+        "\n    #{attr}: " + ary.map(&:inspect).join(", ")
+      end.join # map
+    end # method received_errors_message
+  end # class
+
+  module RSpec::SleepingKingStudios::Matchers
+    # @see RSpec::SleepingKingStudios::Matchers::ActiveModel::HaveErrorsMatcher#matches?
+    def have_errors
+      RSpec::SleepingKingStudios::Matchers::ActiveModel::HaveErrorsMatcher.new
+    end # method have_errors
+  end # module
+end # module