rspec-expectations 2.6.0 → 2.7.0.rc1

data/README.md

@@ -3,7 +3,7 @@
 rspec-expectations adds `should` and `should_not` to every object and includes
 RSpec::Matchers, a library of standard matchers.
 
-[![build status](http://travis-ci.org/rspec/rspec-expectations.png)](http://travis-ci.org/rspec/rspec-expectations)
+[![build status](https://secure.travis-ci.org/rspec/rspec-expectations.png)](http://travis-ci.org/rspec/rspec-expectations)
 
 ## Documentation
 
@@ -21,7 +21,7 @@ tracker](https://github.com/rspec/rspec-expectations/issues).
 ## Install
 
     gem install rspec               # for rspec-core, rspec-expectations, rspec-mocks
-    gem install rspec-expecctations # for rspec-expectations only
+    gem install rspec-expectations  # for rspec-expectations only
 
 ## Matchers
 

data/features/built_in_matchers/README.md

@@ -29,10 +29,10 @@
 
 ## Truthiness and existentialism
 
-    actual.should be_true  # passes if actual is anything but nil or false
-    actual.should be_false # passes if actual is nil or false
+    actual.should be_true  # passes if actual is truthy (not nil or false)
+    actual.should be_false # passes if actual is falsy (nil or false)
     actual.should be_nil   # passes if actual is nil
-    actual.should be       # passes if actual is not nil
+    actual.should be       # passes if actual is truthy (not nil or false)
 
 ## Expecting errors
 
@@ -49,11 +49,13 @@
 
 ## Predicate matchers
 
-    actual.should be_xxx # passes if actual.xxx?
+    actual.should be_xxx         # passes if actual.xxx?
+    actual.should have_xxx(:arg) # passes if actual.has_xxx?(:arg)
 
-### Example
+### Examples
 
     [].should be_empty # passes because [].empty? returns true
+    { :a => 1 }.should have_key(:a) # passes because the hash has the key :a
 
 ## Collection membership
 

data/features/built_in_matchers/be.feature

@@ -5,7 +5,7 @@ Feature: "be" matchers
       obj.should be_true  # passes if obj is truthy (not nil or false)
       obj.should be_false # passes if obj is falsy (nil or false)
       obj.should be_nil   # passes if obj is nil
-      obj.should be       # passes if obj is not nil
+      obj.should be       # passes if obj is truthy (not nil or false)
 
   Scenario: be_true matcher
     Given a file named "be_true_spec.rb" with:

data/features/built_in_matchers/cover.feature

@@ -28,7 +28,7 @@ Feature: cover matcher
         it { should_not cover(8) }
         it { should_not cover(4, 6, 8) }
 
-        # both of these should fail since it covers 1 but not 9
+        # both of these should fail since it covers 5 but not 11
         it { should cover(5, 11) }
         it { should_not cover(5, 11) }
       end

data/features/built_in_matchers/expect_error.feature

@@ -15,32 +15,65 @@ Feature: raise_error matcher
   In addition to the basic form, above, there are a number of ways to specify
   details of an error/exception:
 
+      expect { raise "oops" }.to raise_error
+      expect { raise "oops" }.to raise_error(RuntimeError)
+      expect { raise "oops" }.to raise_error("oops")
+      expect { raise "oops" }.to raise_error(/op/)
+      expect { raise "oops" }.to raise_error(RuntimeError, "oops")
+      expect { raise "oops" }.to raise_error(RuntimeError, /op/)
+
   Scenario: expect any error
-    Given a file named "expect_error_spec.rb" with:
+    Given a file named "example_spec" with:
       """
-      describe "calling a method that does not exist" do
+      describe "calling a missing method" do
         it "raises" do
           expect { Object.new.foo }.to raise_error
         end
       end
       """
-    When I run `rspec expect_error_spec.rb`
+    When I run `rspec example_spec`
     Then the example should pass
 
   Scenario: expect specific error
-    Given a file named "expect_error_spec.rb" with:
+    Given a file named "example_spec" with:
       """
-      describe "calling a method that does not exist" do
+      describe "calling a missing method" do
         it "raises" do
           expect { Object.new.foo }.to raise_error(NameError)
         end
       end
       """
-    When I run `rspec expect_error_spec.rb`
+    When I run `rspec example_spec`
+    Then the example should pass
+
+  Scenario: match message with a string
+    Given a file named "example_spec.rb" with:
+      """
+      describe "matching error message with string" do
+        it "matches the error message" do
+          expect { raise StandardError, 'this message exactly'}.
+            to raise_error('this message exactly')
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the example should pass
+
+  Scenario: match message with a regexp
+    Given a file named "example_spec.rb" with:
+      """
+      describe "matching error message with regex" do
+        it "matches the error message" do
+          expect { raise StandardError, "my message" }.
+            to raise_error(/my mess/)
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
     Then the example should pass
 
-  Scenario: expect specific error message using a string
-    Given a file named "expect_error_with_message.rb" with:
+  Scenario: match type + message with string
+    Given a file named "example_spec.rb" with:
       """
       describe "matching error message with string" do
         it "matches the error message" do
@@ -49,11 +82,11 @@ Feature: raise_error matcher
         end
       end
       """
-    When I run `rspec expect_error_with_message.rb`
+    When I run `rspec example_spec.rb`
     Then the example should pass
 
-  Scenario: expect specific error message using a regular expression
-    Given a file named "expect_error_with_regex.rb" with:
+  Scenario: match type + message with regexp
+    Given a file named "example_spec.rb" with:
       """
       describe "matching error message with regex" do
         it "matches the error message" do
@@ -62,11 +95,11 @@ Feature: raise_error matcher
         end
       end
       """
-    When I run `rspec expect_error_with_regex.rb`
+    When I run `rspec example_spec.rb`
     Then the example should pass
 
   Scenario: set expectations on error object passed to block
-    Given a file named "expect_error_with_block_spec.rb" with:
+    Given a file named "example_spec" with:
       """
       describe "#foo" do
         it "raises NameError" do
@@ -76,30 +109,30 @@ Feature: raise_error matcher
         end
       end
       """
-      When I run `rspec expect_error_with_block_spec.rb`
+      When I run `rspec example_spec`
       Then the example should pass
 
-  Scenario: expect no error at all
-    Given a file named "expect_no_error_spec.rb" with:
+  Scenario: expect no occurence of a specific error
+    Given a file named "example_spec" with:
       """
-      describe "#to_s" do
+      describe Object, "#public_instance_methods" do
         it "does not raise" do
-          expect { Object.new.to_s }.to_not raise_error
+          expect { Object.public_instance_methods }.
+            to_not raise_error(NameError)
         end
       end
       """
-    When I run `rspec expect_no_error_spec.rb`
+    When I run `rspec example_spec`
     Then the example should pass
-    
-  Scenario: expect no occurence of a specific error
-    Given a file named "expect_no_error_spec.rb" with:
+
+  Scenario: expect no error at all
+    Given a file named "example_spec" with:
       """
-      describe Object, "#public_instance_methods" do
+      describe "#to_s" do
         it "does not raise" do
-          expect { Object.public_instance_methods }.
-            to_not raise_error(NameError)
+          expect { Object.new.to_s }.to_not raise_error
         end
       end
       """
-    When I run `rspec expect_no_error_spec.rb`
+    When I run `rspec example_spec`
     Then the example should pass

data/features/built_in_matchers/have.feature

@@ -4,8 +4,8 @@ Feature: have(n).items matcher
   size of a collection.  There are three basic forms:
 
     * collection.should have(x).items
-    * collection.should have_at_least(x).items
-    * collection.should have_at_most(x).items
+    * collection.should have\_at\_least(x).items
+    * collection.should have\_at\_most(x).items
 
   In addition, #have_exactly is provided as an alias to #have.
 

data/features/built_in_matchers/predicates.feature

@@ -101,7 +101,7 @@ Feature: predicate matchers
        """
      When I run `rspec should_not_have_all_string_keys_spec.rb`
      Then the output should contain "2 examples, 1 failure"
-      And the output should contain "expected #has_all_string_keys?(nil) to return false, got true"
+      And the output should contain "expected #has_all_string_keys? to return false, got true"
 
    Scenario: matcher arguments are passed on to the predicate method
      Given a file named "predicate_matcher_argument_spec.rb" with:

data/features/step_definitions/additional_cli_steps.rb

@@ -7,7 +7,7 @@ end
 
 Then /^the output should contain all of these:$/ do |table|
   table.raw.flatten.each do |string|
-    assert_partial_output(string)
+    assert_partial_output(string, all_output)
   end
 end
 

data/features/support/env.rb

@@ -1,5 +1,5 @@
 require 'aruba/cucumber'
 
 Before do
-  @aruba_timeout_seconds = 3
+  @aruba_timeout_seconds = 15
 end

data/lib/rspec/expectations.rb

@@ -5,11 +5,9 @@ require 'rspec/expectations/errors'
 require 'rspec/expectations/deprecation'
 require 'rspec/expectations/handler'
 require 'rspec/expectations/version'
-require 'rspec/expectations/backward_compatibility'
 require 'rspec/expectations/differ'
 
 module RSpec
-  
   # RSpec::Expectations lets you set expectations on your objects.
   #
   #   result.should == 37

data/lib/rspec/expectations/deprecation.rb

@@ -1,9 +1,9 @@
 module RSpec
-
-  # This is defined in rspec-core, but we can't assume it's loaded since
-  # rspec-expectations should be usable w/o rspec-core.
   unless respond_to?(:deprecate)
     class << self
+      # Used internally by RSpec to display standard deprecation warnings.
+      # This is also defined in rspec-core, but we can't assume it's loaded
+      # since rspec-expectations should be usable w/o rspec-core.
       def deprecate(method, alternate_method=nil, version=nil)
         version_string = version ? "rspec-#{version}" : "a future version of RSpec"
 
@@ -27,10 +27,12 @@ ADDITIONAL
         warn_deprecation(message)
       end
 
+      # Used internally by RSpec to display custom deprecation warnings.  This
+      # is also defined in rspec-core, but we can't assume it's loaded since
+      # rspec-expectations should be usable w/o rspec-core.
       def warn_deprecation(message)
         send :warn, message
       end
     end
   end
 end
-

data/lib/rspec/expectations/errors.rb

@@ -1,12 +1,9 @@
 module RSpec
   module Expectations
-    # If Test::Unit is loaed, we'll use its error as baseclass, so that Test::Unit
-    # will report unmet RSpec expectations as failures rather than errors.
-    superclass = ['Test::Unit::AssertionFailedError', '::StandardError'].map do |c|
-      eval(c) rescue nil
-    end.compact.first
-    
-    class ExpectationNotMetError < superclass
+    if defined?(Test::Unit::AssertionFailedError)
+      class ExpectationNotMetError < Test::Unit::AssertionFailedError; end
+    else
+      class ExpectationNotMetError < ::StandardError; end
     end
   end
 end

data/lib/rspec/expectations/extensions.rb

@@ -1,2 +1,3 @@
 require 'rspec/expectations/extensions/kernel'
 require 'rspec/expectations/extensions/array'
+require 'rspec/expectations/extensions/object'

data/lib/rspec/expectations/extensions/array.rb

@@ -1,5 +1,7 @@
+# @private
 class Array
   unless public_instance_methods.map {|m| m.to_s}.include?('none?')
+    # Supports +none?+ on early patch levels of Ruby 1.8.6
     def none?(&block)
       !any?(&block)
     end

data/lib/rspec/expectations/extensions/kernel.rb

@@ -1,51 +1,25 @@
 module Kernel
-  # :call-seq:
-  #   should(matcher)
-  #   should == expected
-  #   should === expected
-  #   should =~ expected
-  #
-  #   receiver.should(matcher)
-  #     => Passes if matcher.matches?(receiver)
-  #
-  #   receiver.should == expected #any value
-  #     => Passes if (receiver == expected)
-  #
-  #   receiver.should === expected #any value
-  #     => Passes if (receiver === expected)
-  #
-  #   receiver.should =~ regexp
-  #     => Passes if (receiver =~ regexp)
-  #
-  # See RSpec::Matchers for more information about matchers
-  #
-  # == Warning
-  #
-  # NOTE that this does NOT support receiver.should != expected.
-  # Instead, use receiver.should_not == expected
+  # Passes if +matcher+ returns true.  Available on every +Object+.
+  # @example
+  #   actual.should eq(expected)
+  #   actual.should be > 4
+  # @param [Matcher]
+  #   matcher
+  # @param [String] message optional message to display when the expectation fails
+  # @return [Boolean] true if the expectation succeeds (else raises)
+  # @see RSpec::Matchers
   def should(matcher=nil, message=nil, &block)
     RSpec::Expectations::PositiveExpectationHandler.handle_matcher(self, matcher, message, &block)
   end
-  
-  # :call-seq:
-  #   should_not(matcher)
-  #   should_not == expected
-  #   should_not === expected
-  #   should_not =~ expected
-  #
-  #   receiver.should_not(matcher)
-  #     => Passes unless matcher.matches?(receiver)
-  #
-  #   receiver.should_not == expected
-  #     => Passes unless (receiver == expected)
-  #
-  #   receiver.should_not === expected
-  #     => Passes unless (receiver === expected)
-  #
-  #   receiver.should_not =~ regexp
-  #     => Passes unless (receiver =~ regexp)
-  #
-  # See RSpec::Matchers for more information about matchers
+
+  # Passes if +matcher+ returns false.  Available on every +Object+.
+  # @example
+  #   actual.should_not eq(expected)
+  # @param [Matcher]
+  #   matcher
+  # @param [String] message optional message to display when the expectation fails
+  # @return [Boolean] false if the negative expectation succeeds (else raises)
+  # @see RSpec::Matchers
   def should_not(matcher=nil, message=nil, &block)
     RSpec::Expectations::NegativeExpectationHandler.handle_matcher(self, matcher, message, &block)
   end

data/lib/rspec/expectations/{backward_compatibility.rb → extensions/object.rb}

@@ -1,7 +1,8 @@
-# Cucumber 0.7 includes Rspec::Expectations
 module RSpec
   module Expectations
-    module ConstMissing
+    module DeprecatedConstants
+      # Displays deprecation warning when it captures Rspec and Spec. Otherwise
+      # delegates to super.
       def const_missing(name)
         case name
         when :Rspec, :Spec
@@ -28,10 +29,11 @@ WARNING
       end
     end
 
+    # @deprecated (no replacement)
     def differ=(ignore)
       RSpec.deprecate("RSpec::Expectations.differ=(differ)", "nothing at all (diffing is now automatic and no longer configurable)")
     end
   end
 end
 
-Object.extend(RSpec::Expectations::ConstMissing)
+extend RSpec::Expectations::DeprecatedConstants

data/lib/rspec/expectations/fail_with.rb

@@ -1,16 +1,19 @@
 module RSpec
   module Expectations
     class << self
+      # @private
       def differ
         @differ ||= Differ.new
       end
       
-      # raises a RSpec::Expectations::ExpectationNotMetError with message
+      # Raises an RSpec::Expectations::ExpectationNotMetError with message.
+      # @param [String] message
+      # @param [Object] expected
+      # @param [Object] actual
       #
-      # When a differ has been assigned and fail_with is passed
-      # <code>expected</code> and <code>actual</code>, passes them
-      # to the differ to append a diff message to the failure message.
-      def fail_with(message, expected=nil, actual=nil) # :nodoc:
+      # Adds a diff to the failure message when +expected+ and +actual+ are
+      # both present.
+      def fail_with(message, expected=nil, actual=nil)
         if !message
           raise ArgumentError, "Failure message is nil. Does your matcher define the " +
                                "appropriate failure_message_for_* method to return a string?"