rspec-expectations 2.9.1 → 2.10.0

data/.yardopts

@@ -1,3 +1,6 @@
---no-private
 --exclude features
+--no-private
 --markup markdown
+-
+Changelog.md
+License.txt

data/Changelog.md

@@ -1,5 +1,23 @@
+### 2.10.0 / 2012-05-03
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.9.1...v2.10.0)
+
+Enhancements
+
+* Add new `start_with` and `end_with` matchers (Jeremy Wadsack)
+* Add new matchers for specifying yields (Myron Marson):
+    * `expect {...}.to yield_control`
+    * `expect {...}.to yield_with_args(1, 2, 3)`
+    * `expect {...}.to yield_with_no_args`
+    * `expect {...}.to yield_successive_args(1, 2, 3)`
+* `match_unless_raises` takes multiple exception args
+
+Bug fixes
+
+* Fix `be_within` matcher to be inclusive of delta.
+* Fix message-specific specs to pass on Rubinius (John Firebaugh)
+
 ### 2.9.1 / 2012-04-03
-[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.9.0...2.9.1)
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.9.0...v2.9.1)
 
 Bug fixes
 

data/README.md

@@ -112,6 +112,21 @@ expect { ... }.to throw_symbol(:symbol)
 expect { ... }.to throw_symbol(:symbol, 'value')
 ```
 
+### Yielding
+
+```ruby
+expect { |b| 5.tap(&b) }.to yield_control # passes regardless of yielded args
+
+expect { |b| yield_if_true(true, &b) }.to yield_with_no_args # passes only if no args are yielded
+
+expect { |b| 5.tap(&b) }.to yield_with_args(5)
+expect { |b| 5.tap(&b) }.to yield_with_args(Fixnum)
+expect { |b| "a string".tap(&b) }.to yield_with_args(/str/)
+
+expect { |b| [1, 2, 3].each(&b) }.to yield_successive_args(1, 2, 3)
+expect { |b| { :a => 1, :b => 2 }.each(&b) }.to yield_successive_args([:a, 1], [:b, 2])
+```
+
 ### Predicate matchers
 
 ```ruby
@@ -129,6 +144,8 @@ actual.should have_xxx(:arg) # passes if actual.has_xxx?(:arg)
 
 ```ruby
 actual.should include(expected)
+actual.should start_with(expected)
+actual.should end_with(expected)
 ```
 
 #### Examples
@@ -136,8 +153,14 @@ actual.should include(expected)
 ```ruby
 [1,2,3].should include(1)
 [1,2,3].should include(1, 2)
+[1,2,3].should start_with(1)
+[1,2,3].should start_with(1,2)
+[1,2,3].should end_with(3)
+[1,2,3].should end_with(2,3)
 {:a => 'b'}.should include(:a => 'b')
 "this string".should include("is str")
+"this string".should start_with("this")
+"this string".should end_with("ring")
 ```
 
 ## Also see

data/features/built_in_matchers/be_within.feature

@@ -23,21 +23,24 @@ Feature: be_within matcher
       """
       describe 27.5 do
         it { should be_within(0.5).of(27.9) }
+        it { should be_within(0.5).of(28.0) }
         it { should be_within(0.5).of(27.1) }
-        it { should_not be_within(0.5).of(28) }
-        it { should_not be_within(0.5).of(27) }
+        it { should be_within(0.5).of(27.0) }
+
+        it { should_not be_within(0.5).of(28.1) }
+        it { should_not be_within(0.5).of(26.9) }
 
         # deliberate failures
-        it { should_not be_within(0.5).of(27.9) }
-        it { should_not be_within(0.5).of(27.1) }
-        it { should be_within(0.5).of(28) }
-        it { should be_within(0.5).of(27) }
+        it { should_not be_within(0.5).of(28) }
+        it { should_not be_within(0.5).of(27) }
+        it { should be_within(0.5).of(28.1) }
+        it { should be_within(0.5).of(26.9) }
       end
       """
     When I run `rspec be_within_matcher_spec.rb`
     Then the output should contain all of these:
-      | 8 examples, 4 failures                     |
-      | expected 27.5 not to be within 0.5 of 27.9 |
-      | expected 27.5 not to be within 0.5 of 27.1 |
-      | expected 27.5 to be within 0.5 of 28       |
-      | expected 27.5 to be within 0.5 of 27       |
+      | 10 examples, 4 failures                     |
+      | expected 27.5 not to be within 0.5 of 28   |
+      | expected 27.5 not to be within 0.5 of 27   |
+      | expected 27.5 to be within 0.5 of 28.1     |
+      | expected 27.5 to be within 0.5 of 26.9     |

data/features/built_in_matchers/end_with.feature

@@ -0,0 +1,46 @@
+Feature: end_with matcher
+
+  Use the `end_with` matcher to specify that a string or array ends with the
+  expected characters or elements.
+
+    "this string".should end_with "string"
+    "this string".should_not end_with "stringy"
+    [0, 1, 2].should end_with 1, 2
+
+  Scenario: string usage
+    Given a file named "example_spec.rb" with:
+      """
+      describe "this string" do
+        it { should end_with "string" }
+        it { should_not end_with "stringy" }
+
+        # deliberate failures
+        it { should_not end_with "string" }
+        it { should end_with "stringy" }
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the output should contain all of these:
+      | 4 examples, 2 failures                          |
+      | expected "this string" not to end with "string" |
+      | expected "this string" to end with "stringy"    |
+
+  Scenario: array usage
+    Given a file named "example_spec.rb" with:
+      """
+      describe [0, 1, 2, 3, 4] do
+        it { should end_with 4 }
+        it { should end_with 3, 4 }
+        it { should_not end_with 3 }
+        it { should_not end_with 0, 1, 2, 3, 4, 5 }
+
+        # deliberate failures
+        it { should_not end_with 4 }
+        it { should end_with 3 }
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the output should contain all of these:
+      | 6 examples, 2 failures                     |
+      | expected [0, 1, 2, 3, 4] not to end with 4 |
+      | expected [0, 1, 2, 3, 4] to end with 3     |

data/features/built_in_matchers/start_with.feature

@@ -0,0 +1,46 @@
+Feature: start_with matcher
+
+  Use the `start_with` matcher to specify that a string or array starts with 
+  the expected characters or elements.
+
+    "this string".should start_with("this")
+    "this string".should_not start_with("that")
+    [0,1,2].should start_with(0, 1)
+
+  Scenario: with a string
+    Given a file named "example_spec.rb" with:
+      """
+      describe "this string" do
+        it { should start_with "this" }
+        it { should_not start_with "that" }
+
+        # deliberate failures
+        it { should_not start_with "this" }
+        it { should start_with "that" }
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the output should contain all of these:
+      | 4 examples, 2 failures                          |
+      | expected "this string" not to start with "this" |
+      | expected "this string" to start with "that"     |
+
+  Scenario: with an array
+    Given a file named "example_spec.rb" with:
+      """
+      describe [0, 1, 2, 3, 4] do
+        it { should start_with 0 }
+        it { should start_with(0, 1)}
+        it { should_not start_with(2) }
+        it { should_not start_with(0, 1, 2, 3, 4, 5) }
+
+        # deliberate failures
+        it { should_not start_with 0 }
+        it { should start_with 3 }
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the output should contain all of these:
+      | 6 examples, 2 failures                       |
+      | expected [0, 1, 2, 3, 4] not to start with 0 |
+      | expected [0, 1, 2, 3, 4] to start with 3     |

data/features/built_in_matchers/yield.feature

@@ -0,0 +1,146 @@
+Feature: yield matchers
+
+  There are four related matchers that allow you to specify whether
+  or not a method yields, how many times it yields, whether or not
+  it yields with arguments, and what those arguments are.
+
+    * `yield_control` matches if the method-under-test yields, regardless
+      of whether or not arguments are yielded.
+    * `yield_with_args` matches if the method-under-test yields with
+      arguments. If arguments are provided to this matcher, it will
+      only pass if the actual yielded arguments match the expected ones
+      using `===` or `==`.
+    * `yield_with_no_args` matches if the method-under-test yields with
+      no arguments.
+    * `yield_successive_args` is designed for iterators, and will match
+      if the method-under-test yields the same number of times as arguments
+      passed to this matcher, and all actual yielded arguments match the
+      expected ones using `===` or `==`.
+
+  Note: your expect block _must_ accept an argument that is then passed on to
+  the method-under-test as a block. This acts as a "probe" that allows the matcher
+  to detect whether or not your method yields, and, if so, how many times and what
+  the yielded arguments are.
+
+  Background:
+    Given a file named "my_class.rb" with:
+      """
+      class MyClass
+        def self.yield_once_with(*args)
+          yield *args
+        end
+
+        def self.raw_yield
+          yield
+        end
+
+        def self.dont_yield
+        end
+      end
+      """
+
+  Scenario: yield_control matcher
+    Given a file named "yield_control_spec.rb" with:
+      """
+      require './my_class'
+
+      describe "yield_control matcher" do
+        specify { expect { |b| MyClass.yield_once_with(1, &b) }.to yield_control }
+        specify { expect { |b| MyClass.dont_yield(&b) }.not_to yield_control }
+
+        # deliberate failures
+        specify { expect { |b| MyClass.yield_once_with(1, &b) }.not_to yield_control }
+        specify { expect { |b| MyClass.dont_yield(&b) }.to yield_control }
+      end
+      """
+    When I run `rspec yield_control_spec.rb`
+    Then the output should contain all of these:
+      | 4 examples, 2 failures                      |
+      | expected given block to yield control       |
+      | expected given block not to yield control   |
+
+  Scenario: yield_with_args matcher
+    Given a file named "yield_with_args_spec.rb" with:
+      """
+      require './my_class'
+
+      describe "yield_with_args matcher" do
+        specify { expect { |b| MyClass.yield_once_with("foo", &b) }.to yield_with_args }
+        specify { expect { |b| MyClass.yield_once_with("foo", &b) }.to yield_with_args("foo") }
+        specify { expect { |b| MyClass.yield_once_with("foo", &b) }.to yield_with_args(String) }
+        specify { expect { |b| MyClass.yield_once_with("foo", &b) }.to yield_with_args(/oo/) }
+
+        specify { expect { |b| MyClass.yield_once_with("foo", "bar", &b) }.to yield_with_args("foo", "bar") }
+        specify { expect { |b| MyClass.yield_once_with("foo", "bar", &b) }.to yield_with_args(String, String) }
+        specify { expect { |b| MyClass.yield_once_with("foo", "bar", &b) }.to yield_with_args(/fo/, /ar/) }
+
+        specify { expect { |b| MyClass.yield_once_with("foo", "bar", &b) }.not_to yield_with_args(17, "baz") }
+
+        # deliberate failures
+        specify { expect { |b| MyClass.yield_once_with("foo", &b) }.not_to yield_with_args }
+        specify { expect { |b| MyClass.yield_once_with("foo", &b) }.not_to yield_with_args("foo") }
+        specify { expect { |b| MyClass.yield_once_with("foo", &b) }.not_to yield_with_args(String) }
+        specify { expect { |b| MyClass.yield_once_with("foo", &b) }.not_to yield_with_args(/oo/) }
+        specify { expect { |b| MyClass.yield_once_with("foo", "bar", &b) }.not_to yield_with_args("foo", "bar") }
+        specify { expect { |b| MyClass.yield_once_with("foo", "bar", &b) }.to yield_with_args(17, "baz") }
+      end
+      """
+    When I run `rspec yield_with_args_spec.rb`
+    Then the output should contain all of these:
+      | 14 examples, 6 failures                                                               |
+      | expected given block not to yield with arguments, but did                             |
+      | expected given block not to yield with arguments, but yielded with expected arguments |
+      | expected given block to yield with arguments, but yielded with unexpected arguments   |
+
+  Scenario: yield_with_no_args matcher
+    Given a file named "yield_with_no_args_spec.rb" with:
+      """
+      require './my_class'
+
+      describe "yield_with_no_args matcher" do
+        specify { expect { |b| MyClass.raw_yield(&b) }.to yield_with_no_args }
+        specify { expect { |b| MyClass.dont_yield(&b) }.not_to yield_with_no_args }
+        specify { expect { |b| MyClass.yield_once_with("a", &b) }.not_to yield_with_no_args }
+
+        # deliberate failures
+        specify { expect { |b| MyClass.raw_yield(&b) }.not_to yield_with_no_args }
+        specify { expect { |b| MyClass.dont_yield(&b) }.to yield_with_no_args }
+        specify { expect { |b| MyClass.yield_once_with("a", &b) }.to yield_with_no_args }
+      end
+      """
+    When I run `rspec yield_with_no_args_spec.rb`
+    Then the output should contain all of these:
+      | 6 examples, 3 failures                                                             |
+      | expected given block not to yield with no arguments, but did                       |
+      | expected given block to yield with no arguments, but did not yield                 |
+      | expected given block to yield with no arguments, but yielded with arguments: ["a"] |
+
+  Scenario: yield_successive_args matcher
+    Given a file named "yield_successive_args_spec.rb" with:
+      """
+      def array
+        [1, 2, 3]
+      end
+
+      def array_of_tuples
+        [[:a, :b], [:c, :d]]
+      end
+
+      describe "yield_successive_args matcher" do
+        specify { expect { |b| array.each(&b) }.to yield_successive_args(1, 2, 3) }
+        specify { expect { |b| array_of_tuples.each(&b) }.to yield_successive_args([:a, :b], [:c, :d]) }
+        specify { expect { |b| array.each(&b) }.to yield_successive_args(Fixnum, Fixnum, Fixnum) }
+        specify { expect { |b| array.each(&b) }.not_to yield_successive_args(1, 2) }
+
+        # deliberate failures
+        specify { expect { |b| array.each(&b) }.not_to yield_successive_args(1, 2, 3) }
+        specify { expect { |b| array_of_tuples.each(&b) }.not_to yield_successive_args([:a, :b], [:c, :d]) }
+        specify { expect { |b| array.each(&b) }.not_to yield_successive_args(Fixnum, Fixnum, Fixnum) }
+        specify { expect { |b| array.each(&b) }.to yield_successive_args(1, 2) }
+      end
+      """
+    When I run `rspec yield_successive_args_spec.rb`
+    Then the output should contain all of these:
+      | 8 examples, 4 failures                                                                             |
+      | expected given block not to yield successively with arguments, but yielded with expected arguments |
+      | expected given block to yield successively with arguments, but yielded with unexpected arguments   |

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '2.9.1'
+      STRING = '2.10.0'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -355,6 +355,20 @@ module RSpec
       BuiltIn::Cover.new(*values)
     end if (1..2).respond_to?(:cover?)
 
+    # Matches if the actual value ends with the expected value(s). In the case
+    # of a string, matches against the last `expected.length` characters of the
+    # actual string. In the case of an array, matches against the last
+    # `expected.length` elements of the actual array.
+    #
+    # @example
+    #
+    #   "this string".should end_with "string"
+    #   [0, 1, 2, 3, 4].should end_with 4
+    #   [0, 2, 3, 4, 4].should end_with 3, 4
+    def end_with(*expected)
+      BuiltIn::EndWith.new(*expected)
+    end
+
     # Passes if <tt>actual == expected</tt>.
     #
     # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
@@ -534,6 +548,20 @@ module RSpec
       BuiltIn::Satisfy.new(&block)
     end
 
+    # Matches if the actual value starts with the expected value(s). In the
+    # case of a string, matches against the first `expected.length` characters
+    # of the actual string. In the case of an array, matches against the first
+    # `expected.length` elements of the actual array.
+    #
+    # @example
+    #
+    #   "this string".should start_with "this s"
+    #   [0, 1, 2, 3, 4].should start_with 0
+    #   [0, 2, 3, 4, 4].should start_with 0, 1
+    def start_with(*expected)
+      BuiltIn::StartWith.new(*expected)
+    end
+
     # Given no argument, matches if a proc throws any Symbol.
     #
     # Given a Symbol, matches if the given proc throws the specified Symbol.
@@ -554,6 +582,88 @@ module RSpec
       BuiltIn::ThrowSymbol.new(expected_symbol, expected_arg)
     end
 
+    # Passes if the method called in the expect block yields, regardless
+    # of whether or not arguments are yielded.
+    #
+    # @example
+    #
+    #   expect { |b| 5.tap(&b) }.to yield_control
+    #   expect { |b| "a".to_sym(&b) }.not_to yield_control
+    #
+    # @note Your expect block must accept a parameter and pass it on to
+    #   the method-under-test as a block.
+    # @note This matcher is not designed for use with methods that yield
+    #   multiple times.
+    def yield_control
+      BuiltIn::YieldControl.new
+    end
+
+    # Passes if the method called in the expect block yields with
+    # no arguments. Fails if it does not yield, or yields with arguments.
+    #
+    # @example
+    #
+    #   expect { |b| User.transaction(&b) }.to yield_with_no_args
+    #   expect { |b| 5.tap(&b) }.not_to yield_with_no_args # because it yields with `5`
+    #   expect { |b| "a".to_sym(&b) }.not_to yield_with_no_args # because it does not yield
+    #
+    # @note Your expect block must accept a parameter and pass it on to
+    #   the method-under-test as a block.
+    # @note This matcher is not designed for use with methods that yield
+    #   multiple times.
+    def yield_with_no_args
+      BuiltIn::YieldWithNoArgs.new
+    end
+
+    # Given no arguments, matches if the method called in the expect
+    # block yields with arguments (regardless of what they are or how
+    # many there are).
+    #
+    # Given arguments, matches if the method called in the expect block
+    # yields with arguments that match the given arguments.
+    #
+    # Argument matching is done using `===` (the case match operator)
+    # and `==`. If the expected and actual arguments match with either
+    # operator, the matcher will pass.
+    #
+    # @example
+    #
+    #   expect { |b| 5.tap(&b) }.to yield_with_args # because #tap yields an arg
+    #   expect { |b| 5.tap(&b) }.to yield_with_args(5) # because 5 == 5
+    #   expect { |b| 5.tap(&b) }.to yield_with_args(Fixnum) # because Fixnum === 5
+    #   expect { |b| File.open("f.txt", &b) }.to yield_with_args(/txt/) # because /txt/ === "f.txt"
+    #
+    #   expect { |b| User.transaction(&b) }.not_to yield_with_args # because it yields no args
+    #   expect { |b| 5.tap(&b) }.not_to yield_with_args(1, 2, 3)
+    #
+    # @note Your expect block must accept a parameter and pass it on to
+    #   the method-under-test as a block.
+    # @note This matcher is not designed for use with methods that yield
+    #   multiple times.
+    def yield_with_args(*args)
+      BuiltIn::YieldWithArgs.new(*args)
+    end
+
+    # Designed for use with methods that repeatedly yield (such as
+    # iterators). Passes if the method called in the expect block yields
+    # multiple times with arguments matching those given.
+    #
+    # Argument matching is done using `===` (the case match operator)
+    # and `==`. If the expected and actual arguments match with either
+    # operator, the matcher will pass.
+    #
+    # @example
+    #
+    #   expect { |b| [1, 2, 3].each(&b) }.to yield_successive_args(1, 2, 3)
+    #   expect { |b| { :a => 1, :b => 2 }.each(&b) }.to yield_successive_args([:a, 1], [:b, 2])
+    #   expect { |b| [1, 2, 3].each(&b) }.not_to yield_successive_args(1, 2)
+    #
+    # @note Your expect block must accept a parameter and pass it on to
+    #   the method-under-test as a block.
+    def yield_successive_args(*args)
+      BuiltIn::YieldSuccessiveArgs.new(*args)
+    end
+
     # Passes if actual contains all of the expected regardless of order. 
     # This works for collections. Pass in multiple args  and it will only 
     # pass if all args are found in collection.