rspec-expectations 2.12.1 → 2.13.0

data/Changelog.md

@@ -1,3 +1,34 @@
+### 2.13.0 / 2013-02-23
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.12.1...v2.13.0)
+
+Enhancements
+
+* Add support for percent deltas to `be_within` matcher:
+  `expect(value).to be_within(10).percent_of(expected)`
+  (Myron Marston).
+* Add support to `include` matcher to allow it to be given a list
+  of matchers as the expecteds to match against (Luke Redpath).
+
+Bug fixes
+
+* Fix `change` matcher so that it dups strings in order to handle
+  mutated strings (Myron Marston).
+* Fix `should be =~ /some regex/` / `expect(...).to be =~ /some regex/`.
+  Previously, these either failed with a confusing `undefined method
+  matches?' for false:FalseClass` error or were no-ops that didn't
+  actually verify anything (Myron Marston).
+* Add compatibility for diff-lcs 1.2 and relax the version
+  constraint (Peter Goldstein).
+* Fix DSL-generated matchers to allow multiple instances of the
+  same matcher in the same example to have different description
+  and failure messages based on the expected value (Myron Marston).
+* Prevent `undefined method #split for Array` error when dumping
+  the diff of an array of multiline strings (Myron Marston).
+* Don't blow up when comparing strings that are in an encoding
+  that is not ASCII compatible (Myron Marston).
+* Remove confusing "Check the implementation of #==" message
+  printed for empty diffs (Myron Marston).
+
 ### 2.12.1 / 2012-12-15
 [full changelog](http://github.com/rspec/rspec-expectations/compare/v2.12.0...v2.12.1)
 

data/README.md

@@ -1,4 +1,4 @@
-# RSpec Expectations [![Build Status](https://secure.travis-ci.org/rspec/rspec-expectations.png?branch=master)](http://travis-ci.org/rspec/rspec-expectations) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/rspec/rspec-expectations)
+# RSpec Expectations [![Build Status](https://secure.travis-ci.org/rspec/rspec-expectations.png?branch=master)](http://travis-ci.org/rspec/rspec-expectations) [![Code Climate](https://codeclimate.com/github/rspec/rspec-expectations.png)](https://codeclimate.com/github/rspec/rspec-expectations)
 
 RSpec::Expectations lets you express expected outcomes on an object in an
 example.

data/features/built_in_matchers/be.feature

@@ -2,10 +2,12 @@ Feature: "be" matchers
 
   There are several related "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 truthy (not nil or false)
+    ```ruby
+    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 truthy (not nil or false)
+    ```
 
   Scenario: be_true matcher
     Given a file named "be_true_spec.rb" with:

data/features/built_in_matchers/be_within.feature

@@ -13,7 +13,9 @@ Feature: be_within matcher
   Instead, you should use the be_within matcher to check that the value
   is within a delta of your expected value:
 
-      area_of_circle.should be_within(0.1).of(28.3)
+    ```ruby
+    area_of_circle.should be_within(0.1).of(28.3)
+    ```
 
   Note that the difference between the actual and expected values must be
   smaller than your delta; if it is equal, the matcher will fail.

data/features/built_in_matchers/cover.feature

@@ -5,9 +5,11 @@ Feature: cover matcher
   expected objects.  This works on any object that responds to #cover?  (such
   as a Range):
 
+    ```ruby
     (1..10).should cover(5)
     (1..10).should cover(4, 6)
     (1..10).should_not cover(11)
+    ```
 
   Scenario: range usage
     Given a file named "range_cover_matcher_spec.rb" with:

data/features/built_in_matchers/end_with.feature

@@ -3,9 +3,11 @@ Feature: end_with matcher
   Use the `end_with` matcher to specify that a string or array ends with the
   expected characters or elements.
 
+    ```ruby
     "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:

data/features/built_in_matchers/equality.feature

@@ -12,14 +12,18 @@ Feature: equality matchers
 
   rspec-expectations ships with matchers that align with each of these methods:
 
-      a.should equal(b) # passes if a.equal?(b)
-      a.should eql(b)   # passes if a.eql?(b)
-      a.should == b     # passes if a == b
+    ```ruby
+    a.should equal(b) # passes if a.equal?(b)
+    a.should eql(b)   # passes if a.eql?(b)
+    a.should == b     # passes if a == b
+    ```
 
   It also ships with two matchers that have more of a DSL feel to them:
 
-      a.should be(b) # passes if a.equal?(b)
-      a.should eq(b) # passes if a == b
+    ```ruby
+    a.should be(b) # passes if a.equal?(b)
+    a.should eq(b) # passes if a == b
+    ```
 
   These are a useful pair if you wish to avoid the warning that Ruby emits on
   `a.should == b`
@@ -27,8 +31,6 @@ Feature: equality matchers
   Scenario: compare using eq (==)
     Given a file named "compare_using_eq.rb" with:
       """ruby
-      require 'spec_helper'
-
       describe "a string" do
         it "is equal to another string of the same value" do
           "this string".should eq("this string")
@@ -51,8 +53,6 @@ Feature: equality matchers
   Scenario: compare using ==
     Given a file named "compare_using_==.rb" with:
       """ruby
-      require 'spec_helper'
-
       describe "a string" do
         it "is equal to another string of the same value" do
           "this string".should == "this string"
@@ -75,8 +75,6 @@ Feature: equality matchers
   Scenario: compare using eql (eql?)
     Given a file named "compare_using_eql.rb" with:
       """ruby
-      require 'spec_helper'
-
       describe "an integer" do
         it "is equal to another integer of the same value" do
           5.should eql(5)
@@ -98,8 +96,6 @@ Feature: equality matchers
   Scenario: compare using equal (equal?)
     Given a file named "compare_using_equal.rb" with:
       """ruby
-      require 'spec_helper'
-
       describe "a string" do
         it "is equal to itself" do
           string = "this string"
@@ -122,8 +118,6 @@ Feature: equality matchers
   Scenario: compare using be (equal?)
     Given a file named "compare_using_be.rb" with:
       """ruby
-      require 'spec_helper'
-
       describe "a string" do
         it "is equal to itself" do
           string = "this string"

data/features/built_in_matchers/exist.feature

@@ -3,7 +3,9 @@ Feature: exist matcher
   The exist matcher is used to specify that something exists
   (as indicated by #exist? or #exists?):
 
+    ```ruby
     obj.should exist # passes if obj.exist? or obj.exists?
+    ```
 
   Scenario: basic usage
     Given a file named "exist_matcher_spec.rb" with:

data/features/built_in_matchers/expect_error.feature

@@ -3,11 +3,15 @@ Feature: raise_error matcher
   Use the `raise_error` matcher to specify that a block of code raises an
   error. The most basic form passes if any error is thrown:
 
-      expect { raise StandardError }.to raise_error
+    ```ruby
+    expect { raise StandardError }.to raise_error
+    ```
 
   You can use `raise_exception` instead if you prefer that wording:
 
-      expect { 3 / 0 }.to raise_exception
+    ```ruby
+    expect { 3 / 0 }.to raise_exception
+    ```
 
   `raise_error` and `raise_exception` are functionally interchangeable, so use
   the one that makes the most sense to you in any given context.
@@ -15,12 +19,14 @@ 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/)
+    ```ruby
+    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 "example_spec" with:

data/features/built_in_matchers/have.feature

@@ -3,9 +3,11 @@ Feature: have(n).items matcher
   RSpec provides several matchers that make it easy to set expectations about the
   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
+    ```ruby
+    collection.should have(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.
 
@@ -14,14 +16,18 @@ Feature: have(n).items matcher
   the #items call is pure syntactic sugar.  You can use anything you want here.  These
   are equivalent:
 
-    * collection.should have(x).items
-    * collection.should have(x).things
+    ```ruby
+    collection.should have(x).items
+    collection.should have(x).things
+    ```
 
   You can also use this matcher on a non-collection object that returns a collection
   from one of its methods.  For example, Dir#entries returns an array, so you could
   set an expectation using the following:
 
+    ```ruby
     Dir.new("my/directory").should have(7).entries
+    ```
 
   Scenario: have(x).items on a collection
     Given a file named "have_items_spec.rb" with:

data/features/built_in_matchers/include.feature

@@ -4,6 +4,7 @@ Feature: include matcher
   expected objects.  This works on any object that responds to #include?  (such
   as a string or array):
 
+    ```ruby
     "a string".should include("a")
     "a string".should include("str")
     "a string".should include("str", "g")
@@ -12,9 +13,11 @@ Feature: include matcher
     [1, 2].should include(1)
     [1, 2].should include(1, 2)
     [1, 2].should_not include(17)
+    ```
 
   The matcher also provides flexible handling for hashes:
 
+    ```ruby
     {:a => 1, :b => 2}.should include(:a)
     {:a => 1, :b => 2}.should include(:a, :b)
     {:a => 1, :b => 2}.should include(:a => 1)
@@ -22,6 +25,7 @@ Feature: include matcher
     {:a => 1, :b => 2}.should_not include(:c)
     {:a => 1, :b => 2}.should_not include(:a => 2)
     {:a => 1, :b => 2}.should_not include(:c => 3)
+    ```
 
   Scenario: array usage
     Given a file named "array_include_matcher_spec.rb" with:
@@ -119,3 +123,52 @@ Feature: include matcher
       """
     When I run `rspec hash_include_matcher_spec.rb`
     Then the output should contain "13 failure"
+
+  Scenario: fuzzy usage with matchers
+    Given a file named "fuzzy_include_matcher_spec.rb" with:
+      """
+      require 'ostruct'
+
+      class User < OpenStruct
+        def inspect
+          name
+        end
+      end
+
+      RSpec::Matchers.define :a_user_named do |expected|
+        match do |actual|
+          actual.is_a?(User) && (actual.name == expected)
+        end
+        description do
+          "a user named '#{expected}'"
+        end
+      end
+
+      describe "Collection of users" do
+        subject do
+          [User.new(:name => "Joe"),
+           User.new(:name => "Fred"),
+           User.new(:name => "John"),
+           User.new(:name => "Luke"),
+           User.new(:name => "David")]
+        end
+
+        it { should include( a_user_named "Joe" ) }
+        it { should include( a_user_named "Luke" ) }
+        it { should_not include( a_user_named "Richard" ) }
+        it { should_not include( a_user_named "Hayley" ) }
+
+        # deliberate failures
+        it { should include( a_user_named "Richard" ) }
+        it { should_not include( a_user_named "Fred" ) }
+        it { should include( a_user_named "Sarah" ) }
+        it { should_not include( a_user_named "Luke" ) }
+      end
+      """
+    When I run `rspec fuzzy_include_matcher_spec.rb`
+    Then the output should contain all of these:
+      | 8 examples, 4 failures                                                     |
+      | expected [Joe, Fred, John, Luke, David] to include a user named 'Richard'  |
+      | expected [Joe, Fred, John, Luke, David] not to include a user named 'Fred' |
+      | expected [Joe, Fred, John, Luke, David] to include a user named 'Sarah'    |
+      | expected [Joe, Fred, John, Luke, David] not to include a user named 'Luke' |

data/features/built_in_matchers/match.feature

@@ -4,10 +4,12 @@ Feature: match matcher
   truthy (not false or nil) value.  Regexp and String both provide a #match
   method.
 
+    ```ruby
     "a string".should match(/str/) # passes
     "a string".should match(/foo/) # fails
     /foo/.should match("food")     # passes
     /foo/.should match("drinks")   # fails
+    ```
 
   This is equivalent to using the =~ matcher (see the operator matchers
   feature for more details).

data/features/built_in_matchers/operators.feature

@@ -4,25 +4,31 @@ Feature: operator matchers
   operators. These pretty much work like you expect. For example, each of these
   pass:
 
-      7.should == 7
-      [1, 2, 3].should == [1, 2, 3]
-      "this is a string".should =~ /^this/
-      "this is a string".should_not =~ /^that/
-      String.should === "this is a string"
+    ```ruby
+    7.should == 7
+    [1, 2, 3].should == [1, 2, 3]
+    "this is a string".should =~ /^this/
+    "this is a string".should_not =~ /^that/
+    String.should === "this is a string"
+    ```
 
   You can also use comparison operators combined with the "be" matcher like
   this:
 
-      37.should be < 100
-      37.should be <= 38
-      37.should be >= 2
-      37.should be > 7
+    ```ruby
+    37.should be < 100
+    37.should be <= 38
+    37.should be >= 2
+    37.should be > 7
+    ```
 
   RSpec also provides a `=~` matcher for arrays that disregards differences in
   the ording between the actual and expected array.  For example:
 
-      [1, 2, 3].should =~ [2, 3, 1] # pass
-      [:a, :c, :b].should =~ [:a, :c] # fail
+    ```ruby
+    [1, 2, 3].should =~ [2, 3, 1] # pass
+    [:a, :c, :b].should =~ [:a, :c] # fail
+    ```
 
   Scenario: numeric operator matchers
     Given a file named "numeric_operator_matchers_spec.rb" with:

data/features/built_in_matchers/predicates.feature

@@ -2,16 +2,20 @@ Feature: predicate matchers
 
   Ruby objects commonly provide predicate methods:
 
-      7.zero?                  # => false
-      0.zero?                  # => true
-      [1].empty?               # => false
-      [].empty?                # => true
-      { :a => 5 }.has_key?(:b) # => false
-      { :b => 5 }.has_key?(:b) # => true
+    ```ruby
+    7.zero?                  # => false
+    0.zero?                  # => true
+    [1].empty?               # => false
+    [].empty?                # => true
+    { :a => 5 }.has_key?(:b) # => false
+    { :b => 5 }.has_key?(:b) # => true
+    ```
 
   You could use a basic equality matcher to set expectations on these:
 
-      7.zero?.should == true # fails with "expected true, got false (using ==)"
+    ```ruby
+    7.zero?.should == true # fails with "expected true, got false (using ==)"
+    ```
 
   ...but RSpec provides dynamic predicate matchers that are more readable and
   provide better failure output.
@@ -19,20 +23,24 @@ Feature: predicate matchers
   For any predicate method, RSpec gives you a corresponding matcher.  Simply
   prefix the method with `be_` and remove the question mark.  Examples:
 
-      7.should_not be_zero       # calls 7.zero?
-      [].should be_empty         # calls [].empty?
-      x.should be_multiple_of(3) # calls x.multiple_of?(3)
+    ```ruby
+    7.should_not be_zero       # calls 7.zero?
+    [].should be_empty         # calls [].empty?
+    x.should be_multiple_of(3) # calls x.multiple_of?(3)
+    ```
 
   Alternately, for a predicate method that begins with `has_` like
   `Hash#has_key?`, RSpec allows you to use an alternate form since `be_has_key`
   makes no sense.
 
-      hash.should have_key(:foo)       # calls hash.has_key?(:foo)
-      array.should_not have_odd_values # calls array.has_odd_values?
+    ```ruby
+    hash.should have_key(:foo)       # calls hash.has_key?(:foo)
+    array.should_not have_odd_values # calls array.has_odd_values?
+    ```
 
   In either case, RSpec provides nice, clear error messages, such as:
 
-      expected zero? to return true, got false
+    `expected zero? to return true, got false`
 
   Any arguments passed to the matcher will be passed on to the predicate method.
 

data/features/built_in_matchers/respond_to.feature

@@ -3,18 +3,24 @@ Feature: respond_to matcher
   Use the respond_to matcher to specify details of an object's interface.  In
   its most basic form:
 
+    ```ruby
     obj.should respond_to(:foo) # pass if obj.respond_to?(:foo)
+    ```
 
   You can specify that an object responds to multiple messages in a single
   statement with multiple arguments passed to the matcher:
-    
+
+    ```ruby
     obj.should respond_to(:foo, :bar) # passes if obj.respond_to?(:foo) && obj.respond_to?(:bar)
+    ```
 
   If the number of arguments accepted by the method is important to you,
   you can specify that as well:
 
+    ```ruby
     obj.should respond_to(:foo).with(1).argument
     obj.should respond_to(:bar).with(2).arguments
+    ```
 
   Note that this matcher relies entirely upon #respond_to?.  If an object
   dynamically responds to a message via #method_missing, but does not indicate