rspec-expectations 2.0.0.beta.22 → 2.6.0

data/features/built_in_matchers/cover.feature

@@ -0,0 +1,45 @@
+@ruby-1.9
+Feature: cover matcher
+
+  Use the cover matcher to specify that a range covers one or more
+  expected objects.  This works on any object that responds to #cover?  (such
+  as a Range):
+
+    (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:
+      """
+      describe (1..10) do
+        it { should cover(4) }
+        it { should cover(6) }
+        it { should cover(8) }
+        it { should cover(4, 6) }
+        it { should cover(4, 6, 8) }
+        it { should_not cover(11) }
+        it { should_not cover(11, 12) }
+
+        # deliberate failures
+        it { should cover(11) }
+        it { should_not cover(4) }
+        it { should_not cover(6) }
+        it { should_not cover(8) }
+        it { should_not cover(4, 6, 8) }
+
+        # both of these should fail since it covers 1 but not 9
+        it { should cover(5, 11) }
+        it { should_not cover(5, 11) }
+      end
+      """
+    When I run `rspec range_cover_matcher_spec.rb`
+    Then the output should contain all of these:
+      | 14 examples, 7 failures                 |
+      | expected 1..10 to cover 11              |
+      | expected 1..10 not to cover 4           |
+      | expected 1..10 not to cover 6           |
+      | expected 1..10 not to cover 8           |
+      | expected 1..10 not to cover 4, 6, and 8 |
+      | expected 1..10 to cover 5 and 11        |
+      | expected 1..10 not to cover 5 and 11    |

data/features/{matchers → built_in_matchers}/equality.feature

@@ -2,9 +2,9 @@ Feature: equality matchers
 
   Ruby exposes several different methods for handling equality:
 
-    a.equal?(b) # object identity - a and b refer to the same object
-    a.eql?(b)   # object equivalence - a and b have the same value
-    a == b      # object equivalence - a and b have the same value with type conversions
+      a.equal?(b) # object identity - a and b refer to the same object
+      a.eql?(b)   # object equivalence - a and b have the same value
+      a == b      # object equivalence - a and b have the same value with type conversions
 
   Note that these descriptions are guidelines but are not forced by the
   language. Any object can implement any of these methods with its own
@@ -12,14 +12,17 @@ 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
+      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
+      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`
 
   Scenario: compare using eq (==)
     Given a file named "compare_using_eq.rb" with:
@@ -42,7 +45,7 @@ Feature: equality matchers
         end
       end
       """
-    When I run "rspec compare_using_eq.rb"
+    When I run `rspec compare_using_eq.rb`
     Then the output should contain "3 examples, 0 failures"
 
   Scenario: compare using ==
@@ -66,7 +69,7 @@ Feature: equality matchers
         end
       end
       """
-    When I run "rspec compare_using_==.rb"
+    When I run `rspec compare_using_==.rb`
     Then the output should contain "3 examples, 0 failures"
 
   Scenario: compare using eql (eql?)
@@ -89,7 +92,7 @@ Feature: equality matchers
 
       end
       """
-    When I run "rspec compare_using_eql.rb"
+    When I run `rspec compare_using_eql.rb`
     Then the output should contain "3 examples, 0 failures"
 
   Scenario: compare using equal (equal?)
@@ -113,7 +116,7 @@ Feature: equality matchers
 
       end
       """
-    When I run "rspec compare_using_equal.rb"
+    When I run `rspec compare_using_equal.rb`
     Then the output should contain "3 examples, 0 failures"
 
   Scenario: compare using be (equal?)
@@ -137,6 +140,6 @@ Feature: equality matchers
 
       end
       """
-    When I run "rspec compare_using_be.rb"
+    When I run `rspec compare_using_be.rb`
     Then the output should contain "3 examples, 0 failures"
 

data/features/built_in_matchers/exist.feature

@@ -0,0 +1,43 @@
+Feature: exist matcher
+
+  The exist matcher is used to specify that something exists
+  (as indicated by #exist? or #exists?):
+
+    obj.should exist # passes if obj.exist? or obj.exists?
+
+  Scenario: basic usage
+    Given a file named "exist_matcher_spec.rb" with:
+      """
+      class Planet
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        def inspect
+          "<Planet: #{name}>"
+        end
+
+        def exist? # also works with exists?
+          %w[Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune].include?(name)
+        end
+      end
+
+      describe "Earth" do
+        let(:earth) { Planet.new("Earth") }
+        specify { earth.should exist }
+        specify { earth.should_not exist } # deliberate failure
+      end
+
+      describe "Tatooine" do
+        let(:tatooine) { Planet.new("Tatooine") }
+        it { tatooine.should exist } # deliberate failure
+        it { tatooine.should_not exist }
+      end
+      """
+    When I run `rspec exist_matcher_spec.rb`
+    Then the output should contain all of these:
+      | 4 examples, 2 failures                |
+      | expected <Planet: Earth> not to exist |
+      | expected <Planet: Tatooine> to exist  |

data/features/built_in_matchers/expect_change.feature

@@ -0,0 +1,59 @@
+Feature: expect change
+
+  Expect the execution of a block of code to change the state of an object.
+
+  Background:
+    Given a file named "lib/counter.rb" with:
+      """
+      class Counter
+        class << self
+          def increment
+            @count ||= 0
+            @count += 1
+          end
+          
+          def count
+            @count ||= 0
+          end
+        end
+      end
+      """
+  
+  Scenario: expect change
+    Given a file named "spec/example_spec.rb" with:
+      """
+      require "counter"
+
+      describe Counter, "#increment" do
+        it "should increment the count" do
+          expect { Counter.increment }.to change{Counter.count}.from(0).to(1)
+        end
+
+        # deliberate failure
+        it "should increment the count by 2" do
+          expect { Counter.increment }.to change{Counter.count}.by(2)
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should contain "1 failure"
+    Then the output should contain "should have been changed by 2, but was changed by 1"
+
+  Scenario: expect no change
+    Given a file named "spec/example_spec.rb" with:
+      """
+      require "counter"
+
+      describe Counter, "#increment" do
+        it "should not increment the count by 1 (using to_not)" do
+          expect { Counter.increment }.to_not change{Counter.count}
+        end
+
+        it "should not increment the count by 1 (using not_to)" do
+          expect { Counter.increment }.not_to change{Counter.count}
+        end
+      end
+      """
+    When I run `rspec spec/example_spec.rb`
+    Then the output should contain "2 failures"
+    Then the output should contain "should not have changed, but did change from 1 to 2"

data/features/built_in_matchers/expect_error.feature

@@ -0,0 +1,105 @@
+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
+
+  You can use `raise_exception` instead if you prefer that wording:
+
+      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.
+
+  In addition to the basic form, above, there are a number of ways to specify
+  details of an error/exception:
+
+  Scenario: expect any error
+    Given a file named "expect_error_spec.rb" with:
+      """
+      describe "calling a method that does not exist" do
+        it "raises" do
+          expect { Object.new.foo }.to raise_error
+        end
+      end
+      """
+    When I run `rspec expect_error_spec.rb`
+    Then the example should pass
+
+  Scenario: expect specific error
+    Given a file named "expect_error_spec.rb" with:
+      """
+      describe "calling a method that does not exist" do
+        it "raises" do
+          expect { Object.new.foo }.to raise_error(NameError)
+        end
+      end
+      """
+    When I run `rspec expect_error_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:
+      """
+      describe "matching error message with string" do
+        it "matches the error message" do
+          expect { raise StandardError, 'this message exactly'}.
+            to raise_error(StandardError, 'this message exactly')
+        end
+      end
+      """
+    When I run `rspec expect_error_with_message.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:
+      """
+      describe "matching error message with regex" do
+        it "matches the error message" do
+          expect { raise StandardError, "my message" }.
+            to raise_error(StandardError, /my mess/)
+        end
+      end
+      """
+    When I run `rspec expect_error_with_regex.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:
+      """
+      describe "#foo" do
+        it "raises NameError" do
+          expect { Object.new.foo }.to raise_error { |error|
+            error.should be_a(NameError)
+          }
+        end
+      end
+      """
+      When I run `rspec expect_error_with_block_spec.rb`
+      Then the example should pass
+
+  Scenario: expect no error at all
+    Given a file named "expect_no_error_spec.rb" with:
+      """
+      describe "#to_s" do
+        it "does not raise" do
+          expect { Object.new.to_s }.to_not raise_error
+        end
+      end
+      """
+    When I run `rspec expect_no_error_spec.rb`
+    Then the example should pass
+    
+  Scenario: expect no occurence of a specific error
+    Given a file named "expect_no_error_spec.rb" with:
+      """
+      describe Object, "#public_instance_methods" do
+        it "does not raise" do
+          expect { Object.public_instance_methods }.
+            to_not raise_error(NameError)
+        end
+      end
+      """
+    When I run `rspec expect_no_error_spec.rb`
+    Then the example should pass

data/features/built_in_matchers/have.feature

@@ -0,0 +1,103 @@
+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
+
+  In addition, #have_exactly is provided as an alias to #have.
+
+  These work on any collection-like object--the object just needs to respond to #size
+  or #length (or both).  When the matcher is called directly on a collection object,
+  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
+
+  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:
+
+    Dir.new("my/directory").should have(7).entries
+
+  Scenario: have(x).items on a collection
+    Given a file named "have_items_spec.rb" with:
+      """
+      describe [1, 2, 3] do
+        it { should have(3).items }
+        it { should_not have(2).items }
+        it { should_not have(4).items }
+
+        it { should have_exactly(3).items }
+        it { should_not have_exactly(2).items }
+        it { should_not have_exactly(4).items }
+
+        it { should have_at_least(2).items }
+        it { should have_at_most(4).items }
+
+        # deliberate failures
+        it { should_not have(3).items }
+        it { should have(2).items }
+        it { should have(4).items }
+
+        it { should_not have_exactly(3).items }
+        it { should have_exactly(2).items }
+        it { should have_exactly(4).items }
+
+        it { should have_at_least(4).items }
+        it { should have_at_most(2).items }
+      end
+      """
+     When I run `rspec have_items_spec.rb`
+     Then the output should contain "16 examples, 8 failures"
+      And the output should contain "expected target not to have 3 items, got 3"
+      And the output should contain "expected 2 items, got 3"
+      And the output should contain "expected 4 items, got 3"
+      And the output should contain "expected at least 4 items, got 3"
+      And the output should contain "expected at most 2 items, got 3"
+
+  Scenario: have(x).words on a String when String#words is defined
+    Given a file named "have_words_spec.rb" with:
+      """
+      class String
+        def words
+          split(' ')
+        end
+      end
+
+      describe "a sentence with some words" do
+        it { should have(5).words }
+        it { should_not have(4).words }
+        it { should_not have(6).words }
+
+        it { should have_exactly(5).words }
+        it { should_not have_exactly(4).words }
+        it { should_not have_exactly(6).words }
+
+        it { should have_at_least(4).words }
+        it { should have_at_most(6).words }
+
+        # deliberate failures
+        it { should_not have(5).words }
+        it { should have(4).words }
+        it { should have(6).words }
+
+        it { should_not have_exactly(5).words }
+        it { should have_exactly(4).words }
+        it { should have_exactly(6).words }
+
+        it { should have_at_least(6).words }
+        it { should have_at_most(4).words }
+      end
+      """
+     When I run `rspec have_words_spec.rb`
+     Then the output should contain "16 examples, 8 failures"
+      And the output should contain "expected target not to have 5 words, got 5"
+      And the output should contain "expected 4 words, got 5"
+      And the output should contain "expected 6 words, got 5"
+      And the output should contain "expected at least 6 words, got 5"
+      And the output should contain "expected at most 4 words, got 5"
+

data/features/built_in_matchers/include.feature

@@ -0,0 +1,121 @@
+Feature: include matcher
+
+  Use the include matcher to specify that a collection includes one or more
+  expected objects.  This works on any object that responds to #include?  (such
+  as a string or array):
+
+    "a string".should include("a")
+    "a string".should include("str")
+    "a string".should include("str", "g")
+    "a string".should_not include("foo")
+
+    [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:
+
+    {:a => 1, :b => 2}.should include(:a)
+    {:a => 1, :b => 2}.should include(:a, :b)
+    {:a => 1, :b => 2}.should include(:a => 1)
+    {:a => 1, :b => 2}.should include(:b => 2, :a => 1)
+    {: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:
+      """
+      describe [1, 3, 7] do
+        it { should include(1) }
+        it { should include(3) }
+        it { should include(7) }
+        it { should include(1, 7) }
+        it { should include(1, 3, 7) }
+        it { should_not include(17) }
+        it { should_not include(43, 100) }
+
+        # deliberate failures
+        it { should include(4) }
+        it { should_not include(1) }
+        it { should_not include(3) }
+        it { should_not include(7) }
+        it { should_not include(1, 3, 7) }
+
+        # both of these should fail since it includes 1 but not 9
+        it { should include(1, 9) }
+        it { should_not include(1, 9) }
+      end
+      """
+    When I run `rspec array_include_matcher_spec.rb`
+    Then the output should contain all of these:
+      | 14 examples, 7 failures                       |
+      | expected [1, 3, 7] to include 4               |
+      | expected [1, 3, 7] not to include 1           |
+      | expected [1, 3, 7] not to include 3           |
+      | expected [1, 3, 7] not to include 7           |
+      | expected [1, 3, 7] not to include 1, 3, and 7 |
+      | expected [1, 3, 7] to include 1 and 9         |
+      | expected [1, 3, 7] not to include 1 and 9     |
+
+  Scenario: string usage
+    Given a file named "string_include_matcher_spec.rb" with:
+      """
+      describe "a string" do
+        it { should include("str") }
+        it { should include("a", "str", "ng") }
+        it { should_not include("foo") }
+        it { should_not include("foo", "bar") }
+
+        # deliberate failures
+        it { should include("foo") }
+        it { should_not include("str") }
+        it { should include("str", "foo") }
+        it { should_not include("str", "foo") }
+      end
+      """
+    When I run `rspec string_include_matcher_spec.rb`
+    Then the output should contain all of these:
+      | 8 examples, 4 failures                             |
+      | expected "a string" to include "foo"               |
+      | expected "a string" not to include "str"           |
+      | expected "a string" to include "str" and "foo"     |
+      | expected "a string" not to include "str" and "foo" |
+
+  Scenario: hash usage
+    Given a file named "hash_include_matcher_spec.rb" with:
+      """
+      describe Hash do
+        subject { { :a => 7, :b => 5 } }
+
+        it { should include(:a) }
+        it { should include(:b, :a) }
+        it { should include(:a => 7) }
+        it { should include(:b => 5, :a => 7) }
+        it { should_not include(:c) }
+        it { should_not include(:c, :d) }
+        it { should_not include(:d => 2) }
+        it { should_not include(:a => 5) }
+        it { should_not include(:b => 7, :a => 5) }
+
+        # deliberate failures
+        it { should_not include(:a) }
+        it { should_not include(:b, :a) }
+        it { should_not include(:a => 7) }
+        it { should_not include(:a => 7, :b => 5) }
+        it { should include(:c) }
+        it { should include(:c, :d) }
+        it { should include(:d => 2) }
+        it { should include(:a => 5) }
+        it { should include(:a => 5, :b => 7) }
+
+        # Mixed cases--the hash includes one but not the other.
+        # All 4 of these cases should fail.
+        it { should include(:a, :d) }
+        it { should_not include(:a, :d) }
+        it { should include(:a => 7, :d => 3) }
+        it { should_not include(:a => 7, :d => 3) }
+      end
+      """
+    When I run `rspec hash_include_matcher_spec.rb`
+    Then the output should contain "13 failure"

data/features/built_in_matchers/match.feature

@@ -0,0 +1,50 @@
+Feature: match matcher
+
+  The match matcher calls #match on the object, passing if #match returns a
+  truthy (not false or nil) value.  Regexp and String both provide a #match
+  method.
+
+    "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).
+
+  Scenario: string usage
+    Given a file named "string_match_spec.rb" with:
+      """
+      describe "a string" do
+        it { should match(/str/) }
+        it { should_not match(/foo/) }
+
+        # deliberate failures
+        it { should_not match(/str/) }
+        it { should match(/foo/) }
+      end
+      """
+    When I run `rspec string_match_spec.rb`
+    Then the output should contain all of these:
+      | 4 examples, 2 failures                 |
+      | expected "a string" not to match /str/ |
+      | expected "a string" to match /foo/     |
+
+  Scenario: regular expression usage
+    Given a file named "regexp_match_spec.rb" with:
+      """
+      describe /foo/ do
+        it { should match("food") }
+        it { should_not match("drinks") }
+
+        # deliberate failures
+        it { should_not match("food") }
+        it { should match("drinks") }
+      end
+      """
+    When I run `rspec regexp_match_spec.rb`
+    Then the output should contain all of these:
+      | 4 examples, 2 failures             |
+      | expected /foo/ not to match "food" |
+      | expected /foo/ to match "drinks"   |
+