rspec-expectations 2.3.0 → 2.4.0

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :version => 2 do
+  watch('^spec/(.*)_spec.rb')
+  watch('^lib/(.*)\.rb')         { |m| "spec/#{m[1]}_spec.rb" }
+  watch('^spec/spec_helper.rb')  { "spec" }
+end

data/History.markdown

@@ -1,5 +1,15 @@
 ## rspec-expectations release history (incomplete)
 
+### 2.4.0 / 2011-01-02
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.3.0...v2.4.0)
+
+No functional changes in this release, which was made to align with the
+rspec-core-2.4.0 release.
+
+* Enhancements
+  * improved RDoc for change matcher (Jo Liss)
+
 ### 2.3.0 / 2010-12-12
 
 [full changelog](http://github.com/rspec/rspec-expectations/compare/v2.2.1...v2.3.0)

data/Rakefile

@@ -55,10 +55,10 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-desc "Push cukes to relishapp using the relish-client-gem"
+desc "Push docs/cukes to relishapp using the relish-client-gem"
 task :relish, :version do |t, args|
   raise "rake relish[VERSION]" unless args[:version]
-  sh "bundle exec relish push --organization rspec --project rspec-expectations -v #{args[:version]}"
+  sh "relish push rspec/rspec-expectations:#{args[:version]}"
 end
 
 task :clobber do

data/features/.nav

@@ -0,0 +1,27 @@
+- customized_message.feature
+- diffing.feature
+- implicit_docstrings.feature
+- built_in_matchers:
+  - be.feature
+  - be_within.feature
+  - equality.feature
+  - exist.feature
+  - expect_change.feature
+  - expect_error.feature
+  - have.feature
+  - include.feature
+  - match.feature
+  - operators.feature
+  - predicates.feature
+  - respond_to.feature
+  - satisfy.feature
+  - throw_symbol.feature
+  - types.feature
+- custom_matchers:
+  - define_matcher.feature
+  - define_diffable_matcher.feature
+  - define_matcher_with_fluent_interface.feature
+  - access_running_example.feature
+  - define_matcher_outside_rspec.feature
+- test_frameworks:
+  - test_unit.feature

data/features/README.markdown

@@ -1,5 +1,4 @@
-rspec-expectations is used to set expectations in executable
-examples:
+rspec-expectations is used to set expectations in executable examples.
 
     describe Account do
       it "has a balance of zero when first created" do
@@ -7,6 +6,31 @@ examples:
       end
     end
 
+## should and should_not
+
+rspec-expectations adds `should` and `should_not` to every object. Each of
+these can accept a matcher and, in most cases, an optional custom failure
+message (see [customized
+message](/rspec/rspec-expectations/v/2-3/customized-message)).
+
+## Matchers
+
+A Matcher is any object that responds to the following methods:
+
+    matches?(actual)
+    failure_message_for_should
+
+These methods are also part of the matcher protocol, but are optional:
+
+    does_not_match?(actual)
+    failure_message_for_should_not
+    description
+
+RSpec ships with a number of [built-in
+matchers](/rspec/rspec-expectations/v/2-3/dir/built-in-matchers) and a DSL for
+writing your own [custom
+matchers](/rspec/rspec-expectations/v/2-3/dir/custom-matchers).
+
 ## Issues
 
 The documentation for rspec-expectations is a work in progress. We'll be adding

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

@@ -1,15 +1,11 @@
-Feature: be matchers
+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 falsey (nil or false)
-    * obj.should be_nil # passes if obj is nil
-    * obj.should be # passes if obj is not nil
-    * obj.should be < expected # passes if obj < expected
-    * obj.should be > expected # passes if obj > expected
-    * obj.should be <= expected # passes if obj <= expected
-    * obj.should be >= expected # passes if obj >= expected
+      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
 
   Scenario: be_true matcher
     Given a file named "be_true_spec.rb" with:
@@ -84,13 +80,32 @@ Feature: be matchers
       end
       """
     When I run "rspec be_nil_spec.rb"
-    Then the output should contain all of these:
-      | 10 examples, 5 failures   |
-      | expected not nil, got nil |
-      | expected nil, got false   |
-      | expected nil, got true    |
-      | expected nil, got 7       |
-      | expected nil, got "foo"   |
+    Then the output should contain "10 examples, 5 failures"
+    And the output should contain:
+      """
+             expected: not nil
+                  got: nil
+      """
+    And the output should contain:
+      """
+             expected: nil
+                  got: false
+      """
+    And the output should contain:
+      """
+             expected: nil
+                  got: true
+      """
+    And the output should contain:
+      """
+             expected: nil
+                  got: 7
+      """
+    And the output should contain:
+      """
+             expected: nil
+                  got: "foo"
+      """
 
   Scenario: be matcher
     Given a file named "be_spec.rb" with:
@@ -118,32 +133,3 @@ Feature: be matchers
       | expected "foo" to evaluate to false |
       | expected nil to evaluate to true    |
       | expected false to evaluate to true  |
-
-  Scenario: be operator matchers
-    Given a file named "be_operators_spec.rb" with:
-      """
-      describe 17 do
-        it { should be < 20 }
-        it { should be > 15 }
-        it { should be <= 17 }
-        it { should be >= 17 }
-        it { should_not be < 15 }
-        it { should_not be > 20 }
-        it { should_not be <= 16 }
-        it { should_not be >= 18 }
-
-        # deliberate failures
-        it { should be < 15 }
-        it { should be > 20 }
-        it { should be <= 16 }
-        it { should be >= 18 }
-      end
-      """
-    When I run "rspec be_operators_spec.rb"
-    Then the output should contain all of these:
-      | 12 examples, 4 failures           |
-      | expected < 15, got 17             |
-      | expected > 20, got 17             |
-      | expected <= 16, got 17            |
-      | expected >= 18, got 17            |
-

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

@@ -1,4 +1,4 @@
-Feature: Equality matchers
+Feature: equality matchers
 
   Ruby exposes several different methods for handling equality:
 

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

@@ -1,4 +1,4 @@
-Feature: Expect change
+Feature: expect change
 
   Expect some code (wrapped in a proc) to change the state of some object.
   

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

@@ -1,4 +1,4 @@
-Feature: Expect error
+Feature: expect error
 
   Expect a proc to raise an error when called.
   

data/features/built_in_matchers/operators.feature

@@ -0,0 +1,221 @@
+Feature: operator matchers
+
+  RSpec provides a number of matchers that are based on Ruby's built-in
+  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"
+
+  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
+
+  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
+
+  Scenario: numeric operator matchers
+    Given a file named "numeric_operator_matchers_spec.rb" with:
+      """
+      describe 18 do
+        it { should == 18 }
+        it { should be < 20 }
+        it { should be > 15 }
+        it { should be <= 19 }
+        it { should be >= 17 }
+
+        it { should_not == 28 }
+
+        # deliberate failures
+        it { should == 28 }
+        it { should be < 15 }
+        it { should be > 20 }
+        it { should be <= 17 }
+        it { should be >= 19 }
+
+        it { should_not == 18 }
+      end
+      """
+     When I run "rspec numeric_operator_matchers_spec.rb"
+     Then the output should contain "12 examples, 6 failures"
+      And the output should contain:
+      """
+           Failure/Error: it { should == 28 }
+             expected: 28
+                  got: 18 (using ==)
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should be < 15 }
+             expected: < 15
+                  got:   18
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should be > 20 }
+             expected: > 20
+                  got:   18
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should be <= 17 }
+             expected: <= 17
+                  got:    18
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should be >= 19 }
+             expected: >= 19
+                  got:    18
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should_not == 18 }
+             expected not: == 18
+                      got:    18
+      """
+
+  Scenario: string operator matchers
+    Given a file named "string_operator_matchers_spec.rb" with:
+      """
+      describe "Strawberry" do
+        it { should == "Strawberry" }
+        it { should be < "Tomato" }
+        it { should be > "Apple" }
+        it { should be <= "Turnip" }
+        it { should be >= "Banana" }
+        it { should =~ /berry/ }
+
+        it { should_not == "Peach" }
+        it { should_not =~ /apple/ }
+
+        it "reports that it is a string using ===" do
+          String.should === subject
+        end
+
+        # deliberate failures
+        it { should == "Peach" }
+        it { should be < "Cranberry" }
+        it { should be > "Zuchini" }
+        it { should be <= "Potato" }
+        it { should be >= "Tomato" }
+        it { should =~ /apple/ }
+
+        it { should_not == "Strawberry" }
+        it { should_not =~ /berry/ }
+
+        it "fails a spec asserting that it is a symbol" do
+          Symbol.should === subject
+        end
+      end
+      """
+     When I run "rspec string_operator_matchers_spec.rb"
+     Then the output should contain "18 examples, 9 failures"
+      And the output should contain:
+      """
+           Failure/Error: it { should == "Peach" }
+             expected: "Peach"
+                  got: "Strawberry" (using ==)
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should be < "Cranberry" }
+             expected: < "Cranberry"
+                  got:   "Strawberry"
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should be > "Zuchini" }
+             expected: > "Zuchini"
+                  got:   "Strawberry"
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should be <= "Potato" }
+             expected: <= "Potato"
+                  got:    "Strawberry"
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should be >= "Tomato" }
+             expected: >= "Tomato"
+                  got:    "Strawberry"
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should =~ /apple/ }
+             expected: /apple/
+                  got: "Strawberry" (using =~)
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should_not == "Strawberry" }
+             expected not: == "Strawberry"
+                      got:    "Strawberry"
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should_not =~ /berry/ }
+             expected not: =~ /berry/
+                      got:    "Strawberry"
+      """
+      And the output should contain:
+      """
+           Failure/Error: Symbol.should === subject
+             expected: "Strawberry"
+                  got: Symbol (using ===)
+      """
+
+  Scenario: array operator matchers
+    Given a file named "array_operator_matchers_spec.rb" with:
+      """
+      describe [1, 2, 3] do
+        it { should == [1, 2, 3] }
+        it { should_not == [1, 3, 2] }
+
+        it { should =~ [1, 2, 3] }
+        it { should =~ [1, 3, 2] }
+        it { should =~ [2, 1, 3] }
+        it { should =~ [2, 3, 1] }
+        it { should =~ [3, 1, 2] }
+        it { should =~ [3, 2, 1] }
+
+        # deliberate failures
+        it { should_not == [1, 2, 3] }
+        it { should == [1, 3, 2] }
+        it { should =~ [1, 2, 1] }
+      end
+      """
+     When I run "rspec array_operator_matchers_spec.rb"
+     Then the output should contain "11 examples, 3 failures"
+      And the output should contain:
+      """
+           Failure/Error: it { should_not == [1, 2, 3] }
+             expected not: == [1, 2, 3]
+                      got:    [1, 2, 3]
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should == [1, 3, 2] }
+             expected: [1, 3, 2]
+                  got: [1, 2, 3] (using ==)
+      """
+      And the output should contain:
+      """
+           Failure/Error: it { should =~ [1, 2, 1] }
+             expected collection contained:  [1, 1, 2]
+             actual collection contained:    [1, 2, 3]
+             the missing elements were:      [1]
+             the extra elements were:        [3]
+      """
+