Permalink
Browse files

doc updates

  • Loading branch information...
1 parent 14475f0 commit a4ebe07641dab82bb30b854cd3adfce536cd4a97 @dchelimsky dchelimsky committed Apr 20, 2011
View
@@ -1,4 +1,5 @@
- Upgrade.md
+- Changelog.md
- customized_message.feature
- diffing.feature
- implicit_docstrings.feature
View
@@ -1,6 +1,6 @@
### 2.6.0.rc2 / 2011-04-18
-[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.5.0...v2.6.1.rc2)
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.5.0...v2.6.0.rc2)
* Enhancments
* `change` matcher accepts Regexps (Robert Davis)
View
@@ -1,4 +1,4 @@
-rspec-expectations is used to set expectations in executable examples.
+rspec-expectations is used to define expected outcomes.
describe Account do
it "has a balance of zero when first created" do
@@ -35,10 +35,8 @@ These methods are also part of the matcher protocol, but are optional:
failure_message_for_should_not
description
-RSpec ships with a number of [built-in
-matchers](/rspec/rspec-expectations/v/2-6-rc/dir/built-in-matchers) and a DSL for
-writing your own [custom
-matchers](/rspec/rspec-expecations/v/2-6-rc/dir/custom-matchers).
+RSpec ships with a number of built-in matchers and a DSL for writing custom
+matchers.
## Issues
@@ -12,14 +12,15 @@
actual.should eq(expected) # passes if actual == expected
actual.should be(expected) # passes if actual.equal?(expected)
-## Near-equality (for floats)
-
- actual.should be_within(delta).of(expected)
-
-## Regular expressions
+## Comparisons
+ actual.should be > expected
+ actual.should be >= expected
+ actual.should be <= expected
+ actual.should be < expected
actual.should =~ /expression/
actual.should match(/expression/)
+ actual.should be_within(delta).of(expected)
## Types/classes
@@ -46,13 +47,6 @@
expect { ... }.to throw_symbol(:symbol)
expect { ... }.to throw_symbol(:symbol, 'value')
-## Operator matchers
-
- actual.should be > expected
- actual.should be >= expected
- actual.should be <= expected
- actual.should be < expected
-
## Predicate matchers
actual.should be_xxx # passes if actual.xxx?
@@ -3,17 +3,17 @@ Feature: be_within matcher
Normal equality expectations do not work well for floating point values.
Consider this irb session:
- > radius = 3
- => 3
- > area_of_circle = radius * radius * Math::PI
- => 28.2743338823081
- > area_of_circle == 28.2743338823081
- => false
+ > radius = 3
+ => 3
+ > area_of_circle = radius * radius * Math::PI
+ => 28.2743338823081
+ > area_of_circle == 28.2743338823081
+ => false
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)
+ 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.
@@ -2,24 +2,27 @@ 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
semantics.
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:
@@ -5,7 +5,7 @@ Feature: exist matcher
obj.should exist # passes if obj.exist? or obj.exists?
- Scenario Outline: basic usage
+ Scenario: basic usage
Given a file named "exist_matcher_spec.rb" with:
"""
class Planet
@@ -19,31 +19,25 @@ Feature: exist matcher
"<Planet: #{name}>"
end
- def <predicate_method>
+ def exist? # also works with exists?
%w[Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune].include?(name)
end
end
describe "Earth" do
- subject { Planet.new("Earth") }
- it { should exist }
- it { should_not exist } # deliberate failure
+ let(:earth) { Planet.new("Earth") }
+ specify { earth.should exist }
+ specify { earth.should_not exist } # deliberate failure
end
describe "Tatooine" do
- subject { Planet.new("Tatooine") }
- it { should_not exist }
- it { should exist } # deliberate failure
+ 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 |
-
- Examples:
- | predicate_method |
- | exist? |
- | exists? |
-
@@ -2,36 +2,36 @@ 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
+ 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 ==)"
+ 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.
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)
+ 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?
+ 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.

0 comments on commit a4ebe07

Please sign in to comment.