Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Update yard docs to use expect syntax #223

Merged
merged 2 commits into from

2 participants

@gautamkpai

No description provided.

lib/rspec/matchers.rb
@@ -679,17 +687,12 @@ def yield_successive_args(*args)
#
# @note This is also available using the `=~` operator with `should`,
# but `=~` is not supported with `expect`.
- # @note There is no should_not version of array.should =~ other_array
+ # @note There is no expect(..).not_to version of expect(array).not_to match_array(other_array)
@myronmarston Owner

This sentence is a bit awkward to read. Can it be rephrased, maybe like this?

This matcher only supports positive expectations. expect(..).not_to match_array(other_array) is not supported.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
lib/rspec/matchers.rb
((29 lines not shown))
#
# RSpec will also create custom matchers for predicates like `has_key?`. To
# use this feature, just state that the object should have_key(:key) and RSpec will
# call has_key?(:key) on the target. For example:
#
- # {:a => "A"}.should have_key(:a) # => {:a => "A"}.has_key?(:a) | passes
- # {:a => "A"}.should have_key(:b) # => {:a => "A"}.has_key?(:b) | fails
+ # expect({:a => "A"}).to have_key(:a) # => {:a => "A"}.has_key?(:a) | passes
+ # expect({:a => "A"}).to have_key(:b) # => {:a => "A"}.has_key?(:b) | fails
@myronmarston Owner

Using the curly braces here adds to the syntactical noiseness of the example. What do you think about using this instead?

expect(:a => "A").to have_key(:a)
expect(:a => "A").to have_key(:b)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@myronmarston

Looks great....I left a couple small comments.

@gautamkpai gautamkpai commented on the diff
lib/rspec/matchers.rb
@@ -679,17 +687,12 @@ def yield_successive_args(*args)
#
# @note This is also available using the `=~` operator with `should`,
# but `=~` is not supported with `expect`.

What about the above? Is this note still needed?

Since everything in this document talks about expect. It feels very abrupt and out of place be mentioning support for should here.

What's your take on this?

@myronmarston Owner

I think it's useful to keep since there's plenty of code out in the wild that uses should =~ array. It'll be helpful for folks who come hunting for what that does.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@gautamkpai

@myronmarston Could you please help me with the next step? With those two little changes,

Should I make a new commit and push it here? Or Should I amend the earlier commit? Or Commit and then squash them together? Or any other way?

@myronmarston

Do whatever you're most comfortable with.

@myronmarston myronmarston merged commit 1a2de54 into from
@myronmarston

Thanks!

@gautamkpai gautamkpai deleted the branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 120 additions and 115 deletions.
  1. +120 −115 lib/rspec/matchers.rb
View
235 lib/rspec/matchers.rb
@@ -1,5 +1,5 @@
module RSpec
- # RSpec::Matchers provides a number of useful matchers we use to compose
+ # RSpec::Matchers provides a number of useful matchers we use to define
# expectations. A matcher is any object that responds to the following:
#
# matches?(actual)
@@ -20,28 +20,29 @@ module RSpec
# A Ruby predicate is a method that ends with a "?" and returns true or false.
# Common examples are `empty?`, `nil?`, and `instance_of?`.
#
- # All you need to do is write `should be_` followed by the predicate without
- # the question mark, and RSpec will figure it out from there. For example:
+ # All you need to do is write `expect(..).to be_` followed by the predicate
+ # without the question mark, and RSpec will figure it out from there.
+ # For example:
#
- # [].should be_empty # => [].empty?() | passes
- # [].should_not be_empty # => [].empty?() | fails
+ # expect([]).to be_empty # => [].empty?() | passes
+ # expect([]).not_to be_empty # => [].empty?() | fails
#
# In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
# and "be_an_", making your specs read much more naturally:
#
- # "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
+ # expect("a string").to be_an_instance_of(String) # =>"a string".instance_of?(String) # passes
#
- # 3.should be_a_kind_of(Fixnum) # => 3.kind_of?(Numeric) | passes
- # 3.should be_a_kind_of(Numeric) # => 3.kind_of?(Numeric) | passes
- # 3.should be_an_instance_of(Fixnum) # => 3.instance_of?(Fixnum) | passes
- # 3.should_not be_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
+ # expect(3).to be_a_kind_of(Fixnum) # => 3.kind_of?(Numeric) | passes
+ # expect(3).to be_a_kind_of(Numeric) # => 3.kind_of?(Numeric) | passes
+ # expect(3).to be_an_instance_of(Fixnum) # => 3.instance_of?(Fixnum) | passes
+ # expect(3).not_to be_an_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
#
# RSpec will also create custom matchers for predicates like `has_key?`. To
# use this feature, just state that the object should have_key(:key) and RSpec will
# call has_key?(:key) on the target. For example:
#
- # {:a => "A"}.should have_key(:a) # => {:a => "A"}.has_key?(:a) | passes
- # {:a => "A"}.should have_key(:b) # => {:a => "A"}.has_key?(:b) | fails
+ # expect(:a => "A").to have_key(:a)
+ # expect(:a => "A").to have_key(:b) # fails
#
# You can use this feature to invoke any predicate that begins with "has_", whether it is
# part of the Ruby libraries (like `Hash#has_key?`) or a method you wrote on your own class.
@@ -58,15 +59,15 @@ module RSpec
# zones on a virtual board. To specify that bob should be in zone 4, you
# could say:
#
- # bob.current_zone.should eql(Zone.new("4"))
+ # expect(bob.current_zone).to eql(Zone.new("4"))
#
# But you might find it more expressive to say:
#
- # bob.should be_in_zone("4")
+ # expect(bob).to be_in_zone("4")
#
# and/or
#
- # bob.should_not be_in_zone("3")
+ # expect(bob).not_to be_in_zone("3")
#
# You can create such a matcher like so:
#
@@ -102,7 +103,7 @@ module RSpec
# passed to the <tt>create</tt> method (in this case, <tt>zone</tt>). The
# failure message methods (<tt>failure_message_for_should</tt> and
# <tt>failure_message_for_should_not</tt>) are passed the actual value (the
- # receiver of <tt>should</tt> or <tt>should_not</tt>).
+ # receiver of <tt>expect(..)</tt> or <tt>expect(..).not_to</tt>).
#
# ### Custom Matcher from scratch
#
@@ -205,12 +206,12 @@ def be_nil
end
# @example
- # actual.should be_true
- # actual.should be_false
- # actual.should be_nil
- # actual.should be_[arbitrary_predicate](*args)
- # actual.should_not be_nil
- # actual.should_not be_[arbitrary_predicate](*args)
+ # expect(actual).to be_true
+ # expect(actual).to be_false
+ # expect(actual).to be_nil
+ # expect(actual).to be_[arbitrary_predicate](*args)
+ # expect(actual).not_to be_nil
+ # expect(actual).not_to be_[arbitrary_predicate](*args)
#
# Given true, false, or nil, will pass if actual value is true, false or
# nil (respectively). Given no args means the caller should satisfy an if
@@ -240,9 +241,9 @@ def be_a(klass)
#
# @example
#
- # 5.should be_instance_of(Fixnum)
- # 5.should_not be_instance_of(Numeric)
- # 5.should_not be_instance_of(Float)
+ # expect(5).to be_an_instance_of(Fixnum)
+ # expect(5).not_to be_an_instance_of(Numeric)
+ # expect(5).not_to be_an_instance_of(Float)
def be_an_instance_of(expected)
BuiltIn::BeAnInstanceOf.new(expected)
end
@@ -253,9 +254,9 @@ def be_an_instance_of(expected)
#
# @example
#
- # 5.should be_kind_of(Fixnum)
- # 5.should be_kind_of(Numeric)
- # 5.should_not be_kind_of(Float)
+ # expect(5).to be_a_kind_of(Fixnum)
+ # expect(5).to be_a_kind_of(Numeric)
+ # expect(5).not_to be_a_kind_of(Float)
def be_a_kind_of(expected)
BuiltIn::BeAKindOf.new(expected)
end
@@ -266,8 +267,8 @@ def be_a_kind_of(expected)
#
# @example
#
- # result.should be_within(0.5).of(3.0)
- # result.should_not be_within(0.5).of(3.0)
+ # expect(result).to be_within(0.5).of(3.0)
+ # expect(result).not_to be_within(0.5).of(3.0)
def be_within(delta)
BuiltIn::BeWithin.new(delta)
end
@@ -283,55 +284,59 @@ def be_within(delta)
#
# When passing a block, it must use the <tt>{ ... }</tt> format, not
# do/end, as <tt>{ ... }</tt> binds to the +change+ method, whereas do/end
- # would errantly bind to the +should+ or +should_not+ method.
+ # would errantly bind to the +expect(..)+ or +expect(..).not_to+ method.
#
# @example
#
- # lambda {
+ # expect {
# team.add_player(player)
- # }.should change(roster, :count)
+ # }.to change(roster, :count)
#
- # lambda {
+ # expect {
# team.add_player(player)
- # }.should change(roster, :count).by(1)
+ # }.to change(roster, :count).by(1)
#
- # lambda {
+ # expect {
# team.add_player(player)
- # }.should change(roster, :count).by_at_least(1)
+ # }.to change(roster, :count).by_at_least(1)
#
- # lambda {
+ # expect {
# team.add_player(player)
- # }.should change(roster, :count).by_at_most(1)
+ # }.to change(roster, :count).by_at_most(1)
#
# string = "string"
- # lambda {
+ # expect {
# string.reverse!
- # }.should change { string }.from("string").to("gnirts")
+ # }.to change { string }.from("string").to("gnirts")
#
- # lambda {
+ # string = "string"
+ # expect {
+ # string
+ # }.not_to change { string }
+ #
+ # expect {
# person.happy_birthday
- # }.should change(person, :birthday).from(32).to(33)
+ # }.to change(person, :birthday).from(32).to(33)
#
- # lambda {
+ # expect {
# employee.develop_great_new_social_networking_app
- # }.should change(employee, :title).from("Mail Clerk").to("CEO")
+ # }.to change(employee, :title).from("Mail Clerk").to("CEO")
#
- # lambda {
+ # expect {
# doctor.leave_office
- # }.should change(doctor, :sign).from(/is in/).to(/is out/)
+ # }.to change(doctor, :sign).from(/is in/).to(/is out/)
#
# user = User.new(:type => "admin")
- # lambda {
+ # expect {
# user.symbolize_type
- # }.should change(user, :type).from(String).to(Symbol)
+ # }.to change(user, :type).from(String).to(Symbol)
#
# == Notes
#
# Evaluates <tt>receiver.message</tt> or <tt>block</tt> before and after it
- # evaluates the proc object (generated by the lambdas in the examples
- # above).
+ # evaluates the block passed to <tt>expect</tt>.
#
- # <tt>should_not change</tt> only supports the form with no subsequent
+ # <tt>expect( ... ).not_to change</tt> only supports the form with no subsequent
# calls to <tt>by</tt>, <tt>by_at_least</tt>, <tt>by_at_most</tt>,
# <tt>to</tt> or <tt>from</tt>.
def change(receiver=nil, message=nil, &block)
@@ -343,11 +348,11 @@ def change(receiver=nil, message=nil, &block)
# and it will only pass if all args are found in Range.
#
# @example
- # (1..10).should cover(5)
- # (1..10).should cover(4, 6)
- # (1..10).should cover(4, 6, 11) # will fail
- # (1..10).should_not cover(11)
- # (1..10).should_not cover(5) # will fail
+ # expect(1..10).to cover(5)
+ # expect(1..10).to cover(4, 6)
+ # expect(1..10).to cover(4, 6, 11) # fails
+ # expect(1..10).not_to cover(11)
+ # expect(1..10).not_to cover(5) # fails
#
# ### Warning:: Ruby >= 1.9 only
def cover(*values)
@@ -361,45 +366,48 @@ def cover(*values)
#
# @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
+ # expect("this string").to end_with "string"
+ # expect([0, 1, 2, 3, 4]).to end_with 4
+ # expect([0, 2, 3, 4, 4]).to 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.
+ # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+ # information about equality in Ruby.
#
# @example
#
- # 5.should eq(5)
- # 5.should_not eq(3)
+ # expect(5).to eq(5)
+ # expect(5).not_to eq(3)
def eq(expected)
BuiltIn::Eq.new(expected)
end
# Passes if +actual.eql?(expected)+
#
- # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+ # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+ # information about equality in Ruby.
#
# @example
#
- # 5.should eql(5)
- # 5.should_not eql(3)
+ # expect(5).to eql(5)
+ # expect(5).not_to eql(3)
def eql(expected)
BuiltIn::Eql.new(expected)
end
# Passes if <tt>actual.equal?(expected)</tt> (object identity).
#
- # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+ # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+ # information about equality in Ruby.
#
# @example
#
- # 5.should equal(5) # Fixnums are equal
- # "5".should_not equal("5") # Strings that look the same are not the same object
+ # expect(5).to equal(5) # Fixnums are equal
+ # expect("5").not_to equal("5") # Strings that look the same are not the same object
def equal(expected)
BuiltIn::Equal.new(expected)
end
@@ -407,7 +415,7 @@ def equal(expected)
# Passes if `actual.exist?` or `actual.exists?`
#
# @example
- # File.should exist("path/to/file")
+ # expect(File).to exist("path/to/file")
def exist(*args)
BuiltIn::Exist.new(*args)
end
@@ -430,16 +438,16 @@ def exist(*args)
# @example
#
# # Passes if team.players.size == 11
- # team.should have(11).players
+ # expect(team).to have(11).players
#
# # Passes if [1,2,3].length == 3
- # [1,2,3].should have(3).items #"items" is pure sugar
+ # expect([1,2,3]).to have(3).items #"items" is pure sugar
#
# # Passes if ['a', 'b', 'c'].count == 3
- # [1,2,3].should have(3).items #"items" is pure sugar
+ # expect([1,2,3]).to have(3).items #"items" is pure sugar
#
# # Passes if "this string".length == 11
- # "this string".should have(11).characters #"characters" is pure sugar
+ # expect("this string").to have(11).characters #"characters" is pure sugar
def have(n)
BuiltIn::Have.new(n)
end
@@ -448,11 +456,11 @@ def have(n)
# Exactly like have() with >=.
#
# @example
- # "this".should have_at_least(3).letters
+ # expect("this").to have_at_least(3).letters
#
# ### Warning:
#
- # `should_not have_at_least` is not supported
+ # `expect(..).not_to have_at_least` is not supported
def have_at_least(n)
BuiltIn::Have.new(n, :at_least)
end
@@ -460,11 +468,11 @@ def have_at_least(n)
# Exactly like have() with <=.
#
# @example
- # should have_at_most(number).items
+ # expect("this").to have_at_most(4).letters
#
# ### Warning:
#
- # `should_not have_at_most` is not supported
+ # `expect(..).not_to have_at_most` is not supported
def have_at_most(n)
BuiltIn::Have.new(n, :at_most)
end
@@ -475,12 +483,12 @@ def have_at_most(n)
#
# @example
#
- # [1,2,3].should include(3)
- # [1,2,3].should include(2,3) #would pass
- # [1,2,3].should include(2,3,4) #would fail
- # [1,2,3].should_not include(4)
- # "spread".should include("read")
- # "spread".should_not include("red")
+ # expect([1,2,3]).to include(3)
+ # expect([1,2,3]).to include(2,3)
+ # expect([1,2,3]).to include(2,3,4) # fails
+ # expect([1,2,3]).not_to include(4)
+ # expect("spread").to include("read")
+ # expect("spread").not_to include("red")
def include(*expected)
BuiltIn::Include.new(*expected)
end
@@ -489,10 +497,10 @@ def include(*expected)
#
# @example
#
- # email.should match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
- # email.should match("@example.com")
- # zipcode.should match_regex(/\A\d{5}(-\d{4})?\z/)
- # zipcode.should match_regex("90210")
+ # expect(email).to match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
+ # expect(email).to match("@example.com")
+ # expect(zipcode).to match_regex(/\A\d{5}(-\d{4})?\z/)
+ # expect(zipcode).to match_regex("90210")
#
# @note Due to Ruby's method dispatch mechanism, using the `#match` matcher
# within a custom matcher defined via the matcher DSL
@@ -513,16 +521,16 @@ def match(expected)
#
# @example
#
- # lambda { do_something_risky }.should raise_error
- # lambda { do_something_risky }.should raise_error(PoorRiskDecisionError)
- # lambda { do_something_risky }.should raise_error(PoorRiskDecisionError) { |error| error.data.should == 42 }
- # lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, "that was too risky")
- # lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, /oo ri/)
+ # expect { do_something_risky }.to raise_error
+ # expect { do_something_risky }.to raise_error(PoorRiskDecisionError)
+ # expect { do_something_risky }.to raise_error(PoorRiskDecisionError) { |error| expect(error.data).to eq 42 }
+ # expect { do_something_risky }.to raise_error(PoorRiskDecisionError, "that was too risky")
+ # expect { do_something_risky }.to raise_error(PoorRiskDecisionError, /oo ri/)
#
- # lambda { do_something_risky }.should_not raise_error
- # lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError)
- # lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, "that was too risky")
- # lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, /oo ri/)
+ # expect { do_something_risky }.not_to raise_error
+ # expect { do_something_risky }.not_to raise_error(PoorRiskDecisionError)
+ # expect { do_something_risky }.not_to raise_error(PoorRiskDecisionError, "that was too risky")
+ # expect { do_something_risky }.not_to raise_error(PoorRiskDecisionError, /oo ri/)
def raise_error(error=Exception, message=nil, &block)
BuiltIn::RaiseError.new(error, message, &block)
end
@@ -534,6 +542,8 @@ def raise_error(error=Exception, message=nil, &block)
#
# @example
#
+ # expect("string").to respond_to(:length)
+ #
def respond_to(*names)
BuiltIn::RespondTo.new(*names)
end
@@ -550,9 +560,7 @@ def respond_to(*names)
#
# @example
#
- # 5.should satisfy { |n|
- # n > 3
- # }
+ # expect(5).to satisfy { |n| n > 3 }
def satisfy(&block)
BuiltIn::Satisfy.new(&block)
end
@@ -564,9 +572,9 @@ def satisfy(&block)
#
# @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
+ # expect("this string").to start_with "this s"
+ # expect([0, 1, 2, 3, 4]).to start_with 0
+ # expect([0, 2, 3, 4, 4]).to start_with 0, 1
def start_with(*expected)
BuiltIn::StartWith.new(*expected)
end
@@ -580,13 +588,13 @@ def start_with(*expected)
#
# @example
#
- # lambda { do_something_risky }.should throw_symbol
- # lambda { do_something_risky }.should throw_symbol(:that_was_risky)
- # lambda { do_something_risky }.should throw_symbol(:that_was_risky, culprit)
+ # expect { do_something_risky }.to throw_symbol
+ # expect { do_something_risky }.to throw_symbol(:that_was_risky)
+ # expect { do_something_risky }.to throw_symbol(:that_was_risky, 'culprit')
#
- # lambda { do_something_risky }.should_not throw_symbol
- # lambda { do_something_risky }.should_not throw_symbol(:that_was_risky)
- # lambda { do_something_risky }.should_not throw_symbol(:that_was_risky, culprit)
+ # expect { do_something_risky }.not_to throw_symbol
+ # expect { do_something_risky }.not_to throw_symbol(:that_was_risky)
+ # expect { do_something_risky }.not_to throw_symbol(:that_was_risky, 'culprit')
def throw_symbol(expected_symbol=nil, expected_arg=nil)
BuiltIn::ThrowSymbol.new(expected_symbol, expected_arg)
end
@@ -679,17 +687,14 @@ def yield_successive_args(*args)
#
# @note This is also available using the `=~` operator with `should`,
# but `=~` is not supported with `expect`.

What about the above? Is this note still needed?

Since everything in this document talks about expect. It feels very abrupt and out of place be mentioning support for should here.

What's your take on this?

@myronmarston Owner

I think it's useful to keep since there's plenty of code out in the wild that uses should =~ array. It'll be helpful for folks who come hunting for what that does.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
- # @note There is no should_not version of array.should =~ other_array
+ #
+ # @note This matcher only supports positive expectations.
+ # expect(..).not_to match_array(other_array) is not supported.
#
# @example
#
# expect([1,2,3]).to match_array([1,2,3])
# expect([1,2,3]).to match_array([1,3,2])
- # [1,2,3].should =~ [1,2,3] # => would pass
- # [1,2,3].should =~ [2,3,1] # => would pass
- # [1,2,3,4].should =~ [1,2,3] # => would fail
- # [1,2,2,3].should =~ [1,2,3] # => would fail
- # [1,2,3].should =~ [1,2,3,4] # => would fail
def match_array(array)
BuiltIn::MatchArray.new(array)
end
Something went wrong with that request. Please try again.