Class: FlexMock::Expectation
Overview
An Expectation is returned from each should_receive
message sent to mock object. Each expectation records how a message matching the message name (argument to should_receive
) and the argument list (given by with
) should behave. Mock expectations can be recorded by chaining the declaration methods defined in this class.
For example:
mock.should_receive(:meth).with(args).and_returns(result)
Instance Attribute Summary collapse
-
#expected_args ⇒ Object
readonly
Returns the value of attribute expected_args.
-
#mock ⇒ Object
Returns the value of attribute mock.
-
#order_number ⇒ Object
readonly
Returns the value of attribute order_number.
Instance Method Summary collapse
-
#_return_value(args) ⇒ Object
Public return value (odd name to avoid accidental use as a constraint).
-
#and_iterates(*yield_values) ⇒ Object
Declare that the mocked method is expected to be given a block and that the block will iterate over the provided values.
-
#and_raise(exception, *args) ⇒ Object
(also: #raises)
:call-seq: and_raise(an_exception) and_raise(SomeException) and_raise(SomeException, args, …).
-
#and_return(*args, &block) ⇒ Object
(also: #returns)
:call-seq: and_return(value) and_return(value, value, …) and_return { |*args| code }.
-
#and_return_undefined ⇒ Object
(also: #returns_undefined)
Declare that the method returns and undefined object (FlexMock.undefined).
-
#and_throw(sym, value = nil) ⇒ Object
(also: #throws)
:call-seq: and_throw(a_symbol) and_throw(a_symbol, value).
-
#and_yield(*yield_values) ⇒ Object
(also: #yields)
:call-seq: and_yield(value1, value2, …).
-
#at_least ⇒ Object
Modifies the next call count declarator (
times
,never
,once
ortwice
) so that the declarator means the method is called at least that many times. -
#at_most ⇒ Object
Modifies the next call count declarator (
times
,never
,once
ortwice
) so that the declarator means the method is called at most that many times. - #by_default ⇒ Object
-
#description ⇒ Object
Return a description of the matching features of the expectation.
-
#eligible? ⇒ Boolean
Is this expectation eligible to be called again? It is eligible only if all of its count validators agree that it is eligible.
-
#explicitly ⇒ Object
No-op for allowing explicit calls when explicit not explicitly needed.
- #flexmock_location_filter ⇒ Object
-
#flexmock_verify ⇒ Object
Validate the correct number of calls have been made.
-
#globally ⇒ Object
Modifier that changes the next ordered constraint to apply globally across all mock objects in the container.
-
#initialize(mock, sym, location) ⇒ Expectation
constructor
Create an expectation for a method named
sym
. -
#match_args(args) ⇒ Object
Does the argument list match this expectation’s argument specification.
-
#never ⇒ Object
Declare that the method is never expected to be called with the given argument list.
-
#once ⇒ Object
Declare that the method is expected to be called exactly once with the given argument list.
-
#ordered(group_name = nil) ⇒ Object
Declare that the given method must be called in order.
- #pass_thru(&block) ⇒ Object
-
#times(limit) ⇒ Object
Declare that the method is called
limit
times with the declared argument list. - #to_s ⇒ Object
-
#twice ⇒ Object
Declare that the method is expected to be called exactly twice with the given argument list.
-
#validate_eligible ⇒ Object
Validate that this expectation is eligible for an extra call.
- #validate_signature(args) ⇒ Object
-
#verify_call(*args) ⇒ Object
Verify the current call with the given arguments matches the expectations recorded in this object.
-
#with(*args) ⇒ Object
Declare that the method should expect the given argument list.
-
#with_any_args ⇒ Object
Declare that the method can be called with any number of arguments of any type.
-
#with_no_args ⇒ Object
Declare that the method should be called with no arguments.
-
#with_signature(required_arguments: 0, optional_arguments: 0, splat: false, required_keyword_arguments: [], optional_keyword_arguments: [], keyword_splat: false) ⇒ Object
Validate general parameters on the call signature.
-
#with_signature_matching(instance_method) ⇒ Object
Validate that the passed arguments match the method signature from the given instance method.
-
#zero_or_more_times ⇒ Object
Declare that the method may be called any number of times.
Constructor Details
#initialize(mock, sym, location) ⇒ Expectation
Create an expectation for a method named sym
.
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
# File 'lib/flexmock/expectation.rb', line 35 def initialize(mock, sym, location) @mock = mock @sym = sym @location = location @expected_args = nil @count_validators = [] @signature_validator = SignatureValidator.new(self) @count_validator_class = ExactCountValidator @actual_count = 0 @return_value = nil @return_queue = [] @yield_queue = [] @order_number = nil @global_order_number = nil @globally = nil end |
Instance Attribute Details
#expected_args ⇒ Object (readonly)
Returns the value of attribute expected_args.
31 32 33 |
# File 'lib/flexmock/expectation.rb', line 31 def expected_args @expected_args end |
#mock ⇒ Object
Returns the value of attribute mock.
32 33 34 |
# File 'lib/flexmock/expectation.rb', line 32 def mock @mock end |
#order_number ⇒ Object (readonly)
Returns the value of attribute order_number.
31 32 33 |
# File 'lib/flexmock/expectation.rb', line 31 def order_number @order_number end |
Instance Method Details
#_return_value(args) ⇒ Object
Public return value (odd name to avoid accidental use as a constraint).
105 106 107 |
# File 'lib/flexmock/expectation.rb', line 105 def _return_value(args) # :nodoc: return_value(args) end |
#and_iterates(*yield_values) ⇒ Object
Declare that the mocked method is expected to be given a block and that the block will iterate over the provided values. If the mock is called multiple times, mulitple and_iterates
declarations can be used to supply different values on each call.
The iteration is queued with the yield values provided with #and_yield.
An error is raised if the mocked method is not called with a block.
305 306 307 |
# File 'lib/flexmock/expectation.rb', line 305 def and_iterates(*yield_values) @yield_queue << yield_values end |
#and_raise(exception, *args) ⇒ Object Also known as: raises
:call-seq:
and_raise(an_exception)
and_raise(SomeException)
and_raise(SomeException, args, ...)
Declares that the method will raise the given exception (with an optional message) when executed.
-
If an exception instance is given, then that instance will be raised.
-
If an exception class is given, the exception raised with be an instance of that class constructed with
new
. Any additional arguments in the argument list will be passed to thenew
constructor when it is invoked.
raises
is an alias for and_raise
.
327 328 329 |
# File 'lib/flexmock/expectation.rb', line 327 def and_raise(exception, *args) and_return { raise exception, *args } end |
#and_return(*args, &block) ⇒ Object Also known as: returns
:call-seq:
and_return(value)
and_return(value, value, ...)
and_return { |*args| code }
Declare that the method returns a particular value (when the argument list is matched).
-
If a single value is given, it will be returned for all matching calls.
-
If multiple values are given, each value will be returned in turn for each successive call. If the number of matching calls is greater than the number of values, the last value will be returned for the extra matching calls.
-
If a block is given, it is evaluated on each call and its value is returned.
For example:
mock.should_receive(:f).returns(12) # returns 12
mock.should_receive(:f).with(String). # returns an
returns { |str| str.upcase } # upcased string
returns
is an alias for and_return
.
243 244 245 246 247 248 249 250 251 252 |
# File 'lib/flexmock/expectation.rb', line 243 def and_return(*args, &block) if block_given? @return_queue << block else args.each do |arg| @return_queue << lambda { |*a| arg } end end self end |
#and_return_undefined ⇒ Object Also known as: returns_undefined
Declare that the method returns and undefined object (FlexMock.undefined). Since the undefined object will always return itself for any message sent to it, it is a good “I don’t care” value to return for methods that are commonly used in method chains.
For example, if m.foo returns the undefined object, then:
m.foo..baz
returns the undefined object without throwing an exception.
267 268 269 |
# File 'lib/flexmock/expectation.rb', line 267 def and_return_undefined and_return(FlexMock.undefined) end |
#and_throw(sym, value = nil) ⇒ Object Also known as: throws
:call-seq:
and_throw(a_symbol)
and_throw(a_symbol, value)
Declares that the method will throw the given symbol (with an optional value) when executed.
throws
is an alias for and_throw
.
341 342 343 |
# File 'lib/flexmock/expectation.rb', line 341 def and_throw(sym, value=nil) and_return { throw sym, value } end |
#and_yield(*yield_values) ⇒ Object Also known as: yields
:call-seq:
and_yield(value1, value2, ...)
Declare that the mocked method is expected to be given a block and that the block will be called with the values supplied to yield. If the mock is called multiple times, mulitple and_yield
declarations can be used to supply different values on each call.
An error is raised if the mocked method is not called with a block.
283 284 285 |
# File 'lib/flexmock/expectation.rb', line 283 def and_yield(*yield_values) @yield_queue << [yield_values] end |
#at_least ⇒ Object
Modifies the next call count declarator (times
, never
, once
or twice
) so that the declarator means the method is called at least that many times.
E.g. method f must be called at least twice:
mock.should_receive(:f).at_least.twice
404 405 406 407 |
# File 'lib/flexmock/expectation.rb', line 404 def at_least @count_validator_class = AtLeastCountValidator self end |
#at_most ⇒ Object
Modifies the next call count declarator (times
, never
, once
or twice
) so that the declarator means the method is called at most that many times.
E.g. method f must be called no more than twice
mock.should_receive(:f).at_most.twice
417 418 419 420 |
# File 'lib/flexmock/expectation.rb', line 417 def at_most @count_validator_class = AtMostCountValidator self end |
#by_default ⇒ Object
488 489 490 491 |
# File 'lib/flexmock/expectation.rb', line 488 def by_default expectations = mock.flexmock_expectations_for(@sym) expectations.defaultify_expectation(self) if expectations end |
#description ⇒ Object
Return a description of the matching features of the expectation. Matching features include:
-
name of the method
-
argument matchers
-
call count validators
63 64 65 66 67 68 69 70 71 72 73 |
# File 'lib/flexmock/expectation.rb', line 63 def description result = "should_receive(#{@sym.inspect})" result << ".with(#{FlexMock.format_args(@expected_args)})" if @expected_args @count_validators.each do |validator| result << validator.describe end if !@signature_validator.null? result << @signature_validator.describe end result end |
#eligible? ⇒ Boolean
Is this expectation eligible to be called again? It is eligible only if all of its count validators agree that it is eligible.
142 143 144 |
# File 'lib/flexmock/expectation.rb', line 142 def eligible? @count_validators.all? { |v| v.eligible?(@actual_count) } end |
#explicitly ⇒ Object
No-op for allowing explicit calls when explicit not explicitly needed.
484 485 486 |
# File 'lib/flexmock/expectation.rb', line 484 def explicitly self end |
#flexmock_location_filter ⇒ Object
493 494 495 496 497 498 499 500 501 502 |
# File 'lib/flexmock/expectation.rb', line 493 def flexmock_location_filter yield rescue Exception => ex bt = @location.dup flexmock_dir = File.(File.dirname(__FILE__)) while bt.first.start_with?(flexmock_dir) bt.shift end raise ex, ex., bt end |
#flexmock_verify ⇒ Object
Validate the correct number of calls have been made. Called by the teardown process.
163 164 165 166 167 168 169 |
# File 'lib/flexmock/expectation.rb', line 163 def flexmock_verify @count_validators.each do |v| v.validate(@actual_count) end rescue CountValidator::ValidationFailed => e FlexMock.framework_adapter.make_assertion(e., @location) { false } end |
#globally ⇒ Object
Modifier that changes the next ordered constraint to apply globally across all mock objects in the container.
458 459 460 461 |
# File 'lib/flexmock/expectation.rb', line 458 def globally @globally = true self end |
#match_args(args) ⇒ Object
Does the argument list match this expectation’s argument specification.
173 174 175 |
# File 'lib/flexmock/expectation.rb', line 173 def match_args(args) ArgumentMatching.all_match?(@expected_args, args) end |
#never ⇒ Object
Declare that the method is never expected to be called with the given argument list. This may be modified by the at_least
and at_most
declarators.
378 379 380 |
# File 'lib/flexmock/expectation.rb', line 378 def never times(0) end |
#once ⇒ Object
Declare that the method is expected to be called exactly once with the given argument list. This may be modified by the at_least
and at_most
declarators.
385 386 387 |
# File 'lib/flexmock/expectation.rb', line 385 def once times(1) end |
#ordered(group_name = nil) ⇒ Object
Declare that the given method must be called in order. All ordered method calls must be received in the order specified by the ordering of the should_receive
messages. Receiving a methods out of the specified order will cause a test failure.
If the user needs more fine control over ordering (e.g. specifying that a group of messages may be received in any order as long as they all come after another group of messages), a group name may be specified in the ordered
calls. All messages within the same group may be received in any order.
For example, in the following, messages flip
and flop
may be received in any order (because they are in the same group), but must occur strictly after start
but before end
. The message any_time
may be received at any time because it is not ordered.
m = FlexMock.new
m.should_receive(:any_time)
m.should_receive(:start).ordered
m.should_receive(:flip).ordered(:flip_flop_group)
m.should_receive(:flop).ordered(:flip_flop_group)
m.should_receive(:end).ordered
446 447 448 449 450 451 452 453 454 |
# File 'lib/flexmock/expectation.rb', line 446 def ordered(group_name=nil) if @globally @global_order_number = define_ordered(group_name, @mock.flexmock_container) else @order_number = define_ordered(group_name, @mock) end @globally = false self end |
#pass_thru(&block) ⇒ Object
346 347 348 349 350 351 352 353 354 355 356 357 358 359 |
# File 'lib/flexmock/expectation.rb', line 346 def pass_thru(&block) block ||= lambda { |value| value } and_return { |*args| begin block.call(@mock.flexmock_invoke_original(@sym, args)) rescue NoMethodError => e if e.name == @sym raise e, "#{e.} while performing #pass_thru in expectation object #{self}" else raise end end } end |
#times(limit) ⇒ Object
Declare that the method is called limit
times with the declared argument list. This may be modified by the at_least
and at_most
declarators.
369 370 371 372 373 |
# File 'lib/flexmock/expectation.rb', line 369 def times(limit) @count_validators << @count_validator_class.new(self, limit) unless limit.nil? @count_validator_class = ExactCountValidator self end |
#to_s ⇒ Object
52 53 54 |
# File 'lib/flexmock/expectation.rb', line 52 def to_s FlexMock.format_call(@sym, @expected_args) end |
#twice ⇒ Object
Declare that the method is expected to be called exactly twice with the given argument list. This may be modified by the at_least
and at_most
declarators.
392 393 394 |
# File 'lib/flexmock/expectation.rb', line 392 def twice times(2) end |
#validate_eligible ⇒ Object
Validate that this expectation is eligible for an extra call
76 77 78 79 80 81 82 83 84 |
# File 'lib/flexmock/expectation.rb', line 76 def validate_eligible @count_validators.each do |v| if !v.eligible?(@actual_count) v.validate(@actual_count + 1) end end rescue CountValidator::ValidationFailed => e FlexMock.framework_adapter.check(e.) { false } end |
#validate_signature(args) ⇒ Object
86 87 88 89 90 |
# File 'lib/flexmock/expectation.rb', line 86 def validate_signature(args) @signature_validator.validate(args) rescue SignatureValidator::ValidationFailed => e FlexMock.framework_adapter.check(e.) { false } end |
#verify_call(*args) ⇒ Object
Verify the current call with the given arguments matches the expectations recorded in this object.
94 95 96 97 98 99 100 101 |
# File 'lib/flexmock/expectation.rb', line 94 def verify_call(*args) validate_eligible validate_order validate_signature(args) @actual_count += 1 perform_yielding(args) return_value(args) end |
#with(*args) ⇒ Object
Declare that the method should expect the given argument list.
178 179 180 181 |
# File 'lib/flexmock/expectation.rb', line 178 def with(*args) @expected_args = args self end |
#with_any_args ⇒ Object
Declare that the method can be called with any number of arguments of any type.
190 191 192 193 |
# File 'lib/flexmock/expectation.rb', line 190 def with_any_args @expected_args = nil self end |
#with_no_args ⇒ Object
Declare that the method should be called with no arguments.
184 185 186 |
# File 'lib/flexmock/expectation.rb', line 184 def with_no_args with end |
#with_signature(required_arguments: 0, optional_arguments: 0, splat: false, required_keyword_arguments: [], optional_keyword_arguments: [], keyword_splat: false) ⇒ Object
Validate general parameters on the call signature
196 197 198 199 200 201 202 203 204 205 206 207 208 |
# File 'lib/flexmock/expectation.rb', line 196 def with_signature( required_arguments: 0, optional_arguments: 0, splat: false, required_keyword_arguments: [], optional_keyword_arguments: [], keyword_splat: false) @signature_validator = SignatureValidator.new( self, required_arguments: required_arguments, optional_arguments: optional_arguments, splat: splat, required_keyword_arguments: required_keyword_arguments, optional_keyword_arguments: optional_keyword_arguments, keyword_splat: keyword_splat) self end |
#with_signature_matching(instance_method) ⇒ Object
Validate that the passed arguments match the method signature from the given instance method
212 213 214 215 |
# File 'lib/flexmock/expectation.rb', line 212 def with_signature_matching(instance_method) @signature_validator = SignatureValidator.from_instance_method(self, instance_method) self end |
#zero_or_more_times ⇒ Object
Declare that the method may be called any number of times.
362 363 364 |
# File 'lib/flexmock/expectation.rb', line 362 def zero_or_more_times at_least.never end |