Class: FlexMock::Expectation

Inherits:
Object
  • Object
show all
Defined in:
lib/flexmock/expectation.rb

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

Instance Method Summary collapse

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
51
52
 
# File 'lib/flexmock/expectation.rb', line 35

def initialize(mock, sym, location)
  @mock = mock
  @sym = sym
  @location = location
  @expected_args = nil
  @expected_kw = nil
  @count_validators = []
  @signature_validator = SignatureValidator.new(self)
  @count_validator_class = ExactCountValidator
  @with_block = nil
  @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, kw, block) ⇒ Object

Public return value (odd name to avoid accidental use as a constraint).



109
110
111
 
# File 'lib/flexmock/expectation.rb', line 109

def _return_value(args, kw, block) # :nodoc:
  return_value(args, kw, block)
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.

Examples:

interaction of and_yield and and_iterates

mock.should_receive(:each).and_yield(10).and_iterates(1, 2, 3).and_yield(20)
mock.enum_for(:each).to_a # => [10]
mock.enum_for(:each).to_a # => [1,2,3]
mock.enum_for(:each).to_a # => [20]


352
353
354
 
# File 'lib/flexmock/expectation.rb', line 352

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 the new constructor when it is invoked.

raises is an alias for and_raise.



374
375
376
 
# File 'lib/flexmock/expectation.rb', line 374

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.



290
291
292
293
294
295
296
297
298
299
 
# File 'lib/flexmock/expectation.rb', line 290

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.bar.baz

returns the undefined object without throwing an exception.



314
315
316
 
# File 'lib/flexmock/expectation.rb', line 314

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.



388
389
390
 
# File 'lib/flexmock/expectation.rb', line 388

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.



330
331
332
 
# File 'lib/flexmock/expectation.rb', line 330

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



451
452
453
454
 
# File 'lib/flexmock/expectation.rb', line 451

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



464
465
466
467
 
# File 'lib/flexmock/expectation.rb', line 464

def at_most
  @count_validator_class = AtMostCountValidator
  self
end

#by_default ⇒ Object 



535
536
537
538
 
# File 'lib/flexmock/expectation.rb', line 535

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



65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/flexmock/expectation.rb', line 65

def description
  result = ["should_receive(#{@sym.inspect})"]
  if @expected_args || @expected_kw
    result << ".with(#{FlexMock.format_args(@expected_args, @expected_kw)})"
  end
  @count_validators.each do |validator|
    result << validator.describe
  end
  if !@signature_validator.null?
    result << @signature_validator.describe
  end
  result.join
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.

Returns:

  • (Boolean) 


145
146
147
 
# File 'lib/flexmock/expectation.rb', line 145

def eligible?
  @count_validators.all? { |v| v.eligible?(@actual_count) }
end

#explicitly ⇒ Object

No-op for allowing explicit calls when explicit not explicitly needed.



531
532
533
 
# File 'lib/flexmock/expectation.rb', line 531

def explicitly
  self
end

#flexmock_location_filter ⇒ Object 



540
541
542
543
544
545
546
547
548
549
 
# File 'lib/flexmock/expectation.rb', line 540

def flexmock_location_filter
  yield
rescue Exception => ex
  bt = @location.dup
  flexmock_dir = File.expand_path(File.dirname(__FILE__))
  while bt.first.start_with?(flexmock_dir)
      bt.shift
  end
  raise ex, ex.message, bt
end

#flexmock_verify ⇒ Object

Validate the correct number of calls have been made. Called by the teardown process.



166
167
168
169
170
171
172
 
# File 'lib/flexmock/expectation.rb', line 166

def flexmock_verify
  @count_validators.each do |v|
    v.validate(@actual_count)
  end
rescue CountValidator::ValidationFailed => e
  FlexMock.framework_adapter.make_assertion(e.message, @location) { false }
end

#globally ⇒ Object

Modifier that changes the next ordered constraint to apply globally across all mock objects in the container.



505
506
507
508
 
# File 'lib/flexmock/expectation.rb', line 505

def globally
  @globally = true
  self
end

#match_args(args, kw, block) ⇒ Object

Does the argument list match this expectation’s argument specification.



176
177
178
 
# File 'lib/flexmock/expectation.rb', line 176

def match_args(args, kw, block)
  ArgumentMatching.all_match?(@expected_args, @expected_kw, @expected_block, args, kw, block)
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.



425
426
427
 
# File 'lib/flexmock/expectation.rb', line 425

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.



432
433
434
 
# File 'lib/flexmock/expectation.rb', line 432

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



493
494
495
496
497
498
499
500
501
 
# File 'lib/flexmock/expectation.rb', line 493

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 



393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/flexmock/expectation.rb', line 393

def pass_thru(&block)
  block ||= lambda { |value| value }
  and_return { |*args, **kw, &orig_block|
    begin
      block.call(@mock.flexmock_invoke_original(@sym, args, kw, orig_block))
    rescue NoMethodError => e
      if e.name == @sym
        raise e, "#{e.message} 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.



416
417
418
419
420
 
# File 'lib/flexmock/expectation.rb', line 416

def times(limit)
  @count_validators << @count_validator_class.new(self, limit) unless limit.nil?
  @count_validator_class = ExactCountValidator
  self
end

#to_s ⇒ Object 



54
55
56
 
# File 'lib/flexmock/expectation.rb', line 54

def to_s
  FlexMock.format_call(@sym, @expected_args, @expected_kw)
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.



439
440
441
 
# File 'lib/flexmock/expectation.rb', line 439

def twice
  times(2)
end

#validate_eligible ⇒ Object

Validate that this expectation is eligible for an extra call



80
81
82
83
84
85
86
87
88
 
# File 'lib/flexmock/expectation.rb', line 80

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.message) { false }
end

#validate_signature(args, kw, block) ⇒ Object 



90
91
92
93
94
 
# File 'lib/flexmock/expectation.rb', line 90

def validate_signature(args, kw, block)
  @signature_validator.validate(args, kw, block)
rescue SignatureValidator::ValidationFailed => e
  FlexMock.framework_adapter.check(e.message) { false }
end

#verify_call(args, kw, block) ⇒ Object

Verify the current call with the given arguments matches the expectations recorded in this object.



98
99
100
101
102
103
104
105
 
# File 'lib/flexmock/expectation.rb', line 98

def verify_call(args, kw, block)
  validate_eligible
  validate_order
  validate_signature(args, kw, block)
  @actual_count += 1
  perform_yielding(block)
  return_value(args, kw, block)
end

#with(*args, **kw) ⇒ Object

Declare that the method should expect the given argument list.



181
182
183
184
185
 
# File 'lib/flexmock/expectation.rb', line 181

def with(*args, **kw)
  @expected_args = args
  @expected_kw = kw
  self
end

#with_any_args ⇒ Object

Declare that the method can be called with any number of arguments of any type.



194
195
196
197
198
 
# File 'lib/flexmock/expectation.rb', line 194

def with_any_args
  @expected_args = nil
  @expected_kw = nil
  self
end

#with_any_kw_args ⇒ Object

Declare that the method can be called with any number of arguments of any type.



202
203
204
205
 
# File 'lib/flexmock/expectation.rb', line 202

def with_any_kw_args
  @expected_kw = nil
  self
end

#with_any_positional_args ⇒ Object

Declare that the method can be called with any number of arguments of any type.



209
210
211
212
 
# File 'lib/flexmock/expectation.rb', line 209

def with_any_positional_args
  @expected_args = nil
  self
end

#with_block ⇒ Object

Declare that the call should have a block



222
223
224
225
 
# File 'lib/flexmock/expectation.rb', line 222

def with_block
  @expected_block = true
  self
end

#with_kw_args(kw) ⇒ Object

Declare that the method should be called with the given keyword arguments



216
217
218
219
 
# File 'lib/flexmock/expectation.rb', line 216

def with_kw_args(kw)
  @expected_kw = kw
  self
end

#with_no_args ⇒ Object

Declare that the method should be called with no arguments.



188
189
190
 
# File 'lib/flexmock/expectation.rb', line 188

def with_no_args
  with
end

#with_no_block ⇒ Object

Declare that the call should have a block



228
229
230
231
 
# File 'lib/flexmock/expectation.rb', line 228

def with_no_block
  @expected_block = false
  self
end

#with_optional_block ⇒ Object 



233
234
235
236
 
# File 'lib/flexmock/expectation.rb', line 233

def with_optional_block
  @expected_block = nil
  self
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



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/flexmock/expectation.rb', line 239

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



258
259
260
261
262
 
# File 'lib/flexmock/expectation.rb', line 258

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.



409
410
411
 
# File 'lib/flexmock/expectation.rb', line 409

def zero_or_more_times
  at_least.never
end