Class: FlexMock::Expectation

Inherits:
Object
  • Object
show all
Defined in:
lib/gems/flexmock-0.8.3/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) ⇒ Expectation

Create an expectation for a method named sym.



34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 34

def initialize(mock, sym)
  @mock = mock
  @sym = sym
  @expected_args = nil
  @count_validators = []
  @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.



30
31
32
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 30

def expected_args
  @expected_args
end

#mock ⇒ Object

Returns the value of attribute mock.



31
32
33
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 31

def mock
  @mock
end

#order_number ⇒ Object (readonly)

Returns the value of attribute order_number.



30
31
32
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 30

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).



64
65
66
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 64

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



252
253
254
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 252

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.



188
189
190
191
192
193
194
195
196
197
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 188

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.



212
213
214
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 212

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.



266
267
268
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 266

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.



228
229
230
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 228

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



314
315
316
317
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 314

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



327
328
329
330
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 327

def at_most
  @count_validator_class = AtMostCountValidator
  self
end

#by_default ⇒ Object 



388
389
390
391
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 388

def by_default
  expectations = mock.flexmock_expectations_for(@sym)
  expectations.defaultify_expectation(self) if expectations
end

#call_count_constrained? ⇒ Boolean

Is this expectation constrained by any call counts?

Returns:

  • (Boolean) 


104
105
106
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 104

def call_count_constrained?
  ! @count_validators.empty?
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) 


99
100
101
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 99

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

#flexmock_verify ⇒ Object

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



121
122
123
124
125
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 121

def flexmock_verify
  @count_validators.each do |v|
    v.validate(@actual_count)
  end
end

#globally ⇒ Object

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



368
369
370
371
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 368

def globally
  @globally = true
  self
end

#match_arg(expected, actual) ⇒ Object

Does the expected argument match the corresponding actual value.



138
139
140
141
142
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 138

def match_arg(expected, actual)
  expected === actual ||
  expected == actual ||
  ( Regexp === expected && expected === actual.to_s )
end

#match_args(args) ⇒ Object

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



129
130
131
132
133
134
135
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 129

def match_args(args)
  # TODO: Rethink this:
  # return false if @expected_args.nil?
  return true if @expected_args.nil?
  return false if args.size != @expected_args.size
  (0...args.size).all? { |i| match_arg(@expected_args[i], args[i]) }
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.



288
289
290
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 288

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.



295
296
297
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 295

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



356
357
358
359
360
361
362
363
364
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 356

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

#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.



279
280
281
282
283
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 279

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

#to_s ⇒ Object 



49
50
51
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 49

def to_s
  FlexMock.format_args(@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.



302
303
304
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 302

def twice
  times(2)
end

#verify_call(*args) ⇒ Object

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



55
56
57
58
59
60
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 55

def verify_call(*args)
  validate_order
  @actual_count += 1
  perform_yielding(args)
  return_value(args)
end

#with(*args) ⇒ Object

Declare that the method should expect the given argument list.



145
146
147
148
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 145

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.



157
158
159
160
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 157

def with_any_args
  @expected_args = nil
  self
end

#with_no_args ⇒ Object

Declare that the method should be called with no arguments.



151
152
153
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 151

def with_no_args
  with
end

#zero_or_more_times ⇒ Object

Declare that the method may be called any number of times.



272
273
274
 
# File 'lib/gems/flexmock-0.8.3/lib/flexmock/expectation.rb', line 272

def zero_or_more_times
  at_least.never
end