Object
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)
Create an expectation for a method named sym.
# File lib/flexmock/expectation.rb, line 34 34: def initialize(mock, sym) 35: @mock = mock 36: @sym = sym 37: @expected_args = nil 38: @count_validators = [] 39: @count_validator_class = ExactCountValidator 40: @actual_count = 0 41: @return_value = nil 42: @return_queue = [] 43: @yield_queue = [] 44: @order_number = nil 45: @global_order_number = nil 46: @globally = nil 47: end
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.
# File lib/flexmock/expectation.rb, line 252 252: def and_raise(exception, *args) 253: and_return { raise exception, *args } 254: end
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.
# File lib/flexmock/expectation.rb, line 188 188: def and_return(*args, &block) 189: if block_given? 190: @return_queue << block 191: else 192: args.each do |arg| 193: @return_queue << lambda { |*a| arg } 194: end 195: end 196: self 197: end
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.
# File lib/flexmock/expectation.rb, line 212 212: def and_return_undefined 213: and_return(FlexMock.undefined) 214: end
Declares that the method will throw the given symbol (with an optional value) when executed.
throws is an alias for and_throw.
# File lib/flexmock/expectation.rb, line 266 266: def and_throw(sym, value=nil) 267: and_return { throw sym, value } 268: end
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.
# File lib/flexmock/expectation.rb, line 228 228: def and_yield(*yield_values) 229: @yield_queue << yield_values 230: end
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
# File lib/flexmock/expectation.rb, line 314 314: def at_least 315: @count_validator_class = AtLeastCountValidator 316: self 317: end
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
# File lib/flexmock/expectation.rb, line 327 327: def at_most 328: @count_validator_class = AtMostCountValidator 329: self 330: end
# File lib/flexmock/expectation.rb, line 388 388: def by_default 389: expectations = mock.flexmock_expectations_for(@sym) 390: expectations.defaultify_expectation(self) if expectations 391: end
Is this expectation constrained by any call counts?
# File lib/flexmock/expectation.rb, line 104 104: def call_count_constrained? 105: ! @count_validators.empty? 106: end
Is this expectation eligible to be called again? It is eligible only if all of its count validators agree that it is eligible.
# File lib/flexmock/expectation.rb, line 99 99: def eligible? 100: @count_validators.all? { |v| v.eligible?(@actual_count) } 101: end
Validate the correct number of calls have been made. Called by the teardown process.
# File lib/flexmock/expectation.rb, line 121 121: def flexmock_verify 122: @count_validators.each do |v| 123: v.validate(@actual_count) 124: end 125: end
Modifier that changes the next ordered constraint to apply globally across all mock objects in the container.
# File lib/flexmock/expectation.rb, line 368 368: def globally 369: @globally = true 370: self 371: end
Does the expected argument match the corresponding actual value.
# File lib/flexmock/expectation.rb, line 138 138: def match_arg(expected, actual) 139: expected === actual || 140: expected == actual || 141: ( Regexp === expected && expected === actual.to_s ) 142: end
Does the argument list match this expectation’s argument specification.
# File lib/flexmock/expectation.rb, line 129 129: def match_args(args) 130: # TODO: Rethink this: 131: # return false if @expected_args.nil? 132: return true if @expected_args.nil? 133: return false if args.size != @expected_args.size 134: (0...args.size).all? { |i| match_arg(@expected_args[i], args[i]) } 135: end
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
# File lib/flexmock/expectation.rb, line 356 356: def ordered(group_name=nil) 357: if @globally 358: @global_order_number = define_ordered(group_name, @mock.flexmock_container) 359: else 360: @order_number = define_ordered(group_name, @mock) 361: end 362: @globally = false 363: self 364: end
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.
# File lib/flexmock/expectation.rb, line 279 279: def times(limit) 280: @count_validators << @count_validator_class.new(self, limit) unless limit.nil? 281: @count_validator_class = ExactCountValidator 282: self 283: end
# File lib/flexmock/expectation.rb, line 49 49: def to_s 50: FlexMock.format_args(@sym, @expected_args) 51: end
Verify the current call with the given arguments matches the expectations recorded in this object.
# File lib/flexmock/expectation.rb, line 55 55: def verify_call(*args) 56: validate_order 57: @actual_count += 1 58: perform_yielding(args) 59: return_value(args) 60: end
Declare that the method should expect the given argument list.
# File lib/flexmock/expectation.rb, line 145 145: def with(*args) 146: @expected_args = args 147: self 148: end
Declare that the method can be called with any number of arguments of any type.
# File lib/flexmock/expectation.rb, line 157 157: def with_any_args 158: @expected_args = nil 159: self 160: end
Helper method for defining ordered expectations.
# File lib/flexmock/expectation.rb, line 374 374: def define_ordered(group_name, ordering) 375: fail UsageError, "Mock #{@mock.flexmock_name} is not in a container and cannot be globally ordered." if ordering.nil? 376: if group_name.nil? 377: result = ordering.flexmock_allocate_order 378: elsif (num = ordering.flexmock_groups[group_name]) 379: result = num 380: else 381: result = ordering.flexmock_allocate_order 382: ordering.flexmock_groups[group_name] = result 383: end 384: result 385: end
Yield stored values to any blocks given.
# File lib/flexmock/expectation.rb, line 83 83: def perform_yielding(args) 84: @return_value = nil 85: unless @yield_queue.empty? 86: block = args.last 87: values = (@yield_queue.size == 1) ? @yield_queue.first : @yield_queue.shift 88: if block && block.respond_to?(:call) 89: @return_value = block.call(*values) 90: else 91: fail MockError, "No Block given to mock with 'and_yield' expectation" 92: end 93: end 94: end
Find the return value for this expectation. (private version)
# File lib/flexmock/expectation.rb, line 69 69: def return_value(args) 70: case @return_queue.size 71: when 0 72: block = lambda { |*args| @return_value } 73: when 1 74: block = @return_queue.first 75: else 76: block = @return_queue.shift 77: end 78: block.call(*args) 79: end
Validate that the order
# File lib/flexmock/expectation.rb, line 109 109: def validate_order 110: if @order_number 111: @mock.flexmock_validate_order(to_s, @order_number) 112: end 113: if @global_order_number 114: @mock.flexmock_container.flexmock_validate_order(to_s, @global_order_number) 115: end 116: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.