Class: FlexMock::Expectation

### Home Classes Methods

### In Files

- lib/flexmock/expectation.rb

### Parent

Object

### Methods

- ::new
- #and_raise
- #and_return
- #and_return_undefined
- #and_throw
- #and_yield
- #at_least
- #at_most
- #by_default
- #call_count_constrained?
- #description
- #eligible?
- #explicitly
- #flexmock_location_filter
- #flexmock_verify
- #globally
- #match_args
- #never
- #once
- #ordered
- #pass_thru
- #raises
- #returns
- #returns_undefined
- #throws
- #times
- #to_s
- #twice
- #verify_call
- #with
- #with_any_args
- #with_no_args
- #yields
- #zero_or_more_times

### Files

- CHANGES
- GoogleExample.rdoc
- rspec_examples_spec.rdoc
- test_unit_examples_test.rdoc
- index.rdoc
- flexmock-0.4.0.rdoc
- flexmock-0.4.1.rdoc
- flexmock-0.4.2.rdoc
- flexmock-0.4.3.rdoc
- flexmock-0.5.0.rdoc
- flexmock-0.5.1.rdoc
- flexmock-0.6.0.rdoc
- flexmock-0.6.1.rdoc
- flexmock-0.6.2.rdoc
- flexmock-0.6.3.rdoc
- flexmock-0.6.4.rdoc
- flexmock-0.7.0.rdoc
- flexmock-0.7.1.rdoc
- flexmock-0.8.0.rdoc
- flexmock-0.8.2.rdoc
- flexmock-0.8.3.rdoc
- flexmock-0.8.4.rdoc
- flexmock-0.8.5.rdoc
- flexmock-0.9.0.rdoc
- flexmock-1.0.0.rdoc
- flexmock-1.0.3.rdoc
- flexmock-1.0.4.rdoc
- flexmock-1.1.0.rdoc
- flexmock-1.2.0.rdoc
- flexmock-1.3.0.rdoc
- flexmock-1.3.1.rdoc

### Class/Module Index

Quicksearch

- FlexMock
- FlexMock::AnyMatcher
- FlexMock::ArgumentMatching
- FlexMock::ArgumentTypes
- FlexMock::AtLeastCountValidator
- FlexMock::AtMostCountValidator
- FlexMock::CallValidator
- FlexMock::CompositeExpectation
- FlexMock::CountValidator
- FlexMock::DefaultFrameworkAdapter
- FlexMock::DefaultFrameworkAdapter::AssertionFailedError
- FlexMock::DuckMatcher
- FlexMock::EqualMatcher
- FlexMock::ExactCountValidator
- FlexMock::Expectation
- FlexMock::ExpectationBuilder
- FlexMock::ExpectationDirector
- FlexMock::ExpectationRecorder
- FlexMock::ExplicitNeeded
- FlexMock::ExtensionRegistry
- FlexMock::Extensions
- FlexMock::Extensions::ActiveRecordModel
- FlexMock::GenericTestCase
- FlexMock::HashMatcher
- FlexMock::MockBuilder
- FlexMock::MockContainer
- FlexMock::MockError
- FlexMock::OptionalProcMatcher
- FlexMock::Ordering
- FlexMock::PartialMockProxy
- FlexMock::ProcMatcher
- FlexMock::RSpecFrameworkAdapter
- FlexMock::RSpecFrameworkAdapter::AssertionFailedError
- FlexMock::RSpecMatchers
- FlexMock::RSpecMatchers::HaveReceived
- FlexMock::Recorder
- FlexMock::SpyDescribers
- FlexMock::TestCase
- FlexMock::TestUnitAssertions
- FlexMock::TestUnitFrameworkAdapter
- FlexMock::Undefined
- FlexMock::UsageError
- FlexMock::UseContainer
- FlexMock::Version
- MiniTest
- MiniTest::Unit
- MiniTest::Unit::TestCase
- Test
- Test::Unit
- Test::Unit::TestCase
- Class
- Module
- Object
- Symbol

No matching classes.

# FlexMock::Expectation

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)

### Attributes

expected_args[R]
mock[RW]
order_number[R]

### Public Class Methods

new(mock, sym, location) click to toggle source

Create an expectation for a method named `sym`.

    # File lib/flexmock/expectation.rb, line 35
    def initialize(mock, sym, location)
      @mock = mock
      @sym = sym
      @location = location
      @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

### Public Instance Methods

and_raise(an_exception) click to toggle source
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`.

    # File lib/flexmock/expectation.rb, line 259
    def and_raise(exception, *args)
      and_return { raise exception, *args }
    end

Also aliased as: raises
and_return(value) click to toggle source
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`.

    # File lib/flexmock/expectation.rb, line 195
    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

Also aliased as: returns
and_return_undefined() click to toggle source

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 219
    def and_return_undefined
      and_return(FlexMock.undefined)
    end

Also aliased as: returns_undefined
and_throw(a_symbol) click to toggle source
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`.

    # File lib/flexmock/expectation.rb, line 273
    def and_throw(sym, value=nil)
      and_return { throw sym, value }
    end

Also aliased as: throws
and_yield(value1, value2, ...) click to toggle source

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 235
    def and_yield(*yield_values)
      @yield_queue << yield_values
    end

Also aliased as: yields
at_least() click to toggle source

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 328
    def at_least
      @count_validator_class = AtLeastCountValidator
      self
    end

at_most() click to toggle source

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 341
    def at_most
      @count_validator_class = AtMostCountValidator
      self
    end

by_default() click to toggle source

    # File lib/flexmock/expectation.rb, line 412
    def by_default
      expectations = mock.flexmock_expectations_for(@sym)
      expectations.defaultify_expectation(self) if expectations
    end

call_count_constrained?() click to toggle source

Is this expectation constrained by any call counts?

    # File lib/flexmock/expectation.rb, line 122
    def call_count_constrained?
      ! @count_validators.empty?
    end

description() click to toggle source

Return a description of the matching features of the expectation. Matching features include:

- name of the method

- argument matchers

- call count validators

    # File lib/flexmock/expectation.rb, line 62
    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
      result
    end

eligible?() click to toggle source

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 117
    def eligible?
      @count_validators.all? { |v| v.eligible?(@actual_count) }
    end

explicitly() click to toggle source

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

    # File lib/flexmock/expectation.rb, line 408
    def explicitly
      self
    end

flexmock_location_filter() click to toggle source

    # File lib/flexmock/expectation.rb, line 417
    def flexmock_location_filter
      yield
    rescue Exception => ex
      ex.backtrace.insert(0, @location)
      raise ex
    end

flexmock_verify() click to toggle source

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

    # File lib/flexmock/expectation.rb, line 139
    def flexmock_verify
      @count_validators.each do |v|
        v.validate(@actual_count)
      end
    end

globally() click to toggle source

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

    # File lib/flexmock/expectation.rb, line 382
    def globally
      @globally = true
      self
    end

match_args(args) click to toggle source

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

    # File lib/flexmock/expectation.rb, line 147
    def match_args(args)
      ArgumentMatching.all_match?(@expected_args, args)
    end

never() click to toggle source

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.

    # File lib/flexmock/expectation.rb, line 302
    def never
      times(0)
    end

once() click to toggle source

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.

    # File lib/flexmock/expectation.rb, line 309
    def once
      times(1)
    end

ordered(group_name=nil) click to toggle source

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 370
    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) click to toggle source

    # File lib/flexmock/expectation.rb, line 278
    def pass_thru(&block)
      block ||= lambda { |value| value }
      and_return { |*args|
        block.call(@mock.flexmock_invoke_original(@sym, args))
      }
    end

raises(exception, *args) click to toggle source
Alias for: and_raise
returns(*args, &block) click to toggle source
Alias for: and_return
returns_undefined() click to toggle source
Alias for: and_return_undefined
throws(sym, value=nil) click to toggle source
Alias for: and_throw
times(limit) click to toggle source

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 293
    def times(limit)
      @count_validators << @count_validator_class.new(self, limit) unless limit.nil?
      @count_validator_class = ExactCountValidator
      self
    end

to_s() click to toggle source

    # File lib/flexmock/expectation.rb, line 51
    def to_s
      FlexMock.format_call(@sym, @expected_args)
    end

twice() click to toggle source

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.

    # File lib/flexmock/expectation.rb, line 316
    def twice
      times(2)
    end

verify_call(*args) click to toggle source

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

    # File lib/flexmock/expectation.rb, line 73
    def verify_call(*args)
      validate_order
      @actual_count += 1
      perform_yielding(args)
      return_value(args)
    end

with(*args) click to toggle source

Declare that the method should expect the given argument list.

    # File lib/flexmock/expectation.rb, line 152
    def with(*args)
      @expected_args = args
      self
    end

with_any_args() click to toggle source

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

    # File lib/flexmock/expectation.rb, line 164
    def with_any_args
      @expected_args = nil
      self
    end

with_no_args() click to toggle source

Declare that the method should be called with no arguments.

    # File lib/flexmock/expectation.rb, line 158
    def with_no_args
      with
    end

yields(*yield_values) click to toggle source
Alias for: and_yield
zero_or_more_times() click to toggle source

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

    # File lib/flexmock/expectation.rb, line 286
    def zero_or_more_times
      at_least.never
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.