mockify - Library core

Library core module.

Deprecated since version 0.9.0: To import Mockify’s core functionality, import from mockify.core module instead.

class mockify.Call(_name_, *args, **kwargs)

An object representing mock call.

Instances of this class are created when expectations are recorded or when mock is called. Call objects are comparable. Two call objects are equal if and only if:

  • mock names are the same,
  • args are the same,
  • and keyword args are the same.
Parameters:_name_ – The name of a mock
name

The name of a mock.

args

Positional args mock was called with or is expected to be called with.

kwargs

Keyword args mock was called with or is expected to be called with.

location

Information of place in test or tested code where this call object was created.

New in version 0.6.

Return type:mockify.core.LocationInfo
class mockify.LocationInfo(filename, lineno)

A placeholder for file name and line number obtained from the stack.

Used by mockify.core.Call objects to get their location in the code. That information is later used in assertion messages.

New in version 0.6.

Parameters:
  • filename – Name of the file
  • lineno – Line number in given file
filename

File name from stack.

lineno

Line number form stack.

classmethod get_external()

Factory method for creating instances of this class.

It extracts stack and finds (in reversed order) first frame that is outside of the Mockify library. Thanks to this all mock calls or expectation recordings will point to test function or tested code that uses Mockify, not to Mockify’s internals.

Return type:mockify.core.LocationInfo
class mockify.Session

A class providing core logic of connecting mock calls with recorded expectations.

Sessions are created for each mock automatically, or can be created explicitly and then shared across multiple mocks. While mock classes can be seen as som kind of frontends that mimic behavior of various Python constructs, session instances are some kind of backends that receive mockify.core.Call instances created by mocks during either mock call, or expectation recording.

Changed in version 0.6: Previously this was named Registry.

config

A dictionary-like object for configuring sessions.

Following options are currently available:

'expectation_class'

Can be used to override expectation class used when expectations are recorded.

By default, this is mockify.core.Expectation, and there is a requirement that custom class must inherit from original one.

'uninterested_call_strategy'

Used to set a way of processing so called unexpected calls, i.e. calls to mocks that has no expectations recorded. Following values are supported:

'fail'

This is default option.

When mock is called unexpectedly, mockify.exc.UninterestedCall exception is raised and test is terminated.

'warn'
Instead of raising exception, mockify.exc.UninterestedCallWarning warning is issued, and test continues.
'ignore'
Unexpected calls are silently ignored.
__call__(actual_call)

Trigger expectation matching actual_call received from mock being called.

This method is called on every mock call and basically all actual call processing takes place here. Values returned or exceptions raised by this method are also returned or raised by mock.

Parameters:actual_call – Instance of mockify.core.Call class created by calling mock.
expectations()

An iterator over all expectations recorded in this session.

Yields mockify.core.Expectation instances.

expect_call(expected_call)

Called by mock when expectation is recorded on it.

This method creates expectation object, adds it to the list of expectations, and returns.

Return type:mockify.Expectation
Parameters:expected_call –

Instance of mockify.core.Call created by mock when expect_call() was called on it.

Represents parameters the mock is expected to be called with.
assert_satisfied()

Check if all registered expectations are satisfied.

This works exactly the same as mockify.core.assert_satisfied(), but for given session only. Can be used as a replacement for any other checks if one global session object is used.

enable_ordered(names)

Mark expectations matching given mock names as ordered, so they will have to be resolved in their declaration order.

This is used internally by mockify.core.ordered().

disable_ordered()

Called by mockify.core.ordered() when processing of ordered expectations is done.

Moves any remaining expectations back to the unordered storage, so they will be later displayed as unsatisfied.

class mockify.Expectation(expected_call)

An class representing single expectation.

Instances of this class are created and returned by factory expect_call() method you will use to record expectations on your mocks:

>>> from mockify.mock import Mock
>>> mock = Mock('mock')
>>> mock.expect_call(1, 2)
<mockify.Expectation: mock(1, 2)>
Parameters:expected_call – Instance of Call class containing parameters passed to expect_call() factory method that created this expectation object.
__call__(actual_call)

Call this expectation object.

If given call object does not match expected_call then this method will raise TypeError exception.

Otherwise, total call count is increased by one and:

  • if actions are recorded, then next action is executed and its result returned or mockify.exc.OversaturatedCall exception is raised if there are no more actions
  • if there are no actions recorded, just None is returned
is_satisfied()

Check if this expectation is satisfied.

Expectation object is satisfied if and only if:

  • total number of calls is not exceeding expected number of calls,
  • all actions (if any were recorded) are consumed.
Return type:bool
times(cardinality)

Set expected number or range of call counts.

Following values are possible:

See Setting expected call count tutorial section for more details.

will_once(action)

Append next action to be executed when this expectation object receives a call.

Once this method is called, it returns special proxy object that you can use to mutate this expectation even further by calling one of given methods on that proxy:

Thanks to that you can record so called action chains (see Recording actions for more details).

This method can be called with any action object from mockify.actions as an argument.

will_repeatedly(action)

Attach so called repeated action to be executed when this expectation is called.

Unlike single actions, recorded with will_once(), repeated actions are by default executed any number of times, including zero (see Repeated actions for more details).

Once this method is called, it returns a proxy object you can use to adjust repeated action even more by calling one of following methods:

  • times(), used to record repeated action call count limits (see times()).

This method accepts actions defined in mockify.actions module.

expected_call

Returns expected_call parameter passed during construction.

This is used when this expectation is compared with mockify.core.Call object representing actual call, to find expectations matching that call.

Return type:mockify.core.Call
actual_call_count

Number of matching calls this expectation object received so far.

This is relative value; if one action expires and another one is started to be executed, then the counter starts counting from 0 again. Thanks to this you’ll receive information about actual action execution count. If your expectation does not use will_once() or will_repeatedly(), then this counter will return total number of calls.

New in version 0.6.

expected_call_count

Return object representing expected number of mock calls.

Like actual_call_count, this varies depending on internal expectation object state.

Return type:mockify.cardinality.ExpectedCallCount
action

Return action to be executed when this expectation receives another call or None if there are no (more) actions.

Return type:mockify.actions.Action
mockify.assert_satisfied(*mocks)

Check if all given mocks are satisfied.

This function collects all expectations from given mock for which mockify.core.Expectation.is_satisfied() evaluates to False. Finally, if at least one unsatisfied expectation is found, this method raises mockify.exc.Unsatisfied exception.

mockify.ordered(*mocks)

Context manager that checks if expectations in wrapped scope are consumed in same order as they were defined.

This context manager will raise mockify.exc.UnexpectedCallOrder assertion on first found mock that is executed out of specified order.

See Recording ordered expectations for more details.

mockify.satisfied(*mocks)

Context manager wrapper for assert_satisfied().

mockify.patched(*mocks)

Context manager that replaces imported objects and functions with their mocks using mock name as a name of patched module.

It will patch only functions or objects that have expectations recorded, so all needed expectations will have to be recorded before this context manager is used.

See Patching imported modules for more details.