mockify.abc - ABC classes for Mockify

Added in version 0.13.

ABC classes for Mockify.

class mockify.abc.IAction

Bases: ABC

An interface to be implemented by mock actions.

Actions are registered on mocks with a help of IExpectation.will_once() and IExpectation.will_repeatedly() methods and are used to set what the mock must do once called by code being under test. The most trivial action is to set a mock return value, or force it to raise given exception. Please proceed to mockify.actions to get familiar with a bulk of built-in implementations.

abstract __call__(actual_call: ICall) Any | None

Action body.

This is the place where actual action execution takes place.

Parameters:

actual_call

Mock call params wrapped with ICall object.

Use this to get access to parameters passed to mock when it was called by code being under test.

class mockify.abc.ICall

Bases: ABC

An interface to be implemented by objects containing mock call information.

This information include:

  • full name of the mock

  • positional and keyword arguments the mock was called or is expected to be called with

  • location in user’s code under test that created this mock object

Call objects are created by mocks when mock receives a call from code being under test (so called actual call), or when expectation is recorded on a mock (so called expected call). Since call objects can be tested for (in)equality, Mockify internals can easily decide if expectation was met or not.

abstract property args: Tuple[Any]

Positional args passed to the call object during creation.

abstract property kwargs: Dict[str, Any]

Named args passed to the call object during creation.

abstract property location: ICallLocation

A place in user’s source code where this call object was created.

abstract property name: str

Full name of a mock for which this object was created.

class mockify.abc.ICallLocation

Bases: ABC

An interface to be implemented by classes used to obtain call location (file name and line number) from the stack.

This is used when instance of ICall is created to find a place in the code, where particular call object was created.

Instances of ICallLocation can be checked for (in)equality. Two call location objects are equal if and only if:

  • filename in both objects is the same

  • and lineno in both objects is the same

abstract property filename: str

File name.

abstract property lineno: int

Line number (within file given by filename).

class mockify.abc.IExpectation

Bases: ABC

Represents single expectation recorded on a mock.

Instances of this class are created by mock’s expect_call() method or by using functions from mockify.expect module.

class IWillOnceMutation

Bases: ABC

Provides return value annotation and interface for will_once() methods.

abstract will_once(action: IAction) IWillOnceMutation

Attach next action to the end of action chain of current expectation object.

See IExpectation.will_once() for more details.

abstract will_repeatedly(action: IAction) IWillRepeatedlyMutation

Finalize action chain with a repeated action.

See IExpectation.will_repeatedly() for more details.

class IWillRepeatedlyMutation

Bases: ABC

Provides return value annotation and interface for will_repeatedly() methods.

abstract times(value: int | IExpectedCallCountMatcher)

Used to configure how many times repeated action is expected to be called by a mock.

See IExpectation.times() for more details.

abstract is_satisfied() bool

Check if this expectation object is satisfied.

Expectations are satisfied if and only if:

  • all recorded one-shot actions were consumed

  • number of calls being made is within expected call count range

This method is used by Mockify’s internals to collect all unsatisfied expectations and raise mockify.exc.Unsatisfied exception.

abstract times(value: int | IExpectedCallCountMatcher)

Set expected call count of this expectation object.

Following values are possible:

  • when int parameter is used as a value, then expectation is expected to be called exactly value times,

  • when IExpectedCallCountMatcher object is used as a value, then number of allowed expected calls depends on particular object that was used as a value (whether it was minimal, maximal or a range of expected call counts)

See Setting expected call count tutorial section for more details.

Parameters:

value

Expected call count value.

This can be either a positive integer number (for a fixed expected call count), or an instance of IExpectedCallCountMatcher class (for a more sophisticated expected call counts, like ranges etc.)

abstract will_once(action: IAction) IWillOnceMutation

Attach next one-shot action to the end of the action chain of this expectation.

When expectation is consumed, actions are consumed as well. If expectation is consumed for the first time, then first action is called. If it is consumed for the second time, then second action is consumed and so on. If there are no more actions and mock is called again, then mockify.exc.OversaturatedCall exception is raised.

See Recording actions for more details about action chains.

Parameters:

action – Action to be performed

abstract will_repeatedly(action: IAction) IWillRepeatedlyMutation

Finalize action chain with a repeated action.

Repeated actions can by default be invoked indefinitely by mock, unless expected call count is set explicitly with mockify.abc.IExpectation.IWillRepeatedlyMutation.times() method on a returned object. This is also a good way to set mock’s default action.

Since repeated actions act in a different way than one-time actions, there is currently not possible to record one-time actions after repeated action is set.

See Repeated actions for more details about repeated actions.

Parameters:

action – Action to be performed

class mockify.abc.IExpectedCallCountMatcher

Bases: ABC

An interface to be implemented by classes that set expected call count ranges.

Instances of this class are used by IExpectation.times() and IExpectation.IWillRepeatedlyMutation.times() methods to set how many times the mock is expected to be called. You can find built-in implementations of this interface in mockify.cardinality module.

abstract match(actual_call_count: int) bool

Check if actual number of calls matches expected number of calls.

class mockify.abc.IMock

Bases: ABC

An interface to be implemented by mock classes.

In Mockify, mocks are organized in a tree-like structure. For example, to mock object with methods, Mockify is first creating a “root” mock representing object, and then supplies it with child nodes, each pointing to “root” as a parent, and each representing single mocked method of that object.

abstract __m_children__() Iterator[IMock]

An iterator over IMock objects representing direct children of this mock.

This SHOULD NOT include grandchildren.

abstract __m_expectations__() Iterator[IExpectation]

An iterator over IExpectation objects recorded for this mock.

This SHOULD NOT include expectations recorded for children of this mock.

__m_walk__() Iterator[IMock]

Recursively iterate over mock subtree, from root to leafs, using self as a root.

This method does that by recursively iterating over __m_children__() iterator.

It always yields self as first element.

property __m_fullname__: str

Full name of this mock.

This is calculated by prefixing __m_name__ of this mock with a __m_fullname__ property of this mock’s parent, using . as a separator.

If this mock has no parent, or parent does not have a name assigned, then this will be the same as __m_name__.

abstract property __m_name__: str

Name of this mock.

Mock names are used for error reporting, to precisely point to mock and method that caused error. For root mocks you will have to provide names manually, and for leaf mocks the names will be picked automatically, using name of a method that is being mocked.

This MUST BE a valid Python identifier, or a sequence of valid Python identifiers concatenated with a single . character.

For example, valid names are:

foo
bar
foobar123
_foo_bar_123
foo.bar.baz
abstract property __m_parent__: IMock | None

A reference to IMock object that is a parent of this mock.

If mock has no parent (i.e. if it’s a root mock), then this should return None.

abstract property __m_session__: ISession

Instance of ISession to be used by this mock.

Value returned by this property MUST meet following condition:

if self.__m_parent__ is not None:
    assert self.__m_session__ is self.__m_parent__.__m_session__

In other words, if this mock has a parent, than it MUST be attached to same session object as its parent.

class mockify.abc.ISession

Bases: ABC

An interface to be implemented by session classes.

In Mockify, sessions are used to keep track of recorded and consumed expectations of each mock sharing one session object. Every created IExpectation object is stored in the session attached to a mock being used and every call made to that mock is reported in that session. Thanks to this, Mockify can tell (at the end of each test) which expectations were consumed, and which were not.

abstract __call__(actual_call: ICall) Any | None

Called when mock is being called.

This method is called when any mock that has this session assigned is being called. Values returned or exceptions raised by this method are also returned or raised by a mock.

Parameters:

actual_call – Actual call object forwarded by caller

abstract expect_call(expected_call: ICall) IExpectation

Factory method that creates and registers expectations inside this session.

This is called by any mock that has this session assigned during expectation recording on that mock.

Parameters:

expected_call – Expected call object forwarded by caller

abstract expectations() Iterator[IExpectation]

Return iterator over all registered expectations.