API Reference¶
Mocking frontends¶
Mocking frontends are used to provide easy to use interface on top of classes
from mockify.engine
module that act like a backend.
So instead of doing this:
>>> from mockify.engine import Call, Registry
>>> reg = Registry()
>>> reg.expect_call(Call('foo', (1, 2)), 'foo.py', 123)
<mockify.Expectation: foo(1, 2)>
>>> reg(Call('foo', (1, 2)))
>>> reg.assert_satisfied()
You use a frontend to do the same much easier:
>>> from mockify.mock.function import Function
>>> foo = Function('foo')
>>> foo.expect_call(1, 2)
<mockify.Expectation: foo(1, 2)>
>>> foo(1, 2)
>>> foo.assert_satisfied()
mockify.mock.function
- Frontends for mocking functions¶
-
class
mockify.mock.function.
Function
(name, registry=None)¶ Bases:
object
Class for mocking Python functions.
Example usage:
>>> foo = Function('foo') >>> foo.expect_call(1, 2).times(2) <mockify.Expectation: foo(1, 2)> >>> for _ in range(2): ... foo(1, 2) >>> foo.assert_satisfied()
Parameters: - name – Mock function name
- registry –
This is optional.
Use this to pass custom instance of
mockify.engine.Registry
class if you need to share it between multiple frontends. Sharing is useful for example to check if all mocks are satisfied using oneassert_satisfied
call:>>> from mockify.engine import Registry >>> reg = Registry() >>> foo = Function('foo', registry=reg) >>> bar = Function('bar', registry=reg) >>> foo.expect_call() <mockify.Expectation: foo()> >>> bar.expect_call() <mockify.Expectation: bar()> >>> foo() >>> bar() >>> reg.assert_satisfied()
-
assert_satisfied
()¶ Assert that this function mock is satisfied.
This method just calls
mockify.engine.Registry.assert_satisfied()
withname
given via constructor as an argument.
-
expect_call
(*args, **kwargs)¶ Record call expectation.
This method creates
mockify.engine.Call
instance giving itargs
andkwargs
, fetches file and line number from current call stack and triggersmockify.engine.Registry.expect_call()
and returns expectation object it produces.
-
class
mockify.mock.function.
FunctionFactory
(registry=None)¶ Bases:
object
Helper factory class for easier function mocks creating.
This helper can be created with no params or with
mockify.engine.Registry
instance as parameter. It provides an easy way of function mock creating by simply getting factory attributes that become function mock names. Once such attribute is get for the first time,Function
instance is created, and later it is just returned.This allows to create function mocks as easy as in this example:
>>> factory = FunctionFactory() >>> factory.foo.expect_call() <mockify.Expectation: foo()> >>> factory.bar.expect_call(1, 2) <mockify.Expectation: bar(1, 2)>
Then pass to some unit under test:
>>> def unit_under_test(foo, bar): ... foo() ... bar(1, 2) >>> unit_under_test(factory.foo, factory.bar)
To finally check if all mocks registered in one
FunctionFactory
object are satisfied using one single call:>>> factory.assert_satisfied()
-
assert_satisfied
()¶ Check if all function mocks registered by this factory are satisfied.
This method simply calls
mockify.engine.Registry.assert_satisfied()
with names of all created mocks as arguments.
-
mockify.mock.object
- Frontends for mocking objects¶
-
class
mockify.mock.object.
Object
(name, registry=None)¶ Bases:
object
Mock frontend made for mocking Python objects.
This class requires custom subclass to be created and have following attributes defined:
__methods__
- Containing list of method names
__properties__
- Containing list of property names
For example, if you want to mock Python class that has methods
foo
andbar
, and propetyspam
, you would create following subclass:>>> class Mock(Object): ... __methods__ = ['foo', 'bar'] ... __properties__ = ['spam']
After that, class
Mock
can be instantiated like this:>>> mock = Mock('mock')
And then injected to some unit under test.
Parameters: - name – Name of this object mock instance
- registry –
This parameter is optional.
If you omit it, new instance of
mockify.engine.Registry
will be created and used by this object mock. This is useful if you already have registry instance that you want to share between many unrelated mock frontends.
-
assert_satisfied
()¶ Check if this mock object is satisfied.
This method checks (in one call) if all registered expectations (for all methods and all properties) are satisfied. If not, then
mockify.exc.Unsatisfied
exception is raised.
-
expect_call
(_name_, *args, **kwargs)¶ Record method call expectation.
This method requires one argument to be given - method name. All other are simply forwarded to underlying
mockify.mock.function.Function
object.Parameters: _name_ – Method name
-
expect_get
(name)¶ Record property get expectation.
Parameters: name – Property name
-
expect_set
(name, value)¶ Record property set expectation.
Parameters: - name – Property name
- value – Property value that is expected to be set.
mockify.engine
- Library core¶
This module contains set of classes that provides backend mechanism for storing and tracking call expectations.
-
class
mockify.engine.
Call
(name, args=None, kwargs=None)¶ Bases:
object
Binds mock name with arguments it was called with or it is expected to be called with.
Call objects are created in mock frontends (like
mockify.mock.function.Function
mock class) by methodsexpected_call
and__call__
by simply passing their argument toCall
constructor.Instances of this class are comparable. Two
Call
objects are equal if and only if all attributes (name
,args
andkwargs
) are the same. For example:>>> Call('foo') == Call('foo') True >>> Call('foo') != Call('bar') True >>> Call('foo', (1, 2), {'c': 3}) == Call('foo', (1, 2), {'c': 3}) True
Call objects can also be created with use of matchers, for example
mockify.matchers.Any
, that will match any value:>>> from mockify.matchers import _ >>> Call('foo', (_, _)) == Call('foo', (1, 2)) True >>> Call('foo', (_, _)) == Call('foo', (3, 4)) True
Parameters: - name – Function or method name.
- args – Positional arguments
- kwargs – Named arguments
-
args
¶ Mock positional args.
-
kwargs
¶ Mock named args.
-
name
¶ Mock name.
-
class
mockify.engine.
Expectation
(expected_call, filename, lineno)¶ Bases:
object
Class representing single expectation.
Instances of this class are normally created by registry objects using
Registry.expect_call()
method. Each instance of this class is correlated with exactly onemockify.engine.Call
object representing expected mock call pattern.After
Expectation
object is created by call to someexpect_call
method, it can be mutated using following methods:Parameters: - call – Instance of
mockify.engine.Call
representing expected mock call pattern - filename – File name were this expectation was created
- lineno – Line number where this expectation was created
-
__call__
(call)¶ Call this expectation object.
If given
call
object does not matchexpected_call
then this method will raiseTypeError
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
- if actions are recorded, then next action is executed and its
result returned or
-
expected_call
¶ Instance of
mockify.engine.Call
representing expected mock call pattern.This basically is exactly the same
Call
object as was passed toExpectation
constructor.
-
format_action
()¶ Return textual representation of next action to be executed.
This method uses action’s
__str__
method to render action name.Returns
None
if there were no actions recorded or all were consumed.This is used by
mockify.exc.Unsatisfied
exception when rendering error message.
-
format_actual
()¶ Return textual representation of how many times this expectation was called so far.
This is used by
mockify.exc.Unsatisfied
exception when rendering error message.
-
format_expected
()¶ Return textual representation of how many times this expectation is expected to be called.
This is used by
mockify.exc.Unsatisfied
exception when rendering error message.
-
format_location
()¶ Return textual representation of place (filename and lineno) where this expectation was created.
Basically, it just returns
[filename]:[lineno]
string, wherefilename
andlineno
are given viaExpectation
constructor.
-
is_satisfied
()¶ Check if this expectation is satisfied.
-
match
(call)¶ Check if
expected_call
matchescall
.
-
times
(expected_count)¶ Record how many times this expectation is expected to be called.
Parameters: expected_count – Expected call count.
This can be either integer number (exact call count) or instance of one of classes from
mockify.times
module.
-
will_once
(action)¶ Attach action to be executed when this expectation gets consumed.
This method can be used several times, making action chains. Once expectation is consumed, next action is executed and removed from the list. If there are no more actions, another call will fail with
mockify.exc.OversaturatedCall
exception.After this method is used, you can also use
will_repeatedly()
to record repeated action that will get executed after all single actions are consumed.Parameters: action – Action to be executed.
See
mockify.actions
for details.
-
will_repeatedly
(action)¶ Attach repeated action to be executed when this expectation is called.
This method is used to record one action that gets executed each time this expectation object is called. By default, when repeated action is recorded, expectation can be called any number of times (including zero).
After setting repeated action, you can also set expected call count using
times()
.Parameters: action – Action to be executed.
See
mockify.actions
for details.
- call – Instance of
-
class
mockify.engine.
Registry
(expectation_class=None)¶ Bases:
object
Acts like a database for
Expectation
objects.This class is used as a backend for higher level mocking utilities (a.k.a. frontends), like
mockify.mock.function.Function
mocking class. It provides methods to record, lookup and verifying of expectations.There can be many instances of registry classes, or one that can be shared between various mock frontends. For example, you can create one registry in setup code, then create various mocks inside your tests, to finally trigger
assert_satisfied()
of that single registry in test’s teardown code. Or you can just use frontends with their defaults. It is completely up to you.Parameters: expectation_class – This is optional.
Used to give custom subclass of
Expectation
to be used inside this registry.-
__call__
(call)¶ Call a mock.
When this method is called, registry performs a lookup of matching unsatisfied expectations and calls first expectation found. If there are no matching expectation, then
mockify.exc.UninterestedCall
exception is raised. If there are matching expectations but all are satisfied, then last is called (making it oversaturated).Parameters: call – Instance of mockify.engine.Call
class representing mock being called
-
assert_satisfied
(*names)¶ Assert that all expectations are satisfied.
If there is at least one unsatisfied expectation, then this method will raise
mockify.exc.Unsatisfied
exception containing list of failed expectations.This method can be called as many times as you want.
Changed in version 0.2: Accepts names of mocks to check as positional args. If one or more names are given, then this method limits checking only to mocks of matching names.
-
expect_call
(call, filename, lineno)¶ Register expectation.
Returns instance of
expectation_class
(usuallyExpectation
) representing newly created expectation.Parameters: - call – Instance of
mockify.engine.Call
class representing exact mock call or a pattern (if created with matchers) that is expected to be executed - filename – Path to file were expectation is created
- lineno – Line number (inside
filename
) where expectation is created
- call – Instance of
-
mockify.actions
- Actions for use with will_once or will_repeatedly¶
Module containing predefined actions that can be used as argument for
Expectation.will_once()
or Expectation.will_repeatedly()
.
Basically, any class containing following methods is considered an action:
__str__(self)
Returning string representation of an action.
This is used for error reporting.
__call__(self, *args, **kwargs)
Method that is called when mock is called.
Entire action logic goes in here.
-
class
mockify.actions.
Invoke
(func)¶ Bases:
object
Makes mock invoking given function when called.
When mock is called, all arguments (if there are any) are passed to the
func
and its return value is returned as mock’s return value.Parameters: func – Function to be executed
mockify.exc
- Exceptions¶
-
exception
mockify.exc.
OversaturatedCall
(expectation, call)¶ Bases:
TypeError
Raised when mock is called more times than expected.
This exception will be thrown only if mock has actions defined as it does not know what to do next if all expected actions were already executed.
Parameters: - expectation – Instance of
mockify.engine.Expectation
class representing expectation that was oversaturated - call – Instance of
mockify.engine.Call
class representing mock call that oversaturatedexpectation
-
call
¶ Instance of
mockify.engine.Call
passed toOversaturatedCall
constructor.
-
expectation
¶ Instance of
mockify.engine.Expectation
passed toOversaturatedCall
constructor.
- expectation – Instance of
-
exception
mockify.exc.
UninterestedCall
(call)¶ Bases:
TypeError
Raised when uninterested mock is called.
Mockify requires each mock call to have matching expectation recorded. If none is found during call, then this exception is raised, terminating the test.
Parameters: call – Instance of mockify.engine.Call
class representing uinterested mock call-
call
¶ Instance of
mockify.engine.Call
passed toUninterestedCall
constructor.
-
-
exception
mockify.exc.
UninterestedGetterCall
(name)¶ Bases:
mockify.exc.UninterestedPropertyAccess
Raised when uninterested property getter is called.
This will be raised if some system under test gets mock property that has no expectations set.
New in version 0.3.
-
exception
mockify.exc.
UninterestedPropertyAccess
(name)¶ Bases:
TypeError
Base class for exceptions signalling uninterested property access.
This situation occurs when object property is accessed without previous matching expectation being recorded.
New in version 0.3.
Parameters: name – Property name -
name
¶ Name of property being accessed.
-
-
exception
mockify.exc.
UninterestedSetterCall
(name, value)¶ Bases:
mockify.exc.UninterestedPropertyAccess
Raised when uninterested property setter is called.
This will be raised if some system under test sets mock property that has no matching expectations set.
New in version 0.3.
-
value
¶ Value property was set to.
-
-
exception
mockify.exc.
Unsatisfied
(expectations)¶ Bases:
AssertionError
Raised by
mockify.engine.Registry.assert_satisfied()
method when there is at least one unsatisfied expectation.This exception displays explanatory information to the user:
- file location where unsatisfied expectation was recorded
- expected call pattern
- expected call count
- actual call count
- next action to be executed (if any)
Parameters: expectations – List of mockify.engine.Expectation
instances representing all unsatisfied expectations-
expectations
¶ Instance of
mockify.engine.Expectation
passed toUnsatisfied
constructor.
mockify.helpers
- Various helper utilities¶
-
mockify.helpers.
assert_satisfied
(*subjects)¶ Context manager for verifying multiple subjects at once.
Each passed subject must have
assert_satisfied
method defined, so it can be used withmockify.mock.function.Function
ormockify.engine.Registry
instances for example.Basically, the role of this helper is to ensure that all subjects become satisfied after leaving wrapped context. For example:
>>> from mockify.mock.function import Function >>> foo = Function('foo') >>> bar = Function('bar') >>> foo.expect_call() <mockify.Expectation: foo()> >>> bar.expect_call().times(0) <mockify.Expectation: bar()> >>> with assert_satisfied(foo, bar): ... foo()
And that’s it - you don’t have to explicitly check if
foo
andbar
are satisfied, because the helper will do it for you. And also it emphasizes part of code that actually uses given mocks.
mockify.matchers
- Matchers for use with expect_call¶
Module containing predefined matchers.
A matcher is every class that inherits from Matcher
and implements
following methods:
__repr__(self)
- Return matcher’s text representation.
__eq__(self, other)
Check if
self
is equal toother
.Here we use standard Python
__eq__
operator as it will be automatically executed by Python no matter where the matcher is used. But equality definition is completely up to the matcher implementation.
-
class
mockify.matchers.
Any
¶ Bases:
mockify.matchers.Matcher
Matcher that matches any value.
It is available also as
_
(underscore) single instance that can be imported from this module.For example, you can record expectation that mock must be called with one positional argument of any value but exactly 3 times:
>>> from mockify.matchers import _ >>> from mockify.mock.function import Function >>> foo = Function('foo') >>> foo.expect_call(_).times(3) <mockify.Expectation: foo(_)> >>> for i in range(3): ... foo(i) >>> foo.assert_satisfied()
-
class
mockify.matchers.
SaveArg
¶ Bases:
mockify.matchers.Matcher
Matcher that matches any value and keeps ordered track of unique values.
This can be used as a replacement for
Any
in case that you need to ensure that mock was called in specified order.For example:
>>> from mockify.mock.function import Function >>> arg = SaveArg() >>> foo = Function('foo') >>> foo.expect_call(arg).times(3) <mockify.Expectation: foo(SaveArg)> >>> for i in range(3): ... foo(i) >>> foo.assert_satisfied() >>> arg.called_with == [0, 1, 2] True
-
called_with
¶ List of ordered unique values that this matcher was called with.
-
mockify.times
- Classes for use with times method¶
Module containing set of classes to be used with
mockify.engine.Expectation.times()
method.
You can also create your own classes to be used with that method. The only thing required from such class is to implement following interface:
is_satisfied(self, actual)
Return
True
ifactual
call count is satisfied byself
, orFalse
otherwise.Here,
actual
is absolute call count expectation received so far. It is completely implementation-specific of which values ofactual
are said to be satisfied and which are not. For example,Exactly
will compareactual
with fixed value (given via constructor) and returnTrue
only if those two are equal.adjust_by(self, minimal)
Adjust
self
by currentminimal
expected call count and return new instance oftype(self)
.In some complex expectation there could be a situation in which expectation must be computed again. This is not visible for library user, but must be done behind the scenes to properly process expectations. Such situation can be presented in this example:
>>> from mockify.actions import Return >>> from mockify.mock.function import Function >>> foo = Function('foo') >>> foo.expect_call(1, 2).will_once(Return(1)).will_repeatedly(Return(2)).times(2) <mockify.Expectation: foo(1, 2)> >>> foo(1, 2) 1 >>> foo(1, 2) 2 >>> foo(1, 2) 2 >>> foo.assert_satisfied()In example above we’ve used
times(2)
to tell that last repeated action is expected to be called twice, but real expected call count is 3 times, aswill_once
is used. Behind the scenes, this is recalculated using this metho.format_expected(self)
Return textual representation of expected call count.
This is used by
mockify.exc.Unsatisfied
exception when error message is being rendered.minimal(sefl)
(property)Property containing minimal call count that is considered valid for given instance.
For example, for
AtLeast
orExactly
it would be just its constructor argument, for :class`AtMost` it will be 0, forBetween
it will be itsminimal
argument.
-
class
mockify.times.
AtLeast
(minimal)¶ Bases:
object
Used to set minimal expected call count.
If this is used, then expectation is said to be satisfied if actual call count is not less that
minimal
.Parameters: minimal – Integer value representing minimal expected call count
-
class
mockify.times.
AtMost
(maximal)¶ Bases:
object
Used to set maximal expected call count.
If this is used, then expectation is said to be satisfied if actual call count is not greater than
maximal
.Parameters: maximal – Integer value representing maximal expected call count
-
class
mockify.times.
Between
(minimal, maximal)¶ Bases:
object
Used to set a range of valid call counts.
If this is used, then expectation is said to be satisfied if actual call count is not less than
minimal
and not greater thanmaximal
.Parameters: - minimal – Integer value representing minimal expected call count
- maximal – Integer value representing maximal expected call count
-
class
mockify.times.
Exactly
(expected)¶ Bases:
object
Used to expect fixed call count to be made.
You do not have to use this class explicitly as its instances are automatically created when you call
times
method with integer value as argument.Parameters: expected – Integer value representing expected call count