Double classes

class Stub([collaborator])
class Spy([collaborator])
class ProxySpy([collaborator])
class Mock([collaborator])
class Mimic(double, collaborator)



Stub method will raise the given exception when invoked. Method parameters are relevant, and they may be literal values or hamcrest matchers:

with Stub() as stub:

See Stubs raising exceptions.


Stub method will return the given value when invoked:

with Stub() as stub:

See Stub.


Stub method will return input parameters when invoked:

with Stub() as stub:

See Stubs returning input.


Stub method will return values generated by the delegate, that may be a function, generator or iterable object:

with Stub() as stub:
    stub.method().delegates([1, 2, 4, 8])

See Stub delegates.


Stub methods are observable. You may attach arbitrary callable that will be invoked any time the stub method does:

counter = itertools.count()

See Stub observers.


class never(matcher)

Just a cosmetic alias to the hamcrest matcher is_not(). See never().

for Spy methods

class called

Asserts a spy method was called:

assert_that(spy.method, called())

See called().


The called assertion waits the corresponding invocation a maximum of timeout seconds.

Parameters:timeout (int) – how many second wait before assume assertion fails.
assert_that(spy.method, called().async(1))

See Asynchronous spies.


The spy method must be invoked value times to consider the assertion right. The value parameter may an integer or hamcrest matcher as well.

Parameters:value (int or hamcrest Matcher) – how many times the method should be called.
assert_that(spy.method, called().times(less_that(3)))

See times(): asserting number of calls.

called.with_args(*args, **kargs)

The spy method must be invoked with the given positional or/and named parameters. All of them may be literal values and hamcrest matchers.

assert_that(spy.method, called().with_args("mary", greater_that(4)))

See with_args(): asserting calling argument values.


The spy method must be invoked with AT LEAST the given parameter values. It supports literal values and hamcrest matchers.

assert_that(spy.method, called().with_some_args(name="mary"))

See with_some_args(): asserting just relevant arguments.

for properties

class property_got
class property_set

See Properties.

for mocks

class verify

Checks the given mock meets the given expectations.

assert_that(mock, verify())

See Mock.

class any_order_verify

Checks the given mock meets the given expectations even when the invocation sequence has a different order to the expectations.

assert_that(mock, any_order_verify())

See Mock.

Module level functions

assert_that(item, matcher)

A convenient replace for the hamcrest assert_that method. See assert_that().

wait_that(item, matcher, reason='', delta=1, timeout=5)

It test the matcher over item until it matches or fails after timemout seconds, polling the matcher each delta seconds.


Creates an independent Stub method that returns the given value. It may be added to any object:

some.method = method_returning(20)

See Ad-hoc stub methods.


Creates an independent Stub method that raises the given exception. It may be added to any object:

some.method = method_raising(ValueError)

See Ad-hoc stub methods.


Set the default behavior for undefined Stub methods. The built-in behavior is to return None. See Changing default stub behavior.