API

Stubs and mocks

doubles.allow(target)

Prepares a target object for a method call allowance (stub). The name of the method to allow should be called as a method on the return value of this function:

allow(foo).bar

Accessing the bar attribute will return an Allowance which provides additional methods to configure the stub.

Parameters

target (object) – The object that will be stubbed.

Returns

An AllowanceTarget for the target object.

doubles.expect(target)

Prepares a target object for a method call expectation (mock). The name of the method to expect should be called as a method on the return value of this function:

expect(foo).bar

Accessing the bar attribute will return an Expectation which provides additional methods to configure the mock.

Parameters

target (object) – The object that will be mocked.

Returns

An ExpectationTarget for the target object.

doubles.allow_constructor(target)

Set an allowance on a ClassDouble constructor

This allows the caller to control what a ClassDouble returns when a new instance is created.

Parameters

target (ClassDouble) – The ClassDouble to set the allowance on.

Returns

an Allowance for the __new__ method.

Raise

ConstructorDoubleError if target is not a ClassDouble.

doubles.expect_constructor(target)

Set an expectation on a ClassDouble constructor

Parameters

target (ClassDouble) – The ClassDouble to set the expectation on.

Returns

an Expectation for the __new__ method.

Raise

ConstructorDoubleError if target is not a ClassDouble.

doubles.patch(target, value)

Replace the specified object

Parameters

• target (str) – A string pointing to the target to patch.

• value (object) – The value to replace the target with.

Returns

A Patch object.

doubles.patch_class(target)

Replace the specified class with a ClassDouble

Parameters

• target (str) – A string pointing to the target to patch.

• values (obj) – Values to return when new instances are created.

Returns

A ClassDouble object.

class doubles.allowance.Allowance(target, method_name, caller)

An individual method allowance (stub).

and_raise(exception)

Causes the double to raise the provided exception when called.

Parameters

exception (Exception) – The exception to raise.

and_return(*return_values)

Causes the double to return the provided values in order. If multiple values are provided, they are returned one at a time in sequence as the double is called. If the double is called more times than there are return values, it should continue to return the last value in the list.

Parameters

return_values (object) – The values the double will return when called,

and_return_result_of(return_value)

Causes the double to return the result of calling the provided value.

Parameters

return_value (any callable object) – A callable that will be invoked to determine the double’s return value.

with_args(*args, **kwargs)

Declares that the double can only be called with the provided arguments.

Parameters

• args – Any positional arguments required for invocation.

• kwargs – Any keyword arguments required for invocation.

with_no_args()

Declares that the double can only be called with no arguments.

class doubles.expectation.Expectation(target, method_name, caller)

An individual method expectation (mock).

with_args(*args, **kwargs)

Declares that the double can only be called with the provided arguments.

Parameters

• args – Any positional arguments required for invocation.

• kwargs – Any keyword arguments required for invocation.

with_no_args()

Declares that the double can only be called with no arguments.

Pure doubles

class doubles.InstanceDouble(path, **kwargs)

A pure double representing an instance of the target class.

Any kwargs supplied will be set as attributes on the instance that is created.

user = InstanceDouble('myapp.User', name='Bob Barker')

Parameters

path (str) – The absolute module path to the class.

class doubles.ClassDouble(path)

A pure double representing the target class.

User = ClassDouble('myapp.User')

Parameters

path (str) – The absolute module path to the class.

class doubles.ObjectDouble(target)

A pure double representing the target object.

dummy_user = ObjectDouble(user)

Parameters

target (object) – The object the newly created ObjectDouble will verify against.

Test lifecycle

doubles.verify()

Verifies any mocks that have been created during the test run. Must be called after each test case, but before teardown.

doubles.teardown()

Tears down the current Doubles environment. Must be called after each test case.

Exceptions

exception doubles.exceptions.ConstructorDoubleError

An exception raised when attempting to double the constructor of a non ClassDouble.

exception doubles.exceptions.MockExpectationError

An exception raised when a mock fails verification.

exception doubles.exceptions.UnallowedMethodCallError

An exception raised when an unallowed method call is made on a double.

exception doubles.exceptions.UnsupportedMethodError

An exception raised when a return/raise call is made on an expectation.

exception doubles.exceptions.VerifyingBuiltinDoubleArgumentError

An exception raised when attempting to validate arguments of a builtin.

exception doubles.exceptions.VerifyingDoubleArgumentError

An exception raised when attempting to double a method with arguments that do not match the signature of the real method.

exception doubles.exceptions.VerifyingDoubleError(method_name, doubled_obj)

An exception raised when attempting to double a method that does not exist on the real object.

exception doubles.exceptions.VerifyingDoubleImportError

An exception raised when attempting to create a verifying double from an invalid module path.