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, *args, **kwargs)

Causes the double to raise the provided exception when called.

If provided, additional arguments (positional and keyword) passed to and_raise are used in the exception instantiation.

Parameters:exception (Exception) – The exception to raise.
and_return(*return_values)

Set a return value for an allowance

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()

Verify a mock

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.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.