What is pyDoubles?

pyDoubles is a test doubles framework for the Python platform. Test doubles frameworks are also called mocking frameworks. pyDoubles can be used as a testing tool or as a Test Driven Development tool.

It generates stubs, spies, and mock objects using a fluent interface that will make your unit tests more readable. Moreover, it’s been designed to make your tests less fragile when possible.

The development of pyDoubles has been completely test-driven from scratch. The project is under continuous evolution, but you can extend the framework with your own requirements. The code is simple and well documented with unit tests.

Supported test doubles

Find out what test doubles are according to Gerard Meszaros. pyDoubles offers mainly three kind of doubles:


Replaces the implementation of one or more methods in the object instance which plays the role of collaborator or dependency, returning the value that we explicitly write down in the test. A stub is actually a method but it is also common to use the noun stub for a class with stubbed methods. The stub does not have any kind or memory.

Stubs are used mainly for state validation or along with spies or mocks.


Replaces the implementation as a stub does, but it is also able to register and remember what methods are called during the test execution and how they are invoked.

They are used for interaction/behavior verification.


Contains the same features than the Stub and therefore the Spy, but it is very strict in the behavior specification it should expect from the System Under Tests. Before calling any method in the mock object, the framework should be told (in the test) which methods we expect to be called in order for them to succeed. Otherwise, the test will fail with an “UnexpectedBehavior” exception.

Mock objects are used when we have to be very precise in the behavior specification. They usually make the tests more fragile than a spy but still are necessary in many cases. It is common to use mock objects together with stubs in tests.

New to test doubles?

A unit test is comprised of three parts: Arrange/Act/Assert or Given/When/Then or whatever you want to call them. The scenario has to be created, exercised, and eventually we verify that the expected behavior happened. The test doubles framework is used to create the scenario (create the objects), and verify behavior after the execution but it does not make sense to invoke test doubles’ methods in the test code. If you call the doubles’ methods in the test code, you are testing the framework itself, which has been already tested (better than that, we crafted it using TDD). Make sure the calls to the doubles’ methods happen in your production code.

Why another framework?

pyDoubles is inspired in mockito and jMock for Java, and also inspired in Rhino.Mocks for .Net. There are other frameworks for Python that work really well, but after some time using them, we were not really happy with the syntax and the readability of the tests. Fragile tests were also a problem. Some well-known frameworks available for Python are: mocker, mockito-python, mock, pymox.

pyDoubles is open source and free software, released under the Apache License Version 2.0

Take a look at the project’s blog

Read the Docs v: latest
On Read the Docs
Project Home

Free document hosting provided by Read the Docs.