Skip to main content

testtools: tasteful testing for Python

testtools is a set of extensions to the Python standard library’s unit testing framework. These extensions have been derived from many years of experience with unit testing in Python and come from many different sources.

What better way to start than with a contrived code snippet?:

from testtools import TestCase
from testtools.content import Content
from testtools.content_type import UTF8_TEXT
from testtools.matchers import Equals

from myproject import SillySquareServer

class TestSillySquareServer(TestCase):

    def setUp(self):
        super(TestSillySquareServer, self).setUp()
        self.server = self.useFixture(SillySquareServer())
        self.addCleanup(self.attach_log_file)

    def attach_log_file(self):
        self.addDetail(
            'log-file',
            Content(UTF8_TEXT,
                    lambda: open(self.server.logfile, 'r').readlines()))

    def test_server_is_cool(self):
        self.assertThat(self.server.temperature, Equals("cool"))

    def test_square(self):
        self.assertThat(self.server.silly_square_of(7), Equals(49))

Why use testtools?

Matchers: better than assertion methods

Of course, in any serious project you want to be able to have assertions that are specific to that project and the particular problem that it is addressing. Rather than forcing you to define your own assertion methods and maintain your own inheritance hierarchy of TestCase classes, testtools lets you write your own “matchers”, custom predicates that can be plugged into a unit test:

def test_response_has_bold(self):
   # The response has bold text.
   response = self.server.getResponse()
   self.assertThat(response, HTMLContains(Tag('bold', 'b')))

More debugging info, when you need it

testtools makes it easy to add arbitrary data to your test result. If you want to know what’s in a log file when a test fails, or what the load was on the computer when a test started, or what files were open, you can add that information with TestCase.addDetail, and it will appear in the test results if that test fails.

Extend unittest, but stay compatible and re-usable

testtools goes to great lengths to allow serious test authors and test framework authors to do whatever they like with their tests and their extensions while staying compatible with the standard library’s unittest.

testtools has completely parametrized how exceptions raised in tests are mapped to TestResult methods and how tests are actually executed (ever wanted tearDown to be called regardless of whether setUp succeeds?)

It also provides many simple but handy utilities, like the ability to clone a test, a MultiTestResult object that lets many result objects get the results from one test suite, adapters to bring legacy TestResult objects into our new golden age.

Cross-Python compatibility

testtools gives you the very latest in unit testing technology in a way that will work with Python 3.10+ and PyPy3.

If you wish to use testtools with Python 2.4 or 2.5, then please use testtools 0.9.15.

If you wish to use testtools with Python 2.6 or 3.2, then please use testtools 1.9.0.

If you wish to use testtools with Python 3.3 or 3.4, then please use testtools 2.3.0.

If you wish to use testtools with Python 2.7 or 3.5, then please use testtools 2.4.0.

Metadata

Release files for testtools 2.9.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for testtools 2.9.2
File Size Uploaded Provenance Actions
testtools-2.9.2.tar.gz 227.5 kB With provenance Details for testtools-2.9.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for testtools 2.9.2
File Interpreter ABI Platform Actions
testtools-2.9.2-py3-none-any.whl Python 3 none any Details for testtools-2.9.2-py3-none-any.whl

Total release size: 340.0 kB

Release files / testtools-2.9.2.tar.gz

Download URL testtools-2.9.2.tar.gz
Size 227.5 kB
Tags Source
SHA-256 checksum
How to use checksums
64f35fc503ac0e51310e0be9f4336533d26e375f343fda39da72c62d4b9ddb6e
BLAKE2b-256 checksum
How to use checksums
32d3d9b2558fd75080261c1389372c4d61987cf201d701d06481cba0b7a0caf9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / testtools-2.9.2-py3-none-any.whl

Download URL testtools-2.9.2-py3-none-any.whl
Size 112.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e041e621b4dc0a280ccdd1cc8330afa2e2a4a6f7d88bbf0489149ff4efd40fd2
BLAKE2b-256 checksum
How to use checksums
ba9466932c1b4eb67d4ffd0da48e378c028a966fe390305cffe4c5a710d9e0ed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for testtools 2.9.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for testtools-2.9.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.9.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page