Testtools: Unit Testing Extensions

2.9.0 · active · verified Sat Apr 11

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. It aims to provide the latest in unit testing technology in a way that will work with Python 3.10+ and PyPy3, with active development and regular releases.

Warnings

breaking testtools versions 2.5.0 and later removed the dependency on and explicit references to `unittest2`. If your project implicitly relied on `unittest2` being present or imported from it, this change will cause import errors or behavioral differences.
Fix: Migrate any `unittest2` imports or usage to the standard library's `unittest` module or the equivalent `testtools.TestCase` methods. Ensure your test runner is compatible with standard `unittest` modules.
breaking When running on Python 3.12.1, `testtools` versions older than 2.7.2 may encounter issues due to a breaking API change within Python itself. `testtools` 2.7.2 includes a fix for this incompatibility.
Fix: Upgrade `testtools` to version 2.7.2 or later to ensure compatibility with Python 3.12.1. If remaining on an older `testtools` version is necessary, avoid Python 3.12.1.
gotcha Recent versions of `testtools` (2.9.0 and later) require Python 3.10+. Attempting to install or run `testtools` on older Python environments will result in installation failures or runtime errors.
Fix: Ensure your Python environment is 3.10 or newer. For projects requiring older Python versions, consult the PyPI page for `testtools` to find a compatible older `testtools` release.
deprecated The `distutils` integration within `testtools` was deprecated in version 2.6.0. While `distutils` itself is deprecated in Python, projects that relied on this specific `testtools` integration may need to update their build or test setup scripts.
Fix: Transition to modern packaging tools like `setuptools` or `hatchling` (which `testtools` itself adopted in 2.8.0) and avoid direct reliance on `distutils` integration points provided by `testtools`.

Install

pip install testtools Install stable version
pip install testtools[twisted] Install with Twisted support

Imports

TestCase
```
from testtools import TestCase
```
text_content
```
from testtools.content import text_content
```
Content details classes are in `testtools.content`, not `testtools.details`.
run
```
from testtools.run import main as testtools_main
```
While `testtools.run` can be imported, it's typically used via its `main` function for direct execution, often aliased.

Quickstart

This quickstart demonstrates defining a test case using `testtools.TestCase`, adding custom details to test results for enhanced debugging, and explicitly skipping tests. It also shows how to invoke the `testtools` runner directly.

from testtools import TestCase
from testtools.content import text_content
from testtools.run import main as testtools_main

class MyTest(TestCase):
    def test_example_success(self):
        self.assertTrue(True, "This assertion should pass.")

    def test_example_failure_with_detail(self):
        # Add a custom detail to the test result for context on failure.
        self.addDetail('debug-log', text_content("Detailed log entry from test execution."))
        self.assertEqual(1, 2, "Expected 1 to equal 2, but it did not.")

    def test_example_skip(self):
        self.skipTest("This test is intentionally skipped as it's not relevant right now.")

if __name__ == '__main__':
    # Run tests using the testtools runner. 
    # In larger projects, consider 'testrepository' or 'python -m testtools.run'
    testtools_main()

view raw JSON →