{"id":3830,"library":"testtools","title":"Testtools: Unit Testing Extensions","description":"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.","status":"active","version":"2.9.0","language":"en","source_language":"en","source_url":"https://github.com/testing-cabal/testtools","tags":["testing","unit-testing","unittest-extensions","test-framework"],"install":[{"cmd":"pip install testtools","lang":"bash","label":"Install stable version"},{"cmd":"pip install testtools[twisted]","lang":"bash","label":"Install with Twisted support"}],"dependencies":[{"reason":"Optional dependency for Twisted framework integration.","package":"twisted","optional":true},{"reason":"Optional dependency for fixture support, an alternative to custom fixture objects.","package":"fixtures","optional":true}],"imports":[{"symbol":"TestCase","correct":"from testtools import TestCase"},{"note":"Content details classes are in `testtools.content`, not `testtools.details`.","wrong":"from testtools.details import text_content","symbol":"text_content","correct":"from testtools.content import text_content"},{"note":"While `testtools.run` can be imported, it's typically used via its `main` function for direct execution, often aliased.","wrong":"import testtools.run","symbol":"run","correct":"from testtools.run import main as testtools_main"}],"quickstart":{"code":"from testtools import TestCase\nfrom testtools.content import text_content\nfrom testtools.run import main as testtools_main\n\nclass MyTest(TestCase):\n    def test_example_success(self):\n        self.assertTrue(True, \"This assertion should pass.\")\n\n    def test_example_failure_with_detail(self):\n        # Add a custom detail to the test result for context on failure.\n        self.addDetail('debug-log', text_content(\"Detailed log entry from test execution.\"))\n        self.assertEqual(1, 2, \"Expected 1 to equal 2, but it did not.\")\n\n    def test_example_skip(self):\n        self.skipTest(\"This test is intentionally skipped as it's not relevant right now.\")\n\nif __name__ == '__main__':\n    # Run tests using the testtools runner. \n    # In larger projects, consider 'testrepository' or 'python -m testtools.run'\n    testtools_main()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.5.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<2.7.2 (when running on Python 3.12.1)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.9.0 (when running on Python < 3.10)"},{"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`.","message":"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.","severity":"deprecated","affected_versions":">=2.6.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}