or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

content.mdhelpers.mdindex.mdmatchers.mdtest-cases.mdtest-execution.mdtest-results.mdtwisted-support.md
tile.json

tessl/pypi-testtools

Extensions to the Python standard library unit testing framework

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/testtools@2.7.x

To install, run

npx @tessl/cli install tessl/pypi-testtools@2.7.0

index.mddocs/

Testtools

Extensions to the Python standard library unit testing framework, providing enhanced testing capabilities including advanced assertion methods, test result management, sophisticated matchers, and integration with testing tools like Twisted. Testtools offers a comprehensive foundation for building robust test suites in Python applications with support for complex testing scenarios and asynchronous code.

Package Information

  • Package Name: testtools
  • Language: Python
  • Installation: pip install testtools
  • Requires: Python 3.8+
  • License: MIT

Core Imports

import testtools

Common imports for basic usage:

from testtools import TestCase
from testtools.matchers import Equals, Contains, MatchesRegex
from testtools import skip, skipIf, skipUnless

Full matcher imports:

from testtools.matchers import (
    # Basic matchers
    Equals, Contains, StartsWith, EndsWith, GreaterThan, LessThan,
    # Structure matchers  
    MatchesDict, MatchesListwise, MatchesStructure,
    # Exception matchers
    Raises, MatchesException,
    # Higher-order matchers
    MatchesAll, MatchesAny, Not, AllMatch, AnyMatch
)

Basic Usage

import testtools
from testtools.matchers import Equals, Contains, MatchesRegex

class MyTest(testtools.TestCase):
    def test_basic_assertions(self):
        # Enhanced assertions with matchers
        self.assertThat("Hello World", Contains("World"))
        self.assertThat(42, Equals(42))
        self.assertThat("test@example.com", MatchesRegex(r'\w+@\w+\.\w+'))
        
    def test_with_content_attachment(self):
        # Attach debugging content to test results
        self.addDetail('debug_info', testtools.content.text_content("Debug data"))
        self.assertEqual(1 + 1, 2)
        
    @testtools.skip("Not implemented yet")
    def test_skipped_example(self):
        pass
        
    @testtools.skipIf(True, "Conditional skip")
    def test_conditional_skip(self):
        pass

# Run tests with enhanced result handling
if __name__ == '__main__':
    import testtools
    suite = testtools.TestSuite()
    suite.addTest(MyTest('test_basic_assertions'))
    runner = testtools.TextTestResult(stream=sys.stdout, verbosity=2)
    suite.run(runner)

Architecture

Testtools extends Python's unittest framework through several key components:

  • Enhanced TestCase: Extends unittest.TestCase with additional assertion methods, better error reporting, and content attachment capabilities
  • Matchers System: Sophisticated assertion library with 46 matchers for complex comparisons and validations
  • Stream Results: Modern, real-time test result reporting system supporting parallel test execution
  • Content Attachments: Attach arbitrary data (files, logs, screenshots) to test results for debugging
  • Test Result Management: Multiple result formats, decorators, and processing pipelines for flexible result handling

This architecture provides maximum compatibility with existing unittest code while adding powerful extensions for advanced testing scenarios.

Capabilities

Enhanced Test Cases

Core TestCase enhancements including additional assertion methods, content attachments, fixture support, and improved error reporting that extends unittest.TestCase functionality.

class TestCase(unittest.TestCase):
    def assertThat(self, matchee, matcher, message='', verbose=False): ...
    def addDetail(self, name, content_object): ...
    def expectThat(self, matchee, matcher): ...
    def getDetails(self): ...

Enhanced Test Cases

Matchers System

Sophisticated assertion system with 46 matchers for complex comparisons, including basic value matchers, data structure matchers, exception matchers, filesystem matchers, and higher-order matcher combinators.

# Basic matchers
def Equals(expected): ...
def Contains(contained): ...
def StartsWith(expected): ...
def MatchesRegex(pattern, flags=0): ...

# Structure matchers
def MatchesDict(d): ...
def MatchesListwise(matchers): ...
def MatchesStructure(**kwargs): ...

# Exception matchers  
def Raises(exception_matcher): ...
def MatchesException(exception, value_re=None): ...

Matchers System

Test Result Management

Comprehensive test result handling including extended result APIs, stream results for real-time reporting, result decorators, and multi-format output support for flexible test result processing.

class TestResult(unittest.TestResult):
    def addError(self, test, err, details=None): ...
    def addFailure(self, test, err, details=None): ...
    def addSuccess(self, test, details=None): ...

class StreamResult:
    def startTestRun(self): ...
    def stopTestRun(self): ...
    def status(self, test_id=None, test_status=None, **kwargs): ...

Test Result Management

Test Execution Control

Control how individual tests run including custom test execution, skip decorators, concurrent test execution, and specialized test suite implementations.

class RunTest:
    def run(self, result): ...
    def setUp(self): ...
    def tearDown(self): ...

def skip(reason): ...
def skipIf(condition, reason): ...
def skipUnless(condition, reason): ...

Test Execution Control

Content Attachments

Attach arbitrary content (files, logs, screenshots, debug data) to test results for enhanced debugging and result reporting capabilities.

class Content:
    def __init__(self, content_type, get_bytes): ...
    def iter_bytes(self): ...
    def iter_text(self): ...

def text_content(text): ...
def json_content(json_data): ...
def content_from_file(path, content_type=None): ...

Content Attachments

Twisted Integration

Complete integration with Twisted framework for testing asynchronous code using Deferreds, including specialized matchers and test execution classes.

# Deferred matchers
def succeeded(): ...
def failed(): ...
def has_no_result(): ...

# Async test execution
class AsynchronousDeferredRunTest(RunTest): ...
class SynchronousDeferredRunTest(RunTest): ...

Twisted Integration

Helper Utilities

Utility functions for common testing tasks including safe imports, dictionary manipulation, monkey patching, and test organization helpers.

def try_import(name, alternative=None, error_callback=None): ...
def clone_test_with_new_id(test, new_id): ...
def iterate_tests(test_suite_or_case): ...

class MonkeyPatcher:
    def add_patch(self, obj, attribute, new_value): ...
    def patch(self): ...
    def restore(self): ...

Helper Utilities