0
# Testtools
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: testtools
7
- **Language**: Python
8
- **Installation**: `pip install testtools`
9
- **Requires**: Python 3.8+
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import testtools
16
```
17

18
Common imports for basic usage:
19

20
```python
21
from testtools import TestCase
22
from testtools.matchers import Equals, Contains, MatchesRegex
23
from testtools import skip, skipIf, skipUnless
24
```
25

26
Full matcher imports:
27

28
```python
29
from testtools.matchers import (
30
    # Basic matchers
31
    Equals, Contains, StartsWith, EndsWith, GreaterThan, LessThan,
32
    # Structure matchers  
33
    MatchesDict, MatchesListwise, MatchesStructure,
34
    # Exception matchers
35
    Raises, MatchesException,
36
    # Higher-order matchers
37
    MatchesAll, MatchesAny, Not, AllMatch, AnyMatch
38
)
39
```
40

41
## Basic Usage
42

43
```python
44
import testtools
45
from testtools.matchers import Equals, Contains, MatchesRegex
46

47
class MyTest(testtools.TestCase):
48
    def test_basic_assertions(self):
49
        # Enhanced assertions with matchers
50
        self.assertThat("Hello World", Contains("World"))
51
        self.assertThat(42, Equals(42))
52
        self.assertThat("test@example.com", MatchesRegex(r'\w+@\w+\.\w+'))
53
        
54
    def test_with_content_attachment(self):
55
        # Attach debugging content to test results
56
        self.addDetail('debug_info', testtools.content.text_content("Debug data"))
57
        self.assertEqual(1 + 1, 2)
58
        
59
    @testtools.skip("Not implemented yet")
60
    def test_skipped_example(self):
61
        pass
62
        
63
    @testtools.skipIf(True, "Conditional skip")
64
    def test_conditional_skip(self):
65
        pass
66

67
# Run tests with enhanced result handling
68
if __name__ == '__main__':
69
    import testtools
70
    suite = testtools.TestSuite()
71
    suite.addTest(MyTest('test_basic_assertions'))
72
    runner = testtools.TextTestResult(stream=sys.stdout, verbosity=2)
73
    suite.run(runner)
74
```
75

76
## Architecture
77

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

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

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

88
## Capabilities
89

90
### Enhanced Test Cases
91

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

94
```python { .api }
95
class TestCase(unittest.TestCase):
96
    def assertThat(self, matchee, matcher, message='', verbose=False): ...
97
    def addDetail(self, name, content_object): ...
98
    def expectThat(self, matchee, matcher): ...
99
    def getDetails(self): ...
100
```
101

102
[Enhanced Test Cases](./test-cases.md)
103

104
### Matchers System
105

106
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.
107

108
```python { .api }
109
# Basic matchers
110
def Equals(expected): ...
111
def Contains(contained): ...
112
def StartsWith(expected): ...
113
def MatchesRegex(pattern, flags=0): ...
114

115
# Structure matchers
116
def MatchesDict(d): ...
117
def MatchesListwise(matchers): ...
118
def MatchesStructure(**kwargs): ...
119

120
# Exception matchers  
121
def Raises(exception_matcher): ...
122
def MatchesException(exception, value_re=None): ...
123
```
124

125
[Matchers System](./matchers.md)
126

127
### Test Result Management
128

129
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.
130

131
```python { .api }
132
class TestResult(unittest.TestResult):
133
    def addError(self, test, err, details=None): ...
134
    def addFailure(self, test, err, details=None): ...
135
    def addSuccess(self, test, details=None): ...
136

137
class StreamResult:
138
    def startTestRun(self): ...
139
    def stopTestRun(self): ...
140
    def status(self, test_id=None, test_status=None, **kwargs): ...
141
```
142

143
[Test Result Management](./test-results.md)
144

145
### Test Execution Control
146

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

149
```python { .api }
150
class RunTest:
151
    def run(self, result): ...
152
    def setUp(self): ...
153
    def tearDown(self): ...
154

155
def skip(reason): ...
156
def skipIf(condition, reason): ...
157
def skipUnless(condition, reason): ...
158
```
159

160
[Test Execution Control](./test-execution.md)
161

162
### Content Attachments
163

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

166
```python { .api }
167
class Content:
168
    def __init__(self, content_type, get_bytes): ...
169
    def iter_bytes(self): ...
170
    def iter_text(self): ...
171

172
def text_content(text): ...
173
def json_content(json_data): ...
174
def content_from_file(path, content_type=None): ...
175
```
176

177
[Content Attachments](./content.md)
178

179
### Twisted Integration
180

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

183
```python { .api }
184
# Deferred matchers
185
def succeeded(): ...
186
def failed(): ...
187
def has_no_result(): ...
188

189
# Async test execution
190
class AsynchronousDeferredRunTest(RunTest): ...
191
class SynchronousDeferredRunTest(RunTest): ...
192
```
193

194
[Twisted Integration](./twisted-support.md)
195

196
### Helper Utilities
197

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

200
```python { .api }
201
def try_import(name, alternative=None, error_callback=None): ...
202
def clone_test_with_new_id(test, new_id): ...
203
def iterate_tests(test_suite_or_case): ...
204

205
class MonkeyPatcher:
206
    def add_patch(self, obj, attribute, new_value): ...
207
    def patch(self): ...
208
    def restore(self): ...
209
```
210

211
[Helper Utilities](./helpers.md)