0
# unittest-xml-reporting
1
2
A unittest-based test runner that extends Python's built-in unittest framework to generate XML test reports in xUnit format. Compatible with build systems, IDEs, and continuous integration servers like Jenkins, this library provides comprehensive test result reporting while maintaining complete compatibility with standard unittest.TestCase workflows.
3
4
## Package Information
5
6
- **Package Name**: unittest-xml-reporting
7
- **Language**: Python
8
- **Installation**: `pip install unittest-xml-reporting`
9
- **Dependencies**: None (core functionality), lxml (for extra features)
10
- **Python Version**: 3.7+
11
12
## Core Imports
13
14
```python
15
import xmlrunner
16
```
17
18
Main components:
19
```python
20
from xmlrunner import XMLTestRunner
21
```
22
23
For XML building utilities:
24
```python
25
from xmlrunner.builder import TestXMLBuilder, TestXMLContext
26
```
27
28
For command-line test program:
29
```python
30
from xmlrunner.runner import XMLTestProgram
31
```
32
33
## Basic Usage
34
35
```python
36
import unittest
37
import xmlrunner
38
39
class TestExample(unittest.TestCase):
40
def test_addition(self):
41
self.assertEqual(2 + 2, 4)
42
43
def test_subtraction(self):
44
self.assertEqual(5 - 3, 2)
45
46
if __name__ == '__main__':
47
# Generate XML reports in test-reports directory
48
unittest.main(
49
testRunner=xmlrunner.XMLTestRunner(output='test-reports'),
50
failfast=False, buffer=False, catchbreak=False
51
)
52
```
53
54
## Architecture
55
56
unittest-xml-reporting follows a layered architecture:
57
58
- **XMLTestRunner**: Main test runner that orchestrates test execution and report generation
59
- **_XMLTestResult**: Captures test results and generates XML reports using the JUnit format
60
- **TestXMLBuilder/TestXMLContext**: Low-level XML document construction utilities
61
- **Django Integration**: Specialized test runner for Django projects
62
- **Jenkins Compatibility**: Transform utilities for various CI/CD systems
63
64
The library maintains full compatibility with Python's unittest framework while adding XML reporting capabilities, making it a drop-in replacement for TextTestRunner in CI/CD environments.
65
66
## Capabilities
67
68
### XML Test Runner
69
70
Main test runner class that executes tests and generates XML reports in JUnit format. Supports both directory-based and single-file output with configurable report formatting.
71
72
```python { .api }
73
class XMLTestRunner:
74
def __init__(self, output='.', outsuffix=None, elapsed_times=True,
75
encoding='UTF-8', resultclass=None, **kwargs): ...
76
def run(self, test): ...
77
```
78
79
[Core Test Runner](./core-runner.md)
80
81
### Result Collection and XML Generation
82
83
Comprehensive test result collection system that captures test outcomes, timing information, stdout/stderr, and generates properly formatted XML reports compatible with CI/CD systems.
84
85
```python { .api }
86
class _XMLTestResult:
87
def __init__(self, stream=sys.stderr, descriptions=1, verbosity=1,
88
elapsed_times=True, properties=None, infoclass=None): ...
89
def generate_reports(self, test_runner): ...
90
```
91
92
[Result Collection](./result-collection.md)
93
94
### XML Document Construction
95
96
Low-level utilities for building XML test reports with proper JUnit schema compliance, including context management, counter tracking, and CDATA section handling.
97
98
```python { .api }
99
class TestXMLBuilder:
100
def __init__(self): ...
101
def begin_context(self, tag, name): ...
102
def append(self, tag, content, **kwargs): ...
103
def finish(self): ...
104
```
105
106
[XML Utilities](./xml-utilities.md)
107
108
### Django Framework Integration
109
110
Specialized test runner for Django projects that integrates unittest-xml-reporting with Django's testing framework, supporting Django-specific configuration options.
111
112
```python { .api }
113
class XMLTestRunner(DiscoverRunner):
114
def get_test_runner_kwargs(self): ...
115
def run_suite(self, suite, **kwargs): ...
116
```
117
118
[Django Integration](./django-integration.md)
119
120
### Command-Line Interface
121
122
Direct command-line execution for running tests with XML reporting. Supports test discovery, module execution, and configurable output options.
123
124
```python { .api }
125
class XMLTestProgram(TestProgram):
126
def __init__(self, *args, **kwargs): ...
127
def runTests(self): ...
128
```
129
130
Command-line usage:
131
```bash
132
python -m xmlrunner [discover] [options] [test_modules...]
133
```
134
135
### Jenkins Compatibility Tools
136
137
Transformation utilities for ensuring XML report compatibility with various versions of Jenkins xUnit plugins, including schema validation and attribute filtering.
138
139
```python { .api }
140
def transform(xml_data): ...
141
```
142
143
[Jenkins Compatibility](./jenkins-compatibility.md)
144
145
## Types
146
147
```python { .api }
148
# Constants
149
UTF8: str = 'UTF-8' # Default encoding for XML output
150
151
# Test outcome constants (from _TestInfo)
152
SUCCESS: int = 0
153
FAILURE: int = 1
154
ERROR: int = 2
155
SKIP: int = 3
156
157
# Test information container
158
class _TestInfo:
159
def __init__(self, test_result, test_method, outcome=SUCCESS,
160
err=None, subTest=None, filename=None, lineno=None, doc=None): ...
161
162
test_result: _XMLTestResult
163
outcome: int
164
elapsed_time: float
165
timestamp: str
166
test_name: str
167
test_id: str
168
test_description: str
169
test_exception_name: str
170
test_exception_message: str
171
test_exception_info: str
172
stdout: str
173
stderr: str
174
filename: str | None
175
lineno: int | None
176
doc: str | None
177
178
# XML context for report generation
179
class TestXMLContext:
180
def __init__(self, xml_doc, parent_context=None): ...
181
182
xml_doc: Document
183
parent: TestXMLContext | None
184
counters: dict[str, int]
185
element: Element
186
_allowed_counters: tuple[str, ...] = ('tests', 'errors', 'failures', 'skipped')
187
```