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
```