0
# Core Test Runner
1

2
Main test runner classes that execute tests and orchestrate XML report generation. Provides both programmatic and command-line interfaces for running tests with XML output.
3

4
## Capabilities
5

6
### XMLTestRunner Class
7

8
Primary test runner that extends unittest's TextTestRunner to generate XML reports in JUnit format. Handles test execution, result collection, and XML report generation.
9

10
```python { .api }
11
class XMLTestRunner(TextTestRunner):
12
    def __init__(self, output='.', outsuffix=None, elapsed_times=True, 
13
                 encoding='UTF-8', resultclass=None, **kwargs):
14
        """
15
        Initialize XML test runner.
16
        
17
        Parameters:
18
        - output: str or file-like object, output directory or file stream
19
        - outsuffix: str or None, suffix for output files (default: timestamp)
20
        - elapsed_times: bool, include timing information in reports
21
        - encoding: str, XML encoding (default: 'UTF-8')
22
        - resultclass: class or None, custom result class
23
        - **kwargs: additional arguments passed to TextTestRunner
24
        """
25
    
26
    def run(self, test):
27
        """
28
        Run test case or test suite and generate XML reports.
29
        
30
        Parameters:
31
        - test: TestCase or TestSuite instance
32
        
33
        Returns:
34
        - TestResult: result object containing test outcomes
35
        """
36
```
37

38
#### Usage Examples
39

40
**Directory Output (Multiple Files)**
41
```python
42
import unittest
43
import xmlrunner
44

45
# Generate separate XML file for each test class
46
runner = xmlrunner.XMLTestRunner(
47
    output='test-reports',
48
    outsuffix='20231201',
49
    elapsed_times=True
50
)
51
unittest.main(testRunner=runner)
52
```
53

54
**Single File Output**
55
```python
56
import xmlrunner
57

58
# Generate single XML report file
59
with open('test-results.xml', 'wb') as output:
60
    runner = xmlrunner.XMLTestRunner(
61
        output=output,
62
        elapsed_times=True
63
    )
64
    unittest.main(testRunner=runner)
65
```
66

67
**In-Memory Output**
68
```python
69
import io
70
import xmlrunner
71

72
# Generate XML report in memory
73
output = io.BytesIO()
74
runner = xmlrunner.XMLTestRunner(output=output)
75
unittest.main(testRunner=runner, exit=False)
76

77
xml_content = output.getvalue()
78
print(xml_content.decode('utf-8'))
79
```
80

81
### XMLTestProgram Class
82

83
Command-line test program with XML reporting capabilities. Extends unittest's TestProgram to add XML-specific command-line options.
84

85
```python { .api }
86
class XMLTestProgram(TestProgram):
87
    def __init__(self, *args, **kwargs):
88
        """
89
        Initialize XML test program with command-line argument parsing.
90
        
91
        Command-line options:
92
        - -o DIR, --output DIR: directory for XML reports
93
        - --output-file FILENAME: single XML report file
94
        - --outsuffix STRING: custom output suffix
95
        
96
        Standard unittest options also supported.
97
        """
98
    
99
    def runTests(self):
100
        """Execute tests with XML reporting based on command-line arguments."""
101
```
102

103
#### Usage Examples
104

105
**Command-Line Usage**
106
```bash
107
# Run tests with XML output to directory
108
python -m xmlrunner discover -t tests -o /tmp/reports
109

110
# Run specific test module
111
python -m xmlrunner tests.test_module -o test-reports
112

113
# Generate single output file
114
python -m xmlrunner --output-file results.xml tests
115

116
# Custom suffix for multiple files
117
python -m xmlrunner --outsuffix build-123 tests
118
```
119

120
**Programmatic Usage**
121
```python
122
import sys
123
from xmlrunner.runner import XMLTestProgram
124

125
# Simulate command-line execution
126
sys.argv = ['xmlrunner', 'discover', '-t', 'tests', '-o', 'reports']
127
XMLTestProgram(module=None)
128
```
129

130
### Configuration Options
131

132
```python { .api }
133
# Output configuration
134
output: str | file_like = '.'  # Output directory or file stream
135
outsuffix: str | None = None   # File suffix (None = timestamp, '' = no suffix)
136
encoding: str = 'UTF-8'        # XML encoding
137

138
# Test execution options
139
elapsed_times: bool = True     # Include timing information
140
verbosity: int = 1            # Output verbosity level
141
failfast: bool = False        # Stop on first failure
142
buffer: bool = False          # Buffer stdout/stderr during tests
143

144
# Result customization
145
resultclass: type | None = None  # Custom result class
146
```
147

148
### Integration with unittest.main()
149

150
The XMLTestRunner can be used as a drop-in replacement for unittest's default TextTestRunner:
151

152
```python
153
import unittest
154
import xmlrunner
155

156
class MyTestCase(unittest.TestCase):
157
    def test_example(self):
158
        self.assertTrue(True)
159

160
if __name__ == '__main__':
161
    unittest.main(
162
        testRunner=xmlrunner.XMLTestRunner(output='reports'),
163
        failfast=False,
164
        buffer=False,
165
        catchbreak=False
166
    )
167
```
168

169
### Error Handling
170

171
The runner handles various error conditions gracefully:
172

173
- **Invalid output directory**: Creates directory if it doesn't exist
174
- **Permission errors**: Raises appropriate exceptions with clear messages  
175
- **Test execution errors**: Captures and reports in XML format
176
- **XML generation errors**: Falls back to text output with error logging