0
# Django Framework Integration
1

2
Specialized test runner for Django projects that integrates unittest-xml-reporting with Django's testing framework. Provides Django-specific configuration options and seamless integration with Django's test discovery and execution system.
3

4
## Capabilities
5

6
### Django XMLTestRunner Class
7

8
Django test runner that extends Django's DiscoverRunner to use XMLTestRunner for XML report generation.
9

10
```python { .api }
11
class XMLTestRunner(DiscoverRunner):
12
    test_runner = xmlrunner.XMLTestRunner
13
    
14
    def get_resultclass(self):
15
        """
16
        Override Django's default result class behavior.
17
        
18
        Returns:
19
        - None: suppresses Django's DebugSQLTextTestResult to use XMLTestResult
20
        """
21
    
22
    def get_test_runner_kwargs(self):
23
        """
24
        Get keyword arguments for XMLTestRunner based on Django settings.
25
        
26
        Returns:
27
        - dict: configuration dictionary for XMLTestRunner
28
        """
29
    
30
    def run_suite(self, suite, **kwargs):
31
        """
32
        Execute test suite using XMLTestRunner.
33
        
34
        Parameters:
35
        - suite: TestSuite instance
36
        - **kwargs: additional run arguments
37
        
38
        Returns:
39
        - TestResult: result object with test outcomes
40
        """
41
```
42

43
## Configuration
44

45
### Django Settings
46

47
Configure the Django test runner and its behavior through Django settings:
48

49
```python
50
# settings.py
51

52
# Enable XML test runner
53
TEST_RUNNER = 'xmlrunner.extra.djangotestrunner.XMLTestRunner'
54

55
# XML reporting configuration
56
TEST_OUTPUT_VERBOSE = 1              # Verbosity level (0|1|2)
57
TEST_OUTPUT_DESCRIPTIONS = False     # Show docstrings instead of method names
58
TEST_OUTPUT_DIR = '.'                # Output directory for XML reports
59
TEST_OUTPUT_FILE_NAME = None         # Single output file name (None = multiple files)
60
```
61

62
#### Setting Details
63

64
```python { .api }
65
# Verbosity levels
66
TEST_OUTPUT_VERBOSE: int = 1
67
# 0: Minimal output
68
# 1: Standard output with test results
69
# 2: Verbose output with test descriptions
70

71
# Description display
72
TEST_OUTPUT_DESCRIPTIONS: bool = False
73
# False: Show test method names (test_method_name)
74
# True: Show test docstrings when verbosity = 2
75

76
# Output configuration
77
TEST_OUTPUT_DIR: str = '.'
78
# Directory path for XML report files
79
# Created if it doesn't exist
80

81
TEST_OUTPUT_FILE_NAME: str | None = None
82
# None: Generate separate file per test class
83
# str: Generate single XML file with specified name
84
```
85

86
## Usage Examples
87

88
### Basic Django Integration
89

90
```python
91
# settings.py
92
TEST_RUNNER = 'xmlrunner.extra.djangotestrunner.XMLTestRunner'
93
TEST_OUTPUT_DIR = 'test-reports'
94
TEST_OUTPUT_VERBOSE = 2
95
TEST_OUTPUT_DESCRIPTIONS = True
96

97
# Run Django tests
98
python manage.py test
99
```
100

101
### Custom Django Test Configuration
102

103
```python
104
# settings.py
105
import os
106

107
# Different configurations for different environments
108
if os.getenv('CI'):
109
    # CI environment - single file output
110
    TEST_RUNNER = 'xmlrunner.extra.djangotestrunner.XMLTestRunner'
111
    TEST_OUTPUT_DIR = '/tmp/test-reports'
112
    TEST_OUTPUT_FILE_NAME = 'django-tests.xml'
113
    TEST_OUTPUT_VERBOSE = 1
114
else:
115
    # Development environment - multiple files
116
    TEST_RUNNER = 'xmlrunner.extra.djangotestrunner.XMLTestRunner'
117
    TEST_OUTPUT_DIR = 'test-reports'
118
    TEST_OUTPUT_VERBOSE = 2
119
    TEST_OUTPUT_DESCRIPTIONS = True
120
```
121

122
### Command-Line Usage
123

124
```bash
125
# Run all tests with XML reporting
126
python manage.py test
127

128
# Run specific app tests
129
python manage.py test myapp
130

131
# Run with custom verbosity
132
python manage.py test --verbosity=2
133

134
# Run specific test class
135
python manage.py test myapp.tests.TestMyModel
136

137
# Run with custom settings
138
python manage.py test --settings=myproject.test_settings
139
```
140

141
### Integration with Django Test Classes
142

143
```python
144
# tests.py
145
from django.test import TestCase
146
from django.contrib.auth.models import User
147

148
class UserModelTest(TestCase):
149
    """Test user model functionality."""
150
    
151
    def setUp(self):
152
        """Set up test data."""
153
        self.user = User.objects.create_user(
154
            username='testuser',
155
            email='test@example.com',
156
            password='testpass123'
157
        )
158
    
159
    def test_user_creation(self):
160
        """Test user is created correctly."""
161
        self.assertEqual(self.user.username, 'testuser')
162
        self.assertEqual(self.user.email, 'test@example.com')
163
        self.assertTrue(self.user.check_password('testpass123'))
164
    
165
    def test_user_str_representation(self):
166
        """Test user string representation."""
167
        self.assertEqual(str(self.user), 'testuser')
168

169
# XML report will include Django-specific test information
170
```
171

172
### Database Configuration for Testing
173

174
```python
175
# test_settings.py
176
from .settings import *
177

178
# Use in-memory SQLite for faster tests
179
DATABASES = {
180
    'default': {
181
        'ENGINE': 'django.db.backends.sqlite3',
182
        'NAME': ':memory:',
183
    }
184
}
185

186
# XML test runner configuration
187
TEST_RUNNER = 'xmlrunner.extra.djangotestrunner.XMLTestRunner'
188
TEST_OUTPUT_DIR = 'test-reports'
189
TEST_OUTPUT_FILE_NAME = 'django-tests.xml'
190

191
# Run tests with: python manage.py test --settings=myproject.test_settings
192
```
193

194
### Custom Django Test Runner Extension
195

196
```python
197
# custom_test_runner.py
198
from xmlrunner.extra.djangotestrunner import XMLTestRunner as BaseXMLTestRunner
199

200
class CustomXMLTestRunner(BaseXMLTestRunner):
201
    def get_test_runner_kwargs(self):
202
        """Customize test runner arguments."""
203
        kwargs = super().get_test_runner_kwargs()
204
        
205
        # Add custom properties to XML reports
206
        kwargs.update({
207
            'properties': {
208
                'django_version': django.VERSION,
209
                'database_engine': settings.DATABASES['default']['ENGINE'],
210
                'test_environment': 'custom',
211
            }
212
        })
213
        
214
        return kwargs
215
    
216
    def run_suite(self, suite, **kwargs):
217
        """Add custom pre/post test logic."""
218
        print("Starting Django XML test run...")
219
        result = super().run_suite(suite, **kwargs)
220
        print(f"Tests completed: {result.testsRun}")
221
        return result
222

223
# settings.py
224
TEST_RUNNER = 'myproject.custom_test_runner.CustomXMLTestRunner'
225
```
226

227
### Integration with CI/CD Systems
228

229
```python
230
# ci_settings.py
231
import os
232
from .settings import *
233

234
# CI-specific configuration
235
TEST_RUNNER = 'xmlrunner.extra.djangotestrunner.XMLTestRunner'
236

237
# Use environment variables for flexibility
238
TEST_OUTPUT_DIR = os.getenv('TEST_OUTPUT_DIR', 'test-reports')
239
TEST_OUTPUT_FILE_NAME = os.getenv('TEST_OUTPUT_FILE', 'django-tests.xml')
240
TEST_OUTPUT_VERBOSE = int(os.getenv('TEST_VERBOSITY', '1'))
241

242
# Example CI script usage:
243
# export TEST_OUTPUT_DIR=/tmp/test-reports
244
# export TEST_OUTPUT_FILE=django-junit.xml
245
# python manage.py test --settings=myproject.ci_settings
246
```
247

248
### Compatibility Notes
249

250
The Django integration:
251

252
- Works with all Django test types (TestCase, TransactionTestCase, etc.)
253
- Supports Django's test database setup and teardown
254
- Compatible with Django's test discovery mechanism
255
- Preserves Django's fixture loading and management
256
- Maintains Django's test isolation guarantees
257
- Supports Django's test decorators (@override_settings, etc.)
258

259
### Output Structure
260

261
Django XML reports include Django-specific information:
262

263
```xml
264
<?xml version="1.0" encoding="UTF-8"?>
265
<testsuites>
266
  <testsuite name="myapp.tests.UserModelTest" tests="2" failures="0" errors="0" 
267
             time="0.123" timestamp="2023-12-01T10:30:00">
268
    <testcase classname="myapp.tests.UserModelTest" name="test_user_creation" 
269
              time="0.045" timestamp="2023-12-01T10:30:00"/>
270
    <testcase classname="myapp.tests.UserModelTest" name="test_user_str_representation" 
271
              time="0.012" timestamp="2023-12-01T10:30:01"/>
272
  </testsuite>
273
</testsuites>
274
```
275

276
The integration automatically handles Django's test database lifecycle and ensures proper test isolation while generating comprehensive XML reports.