0
# Report Generation
1

2
Multiple output formats for coverage reports including console text, HTML with highlighting, XML (Cobertura), JSON, LCOV, and annotated source files. Each reporter provides different visualization and integration capabilities.
3

4
## Capabilities
5

6
### Console Text Reports
7

8
Generate formatted console output showing coverage statistics and missing lines.
9

10
```python { .api }
11
def report(
12
    self,
13
    morfs=None,                    # Files/modules to report on
14
    show_missing=None,             # Show line numbers of missing statements
15
    ignore_errors=None,            # Ignore source file errors
16
    file=None,                     # Output file object
17
    omit=None,                     # File patterns to omit
18
    include=None,                  # File patterns to include
19
    skip_covered=None,             # Skip files with 100% coverage
20
    contexts=None,                 # Context labels to filter by
21
    skip_empty=None,               # Skip files with no executable code
22
    precision=None,                # Decimal precision for percentages
23
    sort=None,                     # Sort order for files
24
    output_format=None             # Output format ('text' or 'total')
25
) -> float:
26
    """
27
    Generate a text coverage report.
28
    
29
    Parameters:
30
    - morfs (list | None): Modules or filenames to report on
31
    - show_missing (bool | None): Include line numbers of missing statements
32
    - ignore_errors (bool | None): Continue despite source file errors
33
    - file (IO | None): File object to write output (default stdout)
34
    - omit (str | list[str] | None): File patterns to omit from report
35
    - include (str | list[str] | None): File patterns to include in report
36
    - skip_covered (bool | None): Don't report files with 100% coverage
37
    - contexts (list[str] | None): Only include data from these contexts
38
    - skip_empty (bool | None): Don't report files with no executable code
39
    - precision (int | None): Number of decimal places for percentages
40
    - sort (str | None): Sort files by 'name', 'stmts', 'miss', 'branch', 'brpart', 'cover'
41
    - output_format (str | None): 'text' for full report, 'total' for percentage only
42
    
43
    Returns:
44
        float: Overall coverage percentage
45
    """
46
```
47

48
Usage example:
49

50
```python
51
import coverage
52

53
cov = coverage.Coverage()
54
cov.start()
55
# ... run code ...
56
cov.stop()
57

58
# Basic console report
59
total_coverage = cov.report()
60
print(f"Total coverage: {total_coverage:.1f}%")
61

62
# Detailed report with missing lines
63
cov.report(
64
    show_missing=True,
65
    skip_covered=False,
66
    precision=1,
67
    sort='cover'
68
)
69

70
# Report specific files only
71
cov.report(
72
    morfs=['src/core.py', 'src/utils.py'],
73
    show_missing=True
74
)
75

76
# Save report to file
77
with open('coverage_report.txt', 'w') as f:
78
    cov.report(file=f, show_missing=True)
79
```
80

81
### HTML Reports
82

83
Generate interactive HTML reports with syntax highlighting and detailed coverage visualization.
84

85
```python { .api }
86
def html_report(
87
    self,
88
    morfs=None,                    # Files/modules to report on
89
    directory=None,                # Output directory
90
    ignore_errors=None,            # Ignore source file errors
91
    omit=None,                     # File patterns to omit
92
    include=None,                  # File patterns to include
93
    contexts=None,                 # Context labels to filter by
94
    skip_covered=None,             # Skip files with 100% coverage
95
    skip_empty=None,               # Skip files with no executable code
96
    show_contexts=None,            # Show context information
97
    title=None,                    # Title for HTML pages
98
    precision=None                 # Decimal precision for percentages
99
) -> float:
100
    """
101
    Generate an HTML coverage report.
102
    
103
    Parameters:
104
    - morfs (list | None): Modules or filenames to report on
105
    - directory (str | None): Directory to write HTML files (default 'htmlcov')
106
    - ignore_errors (bool | None): Continue despite source file errors
107
    - omit (str | list[str] | None): File patterns to omit from report
108
    - include (str | list[str] | None): File patterns to include in report
109
    - contexts (list[str] | None): Only include data from these contexts
110
    - skip_covered (bool | None): Don't report files with 100% coverage
111
    - skip_empty (bool | None): Don't report files with no executable code
112
    - show_contexts (bool | None): Include context information in HTML
113
    - title (str | None): Title for the HTML report pages
114
    - precision (int | None): Number of decimal places for percentages
115
    
116
    Returns:
117
        float: Overall coverage percentage
118
    """
119
```
120

121
Usage example:
122

123
```python
124
import coverage
125

126
cov = coverage.Coverage()
127
cov.start()
128
# ... run code ...
129
cov.stop()
130

131
# Basic HTML report
132
total_coverage = cov.html_report()
133
print(f"HTML report generated, total coverage: {total_coverage:.1f}%")
134

135
# Customized HTML report
136
cov.html_report(
137
    directory='custom_htmlcov',
138
    title='My Project Coverage Report',
139
    show_contexts=True,
140
    skip_covered=True,
141
    precision=2
142
)
143

144
# Report specific modules
145
cov.html_report(
146
    morfs=['src/'],
147
    directory='src_coverage',
148
    omit=['*/tests/*']
149
)
150
```
151

152
### XML Reports
153

154
Generate XML reports in Cobertura format for integration with CI/CD systems and IDEs.
155

156
```python { .api }
157
def xml_report(
158
    self,
159
    morfs=None,                    # Files/modules to report on
160
    outfile=None,                  # Output file path or object
161
    ignore_errors=None,            # Ignore source file errors
162
    omit=None,                     # File patterns to omit
163
    include=None,                  # File patterns to include
164
    contexts=None,                 # Context labels to filter by
165
    skip_empty=None,               # Skip files with no executable code
166
    precision=None                 # Decimal precision for percentages
167
) -> float:
168
    """
169
    Generate an XML coverage report in Cobertura format.
170
    
171
    Parameters:
172
    - morfs (list | None): Modules or filenames to report on
173
    - outfile (str | IO | None): File path or object to write XML (default 'coverage.xml')
174
    - ignore_errors (bool | None): Continue despite source file errors
175
    - omit (str | list[str] | None): File patterns to omit from report
176
    - include (str | list[str] | None): File patterns to include in report
177
    - contexts (list[str] | None): Only include data from these contexts
178
    - skip_empty (bool | None): Don't report files with no executable code
179
    - precision (int | None): Number of decimal places for percentages
180
    
181
    Returns:
182
        float: Overall coverage percentage
183
    """
184
```
185

186
Usage example:
187

188
```python
189
import coverage
190

191
cov = coverage.Coverage()
192
cov.start()
193
# ... run code ...
194
cov.stop()
195

196
# Basic XML report
197
total_coverage = cov.xml_report()
198
print(f"XML report written to coverage.xml, total: {total_coverage:.1f}%")
199

200
# Custom XML output file
201
cov.xml_report(outfile='reports/cobertura.xml')
202

203
# XML report with file object
204
with open('custom_coverage.xml', 'w') as f:
205
    cov.xml_report(outfile=f, precision=2)
206
```
207

208
### JSON Reports
209

210
Generate JSON format reports for programmatic processing and integration.
211

212
```python { .api }
213
def json_report(
214
    self,
215
    morfs=None,                    # Files/modules to report on
216
    outfile=None,                  # Output file path or object
217
    ignore_errors=None,            # Ignore source file errors
218
    omit=None,                     # File patterns to omit
219
    include=None,                  # File patterns to include
220
    contexts=None,                 # Context labels to filter by
221
    skip_empty=None,               # Skip files with no executable code
222
    precision=None,                # Decimal precision for percentages
223
    pretty_print=None,             # Format JSON for readability
224
    show_contexts=None             # Include context information
225
) -> float:
226
    """
227
    Generate a JSON coverage report.
228
    
229
    Parameters:
230
    - morfs (list | None): Modules or filenames to report on
231
    - outfile (str | IO | None): File path or object to write JSON (default 'coverage.json')
232
    - ignore_errors (bool | None): Continue despite source file errors
233
    - omit (str | list[str] | None): File patterns to omit from report
234
    - include (str | list[str] | None): File patterns to include in report
235
    - contexts (list[str] | None): Only include data from these contexts
236
    - skip_empty (bool | None): Don't report files with no executable code
237
    - precision (int | None): Number of decimal places for percentages
238
    - pretty_print (bool | None): Format JSON for human readability
239
    - show_contexts (bool | None): Include context information in output
240
    
241
    Returns:
242
        float: Overall coverage percentage
243
    """
244
```
245

246
Usage example:
247

248
```python
249
import coverage
250

251
cov = coverage.Coverage()
252
cov.start()
253
# ... run code ...
254
cov.stop()
255

256
# Basic JSON report
257
total_coverage = cov.json_report()
258
print(f"JSON report written to coverage.json, total: {total_coverage:.1f}%")
259

260
# Pretty-printed JSON with contexts
261
cov.json_report(
262
    outfile='reports/coverage.json',
263
    pretty_print=True,
264
    show_contexts=True,
265
    precision=2
266
)
267

268
# Process JSON programmatically
269
import json
270
import io
271

272
json_buffer = io.StringIO()
273
cov.json_report(outfile=json_buffer)
274
json_data = json.loads(json_buffer.getvalue())
275
print(f"Files: {len(json_data['files'])}")
276
```
277

278
### LCOV Reports
279

280
Generate LCOV format reports for integration with LCOV tools and web interfaces.
281

282
```python { .api }
283
def lcov_report(
284
    self,
285
    morfs=None,                    # Files/modules to report on
286
    outfile=None,                  # Output file path or object
287
    ignore_errors=None,            # Ignore source file errors
288
    omit=None,                     # File patterns to omit
289
    include=None,                  # File patterns to include
290
    contexts=None,                 # Context labels to filter by
291
    skip_empty=None,               # Skip files with no executable code
292
    precision=None                 # Decimal precision for percentages
293
) -> float:
294
    """
295
    Generate an LCOV coverage report.
296
    
297
    Parameters:
298
    - morfs (list | None): Modules or filenames to report on
299
    - outfile (str | IO | None): File path or object to write LCOV (default 'coverage.lcov')
300
    - ignore_errors (bool | None): Continue despite source file errors
301
    - omit (str | list[str] | None): File patterns to omit from report
302
    - include (str | list[str] | None): File patterns to include in report
303
    - contexts (list[str] | None): Only include data from these contexts
304
    - skip_empty (bool | None): Don't report files with no executable code
305
    - precision (int | None): Number of decimal places for percentages
306
    
307
    Returns:
308
        float: Overall coverage percentage
309
    """
310
```
311

312
Usage example:
313

314
```python
315
import coverage
316

317
cov = coverage.Coverage()
318
cov.start()
319
# ... run code ...
320
cov.stop()
321

322
# Basic LCOV report
323
total_coverage = cov.lcov_report()
324
print(f"LCOV report written to coverage.lcov, total: {total_coverage:.1f}%")
325

326
# Custom LCOV output
327
cov.lcov_report(
328
    outfile='reports/lcov.info',
329
    omit=['*/test_*']
330
)
331
```
332

333
### Annotated Source Files
334

335
Generate annotated source files showing coverage line-by-line.
336

337
```python { .api }
338
def annotate(
339
    self,
340
    morfs=None,                    # Files/modules to annotate
341
    directory=None,                # Output directory
342
    ignore_errors=None,            # Ignore source file errors
343
    omit=None,                     # File patterns to omit
344
    include=None,                  # File patterns to include
345
    contexts=None                  # Context labels to filter by
346
) -> None:
347
    """
348
    Generate annotated source files showing coverage.
349
    
350
    Parameters:
351
    - morfs (list | None): Modules or filenames to annotate
352
    - directory (str | None): Directory to write annotated files (default '.')
353
    - ignore_errors (bool | None): Continue despite source file errors
354
    - omit (str | list[str] | None): File patterns to omit from annotation
355
    - include (str | list[str] | None): File patterns to include in annotation
356
    - contexts (list[str] | None): Only include data from these contexts
357
    """
358
```
359

360
Usage example:
361

362
```python
363
import coverage
364

365
cov = coverage.Coverage()
366
cov.start()
367
# ... run code ...
368
cov.stop()
369

370
# Generate annotated source files
371
cov.annotate(directory='annotated_source')
372

373
# Annotate specific files
374
cov.annotate(
375
    morfs=['src/core.py', 'src/utils.py'],
376
    directory='annotations'
377
)
378
```
379

380
## Report Configuration
381

382
All reporting methods support common filtering and formatting options:
383

384
### File Selection
385

386
- **`morfs`**: Specify particular modules or files to include
387
- **`omit`**: Exclude files matching glob patterns
388
- **`include`**: Only include files matching glob patterns
389
- **`skip_covered`**: Exclude files with 100% coverage
390
- **`skip_empty`**: Exclude files with no executable statements
391

392
### Data Filtering
393

394
- **`contexts`**: Filter data by context labels (for dynamic context switching)
395
- **`ignore_errors`**: Continue processing despite source file errors
396

397
### Output Formatting
398

399
- **`precision`**: Number of decimal places for coverage percentages
400
- **`show_contexts`**: Include context information in output (HTML/JSON)
401
- **`pretty_print`**: Format JSON output for readability
402

403
### Example: Comprehensive Reporting Workflow
404

405
```python
406
import coverage
407

408
# Set up coverage with branch measurement
409
cov = coverage.Coverage(
410
    branch=True,
411
    source=['src/'],
412
    omit=['*/tests/*', '*/migrations/*']
413
)
414

415
cov.start()
416
# ... run your application/tests ...
417
cov.stop()
418
cov.save()
419

420
# Generate all report formats
421
print("Generating coverage reports...")
422

423
# Console report
424
total_coverage = cov.report(
425
    show_missing=True,
426
    skip_covered=True,
427
    precision=1
428
)
429

430
# HTML report for browsing
431
cov.html_report(
432
    directory='htmlcov',
433
    title='My Project Coverage Report',
434
    show_contexts=True
435
)
436

437
# XML report for CI/CD
438
cov.xml_report(outfile='reports/coverage.xml')
439

440
# JSON report for programmatic use
441
cov.json_report(
442
    outfile='reports/coverage.json',
443
    pretty_print=True,
444
    show_contexts=True
445
)
446

447
# LCOV report for integration tools
448
cov.lcov_report(outfile='reports/coverage.lcov')
449

450
print(f"Total coverage: {total_coverage:.1f}%")
451
print("All reports generated successfully!")
452
```