0
# pytest-cov
1

2
A comprehensive pytest plugin that provides code coverage measurement with enhanced support for distributed testing, subprocess coverage, and multiple reporting formats. pytest-cov extends the standard coverage.py functionality to seamlessly integrate with the pytest testing framework while handling complex testing scenarios including parallel execution, distributed testing via pytest-xdist, and subprocess coverage collection.
3

4
## Package Information
5

6
- **Package Name**: pytest-cov
7
- **Language**: Python
8
- **Installation**: `pip install pytest-cov`
9

10
## Core Imports
11

12
```python
13
import pytest_cov
14
```
15

16
For accessing exceptions and warnings:
17

18
```python
19
from pytest_cov import CoverageError, CovDisabledWarning, CovReportWarning
20
```
21

22
For programmatic access to the plugin:
23

24
```python
25
from pytest_cov.plugin import CovPlugin
26
```
27

28
## Basic Usage
29

30
### Command-line Usage
31

32
```bash
33
# Basic coverage for a package
34
pytest --cov=mypackage tests/
35

36
# Multiple packages with HTML report
37
pytest --cov=package1 --cov=package2 --cov-report=html tests/
38

39
# Branch coverage with failure threshold
40
pytest --cov=mypackage --cov-branch --cov-fail-under=90 tests/
41

42
# Multiple report formats
43
pytest --cov=mypackage --cov-report=term-missing --cov-report=xml tests/
44
```
45

46
### Fixture Usage in Tests
47

48
```python
49
import pytest
50

51
def test_with_coverage_access(cov):
52
    """Test that accesses the coverage object."""
53
    if cov:
54
        # Access underlying coverage.py object
55
        print(f"Coverage data file: {cov.config.data_file}")
56

57
@pytest.mark.no_cover
58
def test_without_coverage():
59
    """This test will not be included in coverage."""
60
    pass
61

62
def test_with_no_cover_fixture(no_cover):
63
    """Test using no_cover fixture to disable coverage."""
64
    pass
65
```
66

67
## Architecture
68

69
pytest-cov implements a plugin architecture that adapts to different testing scenarios:
70

71
- **Plugin Integration**: Registers as a pytest11 plugin via entry points, automatically available when installed
72
- **Controller Pattern**: Uses different coverage controllers based on testing mode (Central, DistMaster, DistWorker)
73
- **Subprocess Support**: Automatically handles coverage for forked processes and subprocesses via environment variable propagation
74
- **Distributed Testing**: Seamlessly integrates with pytest-xdist for parallel test execution with proper coverage data combination
75

76
The plugin hooks into pytest's lifecycle at multiple points to ensure comprehensive coverage collection across all testing scenarios while maintaining compatibility with pytest's extensive ecosystem.
77

78
## Capabilities
79

80
### Command-line Options
81

82
Comprehensive command-line interface providing control over coverage measurement, reporting, and behavior with full integration into pytest's option system.
83

84
```python { .api }
85
# Core coverage options
86
--cov SOURCE                    # Path or package to measure (multi-allowed)
87
--cov-reset                     # Reset accumulated sources
88
--cov-report TYPE               # Report type: term, html, xml, json, lcov, annotate
89
--cov-config PATH               # Coverage config file (default: .coveragerc)
90

91
# Behavior control options  
92
--no-cov                        # Disable coverage completely
93
--no-cov-on-fail               # Don't report coverage if tests fail
94
--cov-append                    # Append to existing coverage data
95
--cov-branch                   # Enable branch coverage
96
--cov-fail-under MIN           # Fail if coverage below threshold
97
--cov-precision N              # Override reporting precision
98
--cov-context CONTEXT          # Dynamic context (only 'test' supported)
99
```
100

101
[Command-line Interface](./command-line.md)
102

103
### Plugin Integration and Hooks
104

105
Core pytest plugin functionality providing seamless integration with pytest's lifecycle and hook system for comprehensive coverage measurement.
106

107
```python { .api }
108
def pytest_addoption(parser): ...
109
def pytest_load_initial_conftests(early_config, parser, args): ...
110
def pytest_configure(config): ...
111

112
class CovPlugin:
113
    def __init__(self, options, pluginmanager, start=True): ...
114
    def start(self, controller_cls, config=None, nodeid=None): ...
115
    def pytest_sessionstart(self, session): ...
116
    def pytest_configure_node(self, node): ...
117
    def pytest_testnodedown(self, node, error): ...
118
    def pytest_runtestloop(self, session): ...
119
    def pytest_terminal_summary(self, terminalreporter): ...
120
    def pytest_runtest_setup(self, item): ...
121
    def pytest_runtest_teardown(self, item): ...
122
    def pytest_runtest_call(self, item): ...
123
```
124

125
[Plugin Integration](./plugin-integration.md)
126

127
### Coverage Controllers
128

129
Engine classes that handle different testing scenarios including single-process, distributed master, and distributed worker modes with proper data collection and combination.
130

131
```python { .api }
132
class CovController:
133
    def __init__(self, options, config, nodeid): ...
134
    def start(self): ...
135
    def finish(self): ...
136
    def pause(self): ...
137
    def resume(self): ...
138
    def summary(self, stream): ...
139

140
class Central(CovController): ...
141
class DistMaster(CovController): ...  
142
class DistWorker(CovController): ...
143
```
144

145
[Coverage Controllers](./coverage-controllers.md)
146

147
### Subprocess and Embed Support
148

149
Automatic coverage measurement for subprocesses and forked processes through environment variable propagation and signal handling.
150

151
```python { .api }
152
def init(): ...
153
def cleanup(): ...
154
def cleanup_on_signal(signum): ...
155
def cleanup_on_sigterm(): ...
156
```
157

158
[Subprocess Support](./subprocess-support.md)
159

160
### Test Fixtures and Markers
161

162
Built-in pytest fixtures and markers for controlling coverage behavior in individual tests.
163

164
```python { .api }
165
@pytest.fixture
166
def no_cover(): ...
167

168
@pytest.fixture  
169
def cov(request): ...
170

171
# Marker registration
172
config.addinivalue_line('markers', 'no_cover: disable coverage for this test.')
173
```
174

175
[Fixtures and Markers](./fixtures-markers.md)
176

177
### Exceptions and Warnings
178

179
Comprehensive error handling with specific exception types and warning categories for different failure scenarios.
180

181
```python { .api }
182
__version__: str  # Package version string
183

184
class CoverageError(Exception): ...
185
class PytestCovWarning(pytest.PytestWarning): ...
186
class CovDisabledWarning(PytestCovWarning): ...
187
class CovReportWarning(PytestCovWarning): ...
188
class CentralCovContextWarning(PytestCovWarning): ...
189
class DistCovError(Exception): ...
190
```
191

192
[Error Handling](./error-handling.md)
193

194
## Types
195

196
```python { .api }
197
# From typing and other modules used in signatures
198
from argparse import Namespace
199
from typing import Union, Optional, List, Dict, Any
200
from pathlib import Path
201
from io import StringIO
202

203
# Plugin configuration namespace
204
class Options:
205
    cov_source: Optional[List[str]]
206
    cov_report: Dict[str, Optional[str]]  
207
    cov_config: str
208
    cov_append: bool
209
    cov_branch: Optional[bool]
210
    cov_fail_under: Optional[Union[int, float]]
211
    cov_precision: Optional[int]
212
    cov_context: Optional[str]
213
    no_cov: bool
214
    no_cov_on_fail: bool
215
```