0
# Command-line Interface
1

2
pytest-cov provides comprehensive command-line options that integrate seamlessly with pytest's option system. These options control coverage measurement, reporting formats, behavior, and thresholds.
3

4
## Capabilities
5

6
### Coverage Source Selection
7

8
Control which packages or paths are measured for coverage during test execution.
9

10
```python { .api }
11
--cov SOURCE
12
```
13

14
Specifies a path or package name to measure during execution. Can be used multiple times to measure multiple packages. Use `--cov=` with no argument to record everything without source filtering.
15

16
```python { .api }
17
--cov-reset
18
```
19

20
Resets the accumulated coverage sources from previous `--cov` options, allowing you to start fresh with coverage source selection.
21

22
**Usage Examples:**
23

24
```bash
25
# Single package
26
pytest --cov=mypackage tests/
27

28
# Multiple packages  
29
pytest --cov=package1 --cov=package2 tests/
30

31
# Everything (no source filtering)
32
pytest --cov= tests/
33

34
# Reset and specify new sources
35
pytest --cov=old_pkg --cov-reset --cov=new_pkg tests/
36
```
37

38
### Report Generation
39

40
Configure the types and formats of coverage reports generated after test execution.
41

42
```python { .api }
43
--cov-report TYPE
44
```
45

46
Specifies the type of coverage report to generate. Can be used multiple times for multiple report types. Supported types:
47

48
- `term`: Terminal output (default)
49
- `term-missing`: Terminal output with missing line numbers
50
- `html`: HTML report
51
- `xml`: XML report (Cobertura format)  
52
- `json`: JSON report
53
- `lcov`: LCOV format (requires coverage.py >= 6.3)
54
- `annotate`: Annotated source code
55

56
For file-based reports, append `:DEST` to specify output location. For terminal reports, append `:skip-covered` to hide fully covered files.
57

58
**Usage Examples:**
59

60
```bash
61
# Multiple report types
62
pytest --cov=mypackage --cov-report=html --cov-report=xml tests/
63

64
# Custom output locations
65
pytest --cov=mypackage --cov-report=html:htmlcov --cov-report=xml:coverage.xml tests/
66

67
# Terminal with skip-covered
68
pytest --cov=mypackage --cov-report=term-missing:skip-covered tests/
69

70
# No report output
71
pytest --cov=mypackage --cov-report= tests/
72
```
73

74
### Configuration Control
75

76
Specify coverage configuration and control coverage behavior.
77

78
```python { .api }
79
--cov-config PATH
80
```
81

82
Path to the coverage configuration file. Defaults to `.coveragerc` if not specified.
83

84
```python { .api }
85
--cov-append
86
```
87

88
Do not delete existing coverage data; append to current coverage. Default is False (coverage data is reset for each run).
89

90
```python { .api }
91
--cov-branch  
92
```
93

94
Enable branch coverage measurement in addition to statement coverage.
95

96
**Usage Examples:**
97

98
```bash
99
# Custom config file
100
pytest --cov=mypackage --cov-config=custom_coverage.ini tests/
101

102
# Append to existing coverage
103
pytest --cov=mypackage --cov-append tests/
104

105
# Enable branch coverage
106
pytest --cov=mypackage --cov-branch tests/
107
```
108

109
### Reporting Control
110

111
Control coverage reporting behavior and failure conditions.
112

113
```python { .api }
114
--cov-fail-under MIN
115
```
116

117
Fail the test run if the total coverage percentage is less than MIN. Accepts integer or float values up to 100.
118

119
```python { .api }
120
--cov-precision N
121
```
122

123
Override the default reporting precision for coverage percentages.
124

125
```python { .api }
126
--no-cov-on-fail
127
```
128

129
Do not report coverage information if the test run fails. Default is False (coverage is reported regardless of test results).
130

131
```python { .api }
132
--no-cov
133
```
134

135
Completely disable coverage reporting. Useful when running tests with debuggers that may conflict with coverage measurement.
136

137
**Usage Examples:**
138

139
```bash
140
# Fail if coverage below 90%
141
pytest --cov=mypackage --cov-fail-under=90 tests/
142

143
# Custom precision  
144
pytest --cov=mypackage --cov-precision=1 tests/
145

146
# No coverage on test failure
147
pytest --cov=mypackage --no-cov-on-fail tests/
148

149
# Disable coverage completely
150
pytest --cov=mypackage --no-cov tests/
151
```
152

153
### Advanced Options
154

155
Advanced coverage features for specialized use cases.
156

157
```python { .api }
158
--cov-context CONTEXT
159
```
160

161
Enable dynamic context switching for detailed coverage tracking. Currently only supports `test` as the context value, which provides per-test coverage tracking.
162

163
**Usage Examples:**
164

165
```bash
166
# Per-test context tracking  
167
pytest --cov=mypackage --cov-context=test tests/
168
```
169

170
## Validation Functions
171

172
pytest-cov includes validation functions to ensure command-line arguments are properly formatted and supported.
173

174
```python { .api }
175
def validate_report(arg: str) -> tuple:
176
    """
177
    Validate --cov-report argument format.
178
    
179
    Args:
180
        arg: Report specification (e.g., 'html', 'xml:output.xml', 'term:skip-covered')
181
        
182
    Returns:
183
        tuple: (report_type, modifier_or_output_path)
184
        
185
    Raises:
186
        argparse.ArgumentTypeError: If format is invalid or unsupported
187
    """
188

189
def validate_fail_under(num_str: str) -> Union[int, float]:
190
    """
191
    Validate --cov-fail-under argument.
192
    
193
    Args:
194
        num_str: Numeric string for coverage threshold
195
        
196
    Returns:
197
        Union[int, float]: Validated threshold value
198
        
199
    Raises:
200
        argparse.ArgumentTypeError: If not a valid number or > 100
201
    """
202

203
def validate_context(arg: str) -> str:
204
    """
205
    Validate --cov-context argument.
206
    
207
    Args:
208
        arg: Context specification
209
        
210
    Returns:
211
        str: Validated context value
212
        
213
    Raises:
214
        argparse.ArgumentTypeError: If context not supported or coverage.py too old
215
    """
216
```
217

218
## Option Processing
219

220
Internal functions that process and prepare command-line options for use by the coverage engine.
221

222
```python { .api }
223
def _prepare_cov_source(cov_source: List[Union[str, bool]]) -> Optional[List[str]]:
224
    """
225
    Process cov_source list to handle special cases.
226
    
227
    Makes --cov --cov=foobar equivalent to --cov (no filtering)
228
    and --cov=foo --cov=bar equivalent to filtering on ['foo', 'bar'].
229
    
230
    Args:
231
        cov_source: List containing source paths and boolean flags
232
        
233
    Returns:
234
        Optional[List[str]]: None for no filtering, list of sources otherwise
235
    """
236
```