0
# Command Line Interface
1

2
Comprehensive command-line configuration for controlling mypy behavior within pytest test runs. These options provide fine-grained control over type checking execution, error reporting, and failure handling.
3

4
## Capabilities
5

6
### Core Enable Option
7

8
The primary flag to activate mypy checking during pytest execution.
9

10
```python { .api }
11
def pytest_addoption(parser: pytest.Parser) -> None:
12
    """
13
    Add mypy command line options to pytest parser.
14
    
15
    Registers the following options:
16
    --mypy: Enable mypy type checking
17
    --mypy-ignore-missing-imports: Suppress import resolution errors
18
    --mypy-config-file: Specify custom mypy configuration file
19
    --mypy-report-style: Choose error output format
20
    --mypy-no-status-check: Ignore mypy exit status
21
    --mypy-xfail: Mark mypy errors as expected failures
22
    """
23
```
24

25
### Import Handling
26

27
Control how mypy handles missing or unresolvable imports during type checking.
28

29
**--mypy-ignore-missing-imports**
30
- Suppresses error messages about imports that cannot be resolved
31
- Equivalent to mypy's `--ignore-missing-imports` option
32
- Useful for codebases with optional dependencies or incomplete stubs
33

34
Usage example:
35
```bash
36
pytest --mypy --mypy-ignore-missing-imports src/
37
```
38

39
### Configuration File Override
40

41
Specify a custom mypy configuration file instead of using the default `mypy.ini`.
42

43
**--mypy-config-file PATH**
44
- Accepts path to custom mypy configuration file
45
- Overrides default mypy configuration discovery
46
- Allows project-specific mypy settings for pytest runs
47

48
Usage example:
49
```bash
50
pytest --mypy --mypy-config-file ./custom-mypy.ini src/
51
```
52

53
### Error Reporting Styles
54

55
Control the format and verbosity of mypy error output within pytest reports.
56

57
**--mypy-report-style STYLE**
58

59
Available styles:
60
- `mypy`: Preserve original mypy output format with full paths
61
- `no-path` (default): Strip path prefixes from error messages for cleaner output
62

63
Usage example:
64
```bash
65
pytest --mypy --mypy-report-style=mypy src/
66
```
67

68
### Status Check Control
69

70
Control whether pytest validates mypy's exit status in addition to per-file errors.
71

72
**--mypy-no-status-check**
73
- Ignores mypy's overall exit status
74
- Only reports per-file type checking errors
75
- Useful when mypy exit status is unreliable or not meaningful
76

77
Usage example:
78
```bash
79
pytest --mypy --mypy-no-status-check src/
80
```
81

82
### Expected Failure Mode
83

84
Mark mypy errors as expected failures instead of test failures.
85

86
**--mypy-xfail**
87
- Converts mypy errors to xfail (expected failure) status
88
- Allows tests to pass even when type errors are present
89
- Useful during gradual typing adoption or when type errors are temporary
90

91
Usage example:
92
```bash
93
pytest --mypy --mypy-xfail src/
94
```
95

96
## Usage Patterns
97

98
### Basic Type Checking
99
```bash
100
# Enable mypy checking on Python files
101
pytest --mypy src/
102

103
# Check only mypy tests using markers
104
pytest --mypy -m mypy src/
105
```
106

107
### Advanced Configuration
108
```bash
109
# Comprehensive mypy checking with custom settings
110
pytest --mypy \
111
       --mypy-ignore-missing-imports \
112
       --mypy-config-file ./strict-mypy.ini \
113
       --mypy-report-style=no-path \
114
       src/
115
```
116

117
### Gradual Typing Support
118
```bash
119
# Allow mypy errors without failing tests
120
pytest --mypy --mypy-xfail src/
121

122
# Ignore status check for partial typing adoption
123
pytest --mypy --mypy-no-status-check src/
124
```