0
# Test Items
1
2
Specialized pytest test items that handle mypy type checking integration. These items execute mypy checks and integrate results into pytest's test execution and reporting framework.
3
4
## Capabilities
5
6
### Base Mypy Item
7
8
Foundation class for all mypy-related test items with shared functionality.
9
10
```python { .api }
11
class MypyItem(pytest.Item):
12
"""
13
Base class for mypy-related test items.
14
15
Automatically adds the 'mypy' marker to enable filtering with -m mypy.
16
Provides custom error representation for mypy-specific exceptions.
17
"""
18
19
def __init__(self, *args: Any, **kwargs: Any): ...
20
21
def repr_failure(
22
self,
23
excinfo: pytest.ExceptionInfo[BaseException],
24
style: Optional[str] = None
25
) -> Union[str, TerminalRepr]:
26
"""
27
Custom failure representation for mypy errors.
28
29
Parameters:
30
- excinfo: Exception information from pytest
31
- style: Optional styling preference
32
33
Returns:
34
Clean error message string or terminal representation
35
"""
36
```
37
38
### File-Specific Type Checking
39
40
Test item that performs mypy type checking on individual Python files.
41
42
```python { .api }
43
class MypyFileItem(MypyItem):
44
"""
45
Test item for mypy type checking of a specific file.
46
47
Executes mypy on the associated file and reports any type errors
48
found. Integrates with pytest's xfail mechanism when configured.
49
"""
50
51
def runtest(self) -> None:
52
"""
53
Execute mypy check on the associated file.
54
55
Raises MypyError if type checking violations are found,
56
unless all errors are informational notes. Supports xfail
57
mode when --mypy-xfail option is used.
58
59
Raises:
60
- MypyError: When type checking violations are found
61
"""
62
63
def reportinfo(self) -> Tuple[Path, None, str]:
64
"""
65
Generate test report heading for this mypy check.
66
67
Returns:
68
Tuple containing file path, line number (None), and formatted test name
69
"""
70
```
71
72
### Status Validation
73
74
Test item that validates mypy's overall exit status across all checked files.
75
76
```python { .api }
77
class MypyStatusItem(MypyItem):
78
"""
79
Test item for validating mypy's overall exit status.
80
81
Ensures mypy exited successfully across all checked files.
82
Prevents tests from passing when mypy failed globally but
83
individual file checks appeared successful.
84
"""
85
86
def runtest(self) -> None:
87
"""
88
Validate mypy's exit status from the cached results.
89
90
Raises MypyError if mypy exited with non-zero status,
91
indicating type checking failures that may not have been
92
captured by individual file items.
93
94
Raises:
95
- MypyError: When mypy exit status is non-zero
96
"""
97
```
98
99
### Collection Plugin
100
101
Plugin responsible for creating mypy test items during pytest's collection phase.
102
103
```python { .api }
104
class MypyCollectionPlugin:
105
"""
106
Pytest plugin that creates MypyFile instances during collection.
107
108
Automatically registered when mypy options are detected.
109
Creates test items for .py and .pyi files while avoiding
110
duplicate collection when both file types exist.
111
"""
112
113
def pytest_collect_file(
114
self,
115
file_path: Path,
116
parent: pytest.Collector
117
) -> Optional[MypyFile]:
118
"""
119
Create MypyFile for Python source files.
120
121
Parameters:
122
- file_path: Path to potential Python file
123
- parent: Parent collector in pytest hierarchy
124
125
Returns:
126
MypyFile instance for .py/.pyi files, None otherwise
127
128
Note:
129
Skips .py files when corresponding .pyi stub exists
130
to avoid duplicate module errors.
131
"""
132
```
133
134
### File Collector
135
136
Pytest File subclass that generates mypy test items.
137
138
```python { .api }
139
class MypyFile(pytest.File):
140
"""
141
File collector that generates mypy test items.
142
143
Creates both file-specific checking items and optional
144
status validation items for comprehensive type checking.
145
"""
146
147
def collect(self) -> Iterator[MypyItem]:
148
"""
149
Generate mypy test items for this file.
150
151
Yields:
152
- MypyFileItem: Type checking for this specific file
153
- MypyStatusItem: Global mypy status check (when enabled)
154
155
The status item is only created once per session and
156
only when --mypy-no-status-check is not specified.
157
"""
158
```
159
160
## Usage Examples
161
162
### Custom Test Item Handling
163
```python
164
# In conftest.py - customize mypy test items
165
import pytest_mypy
166
167
def pytest_configure(config):
168
# Custom error handling for MypyFileItem
169
original_runtest = pytest_mypy.MypyFileItem.runtest
170
171
def custom_runtest(self):
172
try:
173
original_runtest(self)
174
except pytest_mypy.MypyError as e:
175
# Custom error processing
176
print(f"Type error in {self.path}: {e}")
177
raise
178
179
pytest_mypy.MypyFileItem.runtest = custom_runtest
180
```
181
182
### Accessing Error Details
183
```python
184
# Example of processing mypy errors in test items
185
def pytest_runtest_call(pyfuncitem):
186
if hasattr(pyfuncitem, 'path') and isinstance(pyfuncitem, pytest_mypy.MypyFileItem):
187
# Access mypy results for this item
188
results = pytest_mypy.MypyResults.from_session(pyfuncitem.session)
189
file_errors = results.path_lines.get(pyfuncitem.path.resolve(), [])
190
191
# Filter by error severity
192
error_lines = [line for line in file_errors
193
if pytest_mypy._error_severity(line) == "error"]
194
warning_lines = [line for line in file_errors
195
if pytest_mypy._error_severity(line) == "warning"]
196
197
print(f"Found {len(error_lines)} errors and {len(warning_lines)} warnings")
198
```
199
200
### Marker-Based Filtering
201
```bash
202
# Run only mypy checks, excluding regular tests
203
pytest --mypy -m mypy src/
204
205
# Run mypy checks alongside specific test markers
206
pytest --mypy -m "mypy or unit" src/
207
```
208
209
### Test Report Integration
210
The test items integrate with pytest's standard reporting:
211
- File-specific items show as `[mypy] path/to/file.py`
212
- Status items show as `[mypy] mypy-status`
213
- Errors display with appropriate context and formatting
214
- xfail integration shows expected failures appropriately