Command Line Interface

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.

Capabilities

Core Enable Option

The primary flag to activate mypy checking during pytest execution.

def pytest_addoption(parser: pytest.Parser) -> None:
    """
    Add mypy command line options to pytest parser.
    
    Registers the following options:
    --mypy: Enable mypy type checking
    --mypy-ignore-missing-imports: Suppress import resolution errors
    --mypy-config-file: Specify custom mypy configuration file
    --mypy-report-style: Choose error output format
    --mypy-no-status-check: Ignore mypy exit status
    --mypy-xfail: Mark mypy errors as expected failures
    """

Import Handling

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

--mypy-ignore-missing-imports

• Suppresses error messages about imports that cannot be resolved
• Equivalent to mypy's --ignore-missing-imports option
• Useful for codebases with optional dependencies or incomplete stubs

Usage example:

pytest --mypy --mypy-ignore-missing-imports src/

Configuration File Override

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

--mypy-config-file PATH

• Accepts path to custom mypy configuration file
• Overrides default mypy configuration discovery
• Allows project-specific mypy settings for pytest runs

Usage example:

pytest --mypy --mypy-config-file ./custom-mypy.ini src/

Error Reporting Styles

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

--mypy-report-style STYLE

Available styles:

• mypy: Preserve original mypy output format with full paths
• no-path (default): Strip path prefixes from error messages for cleaner output

Usage example:

pytest --mypy --mypy-report-style=mypy src/

Status Check Control

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

--mypy-no-status-check

• Ignores mypy's overall exit status
• Only reports per-file type checking errors
• Useful when mypy exit status is unreliable or not meaningful

Usage example:

pytest --mypy --mypy-no-status-check src/

Expected Failure Mode

Mark mypy errors as expected failures instead of test failures.

--mypy-xfail

• Converts mypy errors to xfail (expected failure) status
• Allows tests to pass even when type errors are present
• Useful during gradual typing adoption or when type errors are temporary

Usage example:

pytest --mypy --mypy-xfail src/

Usage Patterns

Basic Type Checking

# Enable mypy checking on Python files
pytest --mypy src/

# Check only mypy tests using markers
pytest --mypy -m mypy src/

Advanced Configuration

# Comprehensive mypy checking with custom settings
pytest --mypy \
       --mypy-ignore-missing-imports \
       --mypy-config-file ./strict-mypy.ini \
       --mypy-report-style=no-path \
       src/

Gradual Typing Support

# Allow mypy errors without failing tests
pytest --mypy --mypy-xfail src/

# Ignore status check for partial typing adoption
pytest --mypy --mypy-no-status-check src/