pytest-mypy-plugins

Common errors

• No errors reported for obviously wrong code

  cause Mypy, by default, might not type-check functions without any type annotations, or it might infer `Any` types due to missing stubs or the `--ignore-missing-imports` flag, silently passing errors.
  fix Ensure all relevant functions have type annotations. For wider checks, configure mypy to use `--check-untyped-defs`. If `Any` is the issue, investigate missing library stubs or remove `--ignore-missing-imports` to expose hidden import errors.

• Mypy errors are not causing pytest to fail as expected, even with `--mypy` flag.

  cause This can happen if `mypy`'s configuration (e.g., in `mypy.ini` or `pyproject.toml`) contains settings like `ignore_errors = True` or `warn_unreachable = False`, which suppress error reporting. Or, if `--ignore-missing-imports` is broadly used.
  fix Review your `mypy` configuration (e.g., `mypy.ini` or `pyproject.toml`) to ensure error reporting is not suppressed. Remove `ignore_errors = True` or similar options that prevent mypy from failing. Consider removing or narrowing the scope of `--ignore-missing-imports`.

• Cannot import module X when using relative paths in MYPYPATH/PYTHONPATH within pytest-mypy-plugins tests.

  cause When `mypy` runs as a subprocess (the default behavior for `pytest-mypy-plugins`), its working directory might differ from where `pytest` was invoked. This causes relative paths in environment variables to resolve incorrectly.
  fix To resolve this, either configure `pytest-mypy-plugins` to run `mypy` in the same process using the `--mypy-same-process` pytest CLI option, or ensure that any paths specified in `MYPYPATH` or `PYTHONPATH` are absolute paths (e.g., using `$(pwd)/my_plugin` in a shell script).

Warnings

• breaking Errors are now ignored in site-packages by default starting from version 4.0.0.
  Fix: The `--mypy-only-local-stub` flag was removed. To restore the previous behavior of checking errors in site-packages, use the new `--mypy-no-silence-site-packages` flag.
• breaking Python 3.8 support was dropped in versions 3.2.0 and 3.3.0.
  Fix: Ensure your test environment uses Python 3.9 or newer. Python 3.13 support was officially added in 3.3.0.
• breaking Python 3.7 support was dropped starting from version 3.0.0.
  Fix: Upgrade your Python environment to Python 3.8 or newer. The minimum Python requirement for the latest versions is `>=3.10`.
• gotcha Relative paths in `PYTHONPATH` or `MYPYPATH` environment variables may not work as expected when `mypy` runs in a subprocess (the default mode for the plugin).
  Fix: Either invoke `pytest` with `--mypy-same-process` to run `mypy` in the same process, or use absolute paths for `PYTHONPATH` and `MYPYPATH` to ensure correct referencing.

Install

• pip install pytest-mypy-plugins Install with pip

Imports

• pytest-mypy-plugins

  No explicit import usually needed, automatically discovered by pytest.

  pytest plugins are typically auto-discovered upon installation. For advanced configuration, one might access the plugin via `config.pluginmanager.getplugin('mypy')` in `conftest.py`.

Quickstart

Create a Python file (`my_module.py`) with code to be type-checked, and a YAML file (`test_types.yml`) defining test cases. Each `case` block in the YAML file contains `main` (Python code) and uses `# N:` for expected `reveal_type` output or `# E:` for expected mypy error messages. The plugin automatically discovers and runs these tests when `pytest` is executed.

# Save as my_module.py
def add(a: int, b: int) -> int:
    return a + b

# Save as test_types.yml in a directory like 'typesafety/'
- case: correct_addition
  main: |
    from my_module import add
    result = add(1, 2)
    reveal_type(result) # N: Revealed type is 'builtins.int'

- case: incorrect_addition_type
  main: |
    from my_module import add
    add(1, '2') # E: Argument 2 to "add" has incompatible type "str"; expected "int" [arg-type]

# To run tests, simply execute pytest in your terminal from the project root:
# pytest