pytest-typing: Test Your Types

Ensure your types do what you think they do.

pytest-typing lets you test the type signatures of your code to ensure they really are what you expect. You write Markdown files with Python code blocks and expected type assertions; pytest-typing runs type checkers on these blocks and compares the actual and expected outputs.

First, install the plugin, making it discoverable by pytest:

$ pip install pytest-typing
$ # or
$ uv add pytest-typing --group dev

Then, configure pytest-typing with the type checker (or checkers) you want to use in pyproject.toml:

[tool.pytest]
typing_checkers = ["mypy"]

The currently supported type checkers are Mypy, ty, Pyrefly, and Pyright.

Finally, start writing Markdown files in your test directory (tests/ by default). The files need to be named test_typing_*.md in order to be collected.

Inside the Markdown file, use Markdown headings (#, ##, etc.) to separate tests. Inside each heading, write fenced Python code blocks (python or py) with code that will be type-checked.

This is what an example file might look like, defining two tests:

# This is a test file

This is free-form text that can explain the test but is ignored by the plugin.

## This is a happy-path test

This code snippet should type-check without problems.

```python
a: int = 1
```

## This is a sad-path test

This test demonstrates how errors can be checked using error codes.
Note that error codes are specific to individual type checkers.

```python
a: str = 1  # error: [invalid-assignment]
```

In addition to matching on error codes, we can additionally match the exact error messages too.

a: str = 1  # error: [invalid-assignment] Object of type `Literal[1]` is not assignable to `str`

Although this may be fragile since checkers can improve their error messages from time to time.

Comments may be placed above lines that are expected to produce errors.

# error: [invalid-assignment]
a: str = 1

reveal_type statements can be matched against.

reveal_type(1)  # revealed: Literal[1]

Or, again, on the line above.

# revealed: Literal[1]
reveal_type(1)

A section may contain multiple code blocks; this is useful for inserting longer pieces of prose in between blocks. All blocks within a section get concatenated.

# This test contains multiple blocks

```python
a: int = 1
```

Here's some prose explaining what's going on, and then a second block:

```python
b: str = 1  # error: [invalid-assignment]
```

Testing on multiple checkers

When the typing_checkers field is configured with multiple checkers, tests will be run on all of them. Difference checkers usually have different error codes, so different error comments should be used.

a: str = 1  # ty-error: [invalid-assignment]  # mypy-error: [assignment]

Or, when more checkers are in use, stacked:

# ty-error: [invalid-assignment]
# mypy-error: [assignment]
# pyrefly-error: [bad-assignment]
# pyright-error: [reportAssignmentType]
a: str = 1

A code block can be configured to run only on a specific checker:

```python only=mypy
a: int = 1
```

Or configured to skip only a specific checker:

```python skip=mypy
a: int = 1
```

Pyrefly presets

pytest-typing runs Pyrefly with --preset default so temporary test snippets receive full type checking. Without an explicit preset, recent Pyrefly versions fall back to minimal checking for these unconfigured snippets and can miss assignment errors.

Select a different Pyrefly preset in your pytest configuration:

[tool.pytest]
typing_checkers = ["pyrefly"]
typing_pyrefly_preset = "strict"

Or override it for a single run:

pytest --typing-pyrefly-preset=strict

The command-line option takes precedence over configuration and only affects Pyrefly. Preset names are validated by your installed Pyrefly version. Use a version supporting --preset, or set typing_pyrefly_preset = "" to omit the flag and retain Pyrefly's own configuration selection.

pytest-typing is inspired by Astral's mdtest framework.

Project Information

• PyPI
• Source Code
• Changelog

License

pytest-typing is written by Tin Tvrtković and distributed under the terms of the MIT license.