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
```

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.