pytest-beartype is a pytest plugin type-checking tests, fixtures, and your packages at test-time via @beartype.

The unbearably fast near-real-time pure-Python runtime-static type-checker.

pytest-beartype is portably implemented in Python 3, continuously stress-tested via GitHub Actions × tox × pytest, and permissively distributed under the MIT license. pytest-beartype has only two runtime dependencies (i.e., pytest and @beartype) and no test-time dependencies. pytest-beartype supports all actively developed Python versions and all Python package managers.

pytest-beartype supports your favourite Python package managers! It better.

• Via uv, the newest upstart to emerge victorious in the battle of wills:

  uv add pytest-beartype       # <-- by the power of ultraviolet radiation

• Via pip, the once-great venerable master now fallen on hard times:

  pip install pytest-beartype  # <-- sometimes the old ways are still okay

pytest-beartype: QA without doing anything.

pytest-beartype does nothing by default. This plugin only type-checks your packages, your pytest tests, and your pytest fixtures when you tell it to – for your safety and the safety of the code you test:

• Type-check everything at the command line! (◕‿◕✿)

  $ pytest --beartype-tests --beartype-fixtures --beartype-packages="my_package,your_package" --beartype-skip-packages="my_package.my_bad_submodule,your_bad_package"

• Type-check everything from pyproject.toml! (◡‿◡✿)

  [tool.pytest.ini_options]
  beartype_tests = true
  beartype_fixtures = true
  beartype_packages = ["my_package", "your_package"]
  beartype_skip_packages = ["my_package.my_bad_submodule", "your_bad_package"]

• Type-check everything from pytest.ini! (❀◦‿◦)

  [pytest]
  beartype_tests = true
  beartype_fixtures = true
  beartype_packages = my_package your_package
  beartype_skip_packages = my_package.my_bad_submodule your_bad_package

Would you like to know more? Continue reading for details that may bore you.

pytest-beartype configurably type-checks any combination of pytest tests, pytest fixtures, and one or more arbitrary Python packages through plugin-specific options either temporarily passed to the pytest command or permanently set from within project-specific pyproject.toml and pytest.ini configuration files:

Would you like to know more? Wow. You really are a curious person. You rock! 🪨

By default, pytest-beartype type-checks no packages outside your test suite. If your package(s) are already internally type-checked by @beartype, that's fine. On the other hand, if you'd prefer to conditionally type-check your package(s) by @beartype while running tests (and only while running tests), configure pytest-beartype to either...

Type-check a single package (e.g., yours) while running tests:

• By passing the --beartype-packages={package_name} option to the pytest command:

  pytest --beartype-packages=muh_package_name

• By setting the beartype_packages = ["{package_name}"] option in your pyproject.toml file:

  [tool.pytest.ini_options]
  beartype_packages = ["muh_package_name"]

• By setting the beartype_packages = {package_name} option in your pytest.ini file:

  beartype_packages = muh_package_name

pytest-beartype: Because life's already too complicated.

Type-check two or more packages (e.g., yours) while running tests:

• By passing the --beartype-packages="{first_package_name},...,{last_package_name}" option as a comma-delimited list to the pytest command:

  pytest --beartype-packages='muh_package_name,muh_other_package_name'

• By setting the beartype_packages = ["{first_package_name}", ..., "{last_package_name}"] option as a comma-delimited list in your pyproject.toml file:

  # In "pyproject.toml":
  [tool.pytest.ini_options]
  beartype_packages = ["muh_package_name", "muh_other_package_name"]

• By setting the beartype_packages = {first_package_name} ... {last_package_name} option as a whitespace-delimited list in your pytest.ini file:

  # In "pytest.ini":
  beartype_packages = muh_package_name muh_other_package_name

pytest-beartype: Because code's already too complicated, too.

Type-check all packages transitively imported anywhere while running tests. Type-check your entire app stack at test time! Only the brave, the foolhardy, and the desperate need apply:

• By passing the --beartype-packages="*" option to the pytest command.

  pytest --beartype-packages='*'

  CAUTION: The "*" character should typically be single- or double-quoted to prevent your shell from erroneously expanding that as a pathname glob.

• By setting the beartype_packages = ["*"] option in your [pyproject.toml

• file]pyproject.toml:

  [tool.pytest.ini_options]
  beartype_packages = ["muh_package_name", "muh_other_package_name"]

• By setting the beartype_packages = * option in your [pytest.ini

• file]pytest.ini:

  beartype_packages = *

CAUTION: You may need to omit problematic packages by also passing the --beartype-skip-packages option to the pytest command command or setting the beartype_skip_packages option in your pyproject.toml and pytest.ini files. See below for further commentary that will bore you into oblivion.

By default, beartype type-checking is applied to your test functions and fixtures. To disable this behavior, use the --beartype-ignore-tests option:

pytest --beartype-packages=your_package_name --beartype-ignore-tests

When enabled (default), beartype decoration is applied to:

• Test functions: All collected test functions will have their parameters and return types validated
• Fixtures: All fixtures will be validated according to beartype, and tests requesting fixtures with invalid types will fail.

You can also configure this option in your pytest.ini file:

beartype_ignore_tests = true

pytest-beartype is open-source software released under the permissive MIT license.

pytest-beartype encourages security researchers, institutes, and concerned netizens to responsibly disclose security vulnerabilities as GitHub-originated Security Advisories – published with full acknowledgement in the public GitHub Advisory Database.