pytest-stub

What it is and what it does

pytest-stub is a pytest plugin that intercepts imports and replaces external dependencies with stubs—either auto-generated placeholders (functions, classes, mocks) or custom objects you provide. This lets you test code that depends on heavy or unavailable libraries (like OpenCV, Django, or NumPy) without installing them, which is useful when testing a library that uses those dependencies but you want to isolate your test environment.

The plugin works via a `stub` fixture in individual tests or a global `stub_global()` function in conftest.py. You pass a dictionary mapping import paths to stub types: `'[func]'` generates a function, `'[cls]'` generates a class, `'[mock]'` generates a MagicMock, and `'[mock_persist]'` generates a persistent mock. You can also provide custom objects directly. The stubs are applied before test execution so imports succeed without the actual dependency present.

Use it for:

• Test a library that depends on OpenCV or NumPy without installing those heavy packages in your CI environment.
• Isolate tests of Django-related code by stubbing django.core.management and django.conf modules.
• Verify that your code handles missing or unavailable dependencies gracefully without actually removing them.
• Speed up test runs by replacing slow-to-import or slow-to-initialize external libraries with lightweight stubs.
• Test code paths that use optional dependencies without requiring those dependencies to be installed.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that replaces package, module, and attribute dependencies with stubs—either auto-generated (functions, classes, mocks) or custom objects—so you can test code that depends on external libraries without installing them.

Yes, if you need to test code with external dependencies you don't want to install—the plugin is simple and has no runtime dependencies. However, maintenance is abandoned (last release 2020-04-28), so compatibility with Python versions beyond 3.8 is unverified and you should test it in your environment first. For active projects, consider whether a maintained alternative or manual mocking would be more reliable long-term.

Install

pytest-stub on PyPI

pip install pytest-stub

uv add pytest-stub

poetry add pytest-stub

Installing pytest-stub

Before you install

Low install friction with no runtime dependencies. Maintenance is inactive—last release was 2020-04-28 and the repository shows no recent activity—so you should expect no bug fixes or updates for new Python versions beyond those already listed.

License in practice

BSD 3-Clause License is permissive and imposes minimal restrictions; you can use this package freely in commercial and private projects with only attribution required.

Quickstart

# Install
pip install pytest-stub

# In your test file
def test_example(stub):
    stub.apply({
        'django.core.management.call_command': '[func]',
        'cv2': '[mock]',
    })

Requires pytest >= 2.9.0 and Python 3.6 or later.

Verify before relying

• Whether the package works reliably with Python versions newer than 3.8 (last tested version in classifiers).
• Whether auto-generated stubs ([func], [cls], [mock], [mock_persist]) behave correctly for complex dependency signatures.
• Current compatibility with modern pytest versions and whether any breaking changes have occurred since 2020.

Package facts

Evidence: pytest_stub-1.1.0-py2.py3-none-any.whl

Tags

More Testing packages