pytest-subprocess

What it is and what it does

pytest-subprocess is a pytest plugin that intercepts calls to subprocess.Popen and its higher-level wrappers (subprocess.run, subprocess.call, subprocess.check_call, subprocess.check_output) to replace them with fake implementations. Instead of executing real system commands during tests, you register expected commands and their outputs using the fp fixture, which then returns those outputs when your code calls subprocess. This eliminates test dependencies on external tools, makes tests faster and more reliable, and lets you simulate error conditions and edge cases that would be hard to trigger with real processes.

The plugin supports registering different outputs for repeated calls to the same command, passing input to stdin with custom handling logic, allowing unregistered commands to fall through to real subprocess execution, and using callbacks to inject custom behavior. It works across all subprocess functions because they all ultimately call Popen internally. The fixture is available both as fp and the longer form fake_process.

Use it for:

• Test code that shells out to git, docker, or other CLI tools without requiring those tools to be installed or available in CI
• Simulate subprocess failures and non-zero exit codes to verify error handling paths in your application
• Mock multi-step command sequences where each call returns different output, testing state-dependent subprocess behavior
• Verify that your code passes the correct arguments and environment to subprocess without actually executing them
• Test subprocess input/output handling by registering stdin callbacks that transform input into output

Worth the install?

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

Pytest plugin that intercepts and fakes subprocess calls, allowing you to register mock process outputs and behaviors without executing real commands.

Yes. This is a mature, actively maintained plugin with no security issues, low install friction, and a permissive license. It directly solves the common testing problem of isolating code that calls external processes. Install it if your test suite includes code that uses subprocess.

Install

pytest-subprocess on PyPI

pip install pytest-subprocess

uv add pytest-subprocess

poetry add pytest-subprocess

Installing pytest-subprocess

Before you install

Low friction install with a single runtime dependency (pytest). The package is actively maintained with a recent release and no known vulnerabilities, making it straightforward to add to test suites.

License in practice

MIT license is permissive, allowing use in commercial and open-source projects with minimal restrictions—just include the license text.

Quickstart

pip install pytest-subprocess

import subprocess

def test_example(fp):
    fp.register(["echo", "hello"], stdout="hello")
    result = subprocess.run(["echo", "hello"], capture_output=True, text=True)
    assert result.stdout == "hello"

Verify before relying

• Whether the plugin works with subprocess.Popen subclasses or only the standard library implementation
• Performance overhead when registering many subprocess calls in a single test suite

Package facts

Evidence: pytest_subprocess-1.6.0-py3-none-any.whl

Tags

More Testing packages