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 on it.

Install

pytest-subprocess on PyPI

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"

Package facts

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

Tags

More Testing packages

See also pytest-console-scripts · pytest-forked · pytest-responses · EasyProcess · scripttest · pytest-mock · pytest-depends · pytest_httpserver · pytest-httpx2 · pytest-reportportal