Skip to main content

A plugin to fake subprocess for pytest

Project description

PyPI version Python versions See Build Status on Azure Pipelines

A plugin to fake subprocess for pytest


You can install “pytest-subprocess” via pip from PyPI:

$ pip install pytest-subprocess


After plugin installation, the fake_subprocess fixture will become available. Use it to register subprocess results so you won’t need to rely on the real processes. The plugin hooks on the subprocess.Popen(), which is the base for other subprocess functions. That makes the,, subprocess.check_call() and subprocess.check_output() methods also functional.

Basic usage

The most important method is fake_process.register_subprocess() which allows to define the fake processes behavior.

def test_git(fake_process):
        ["git", "branch"], stdout=["* fake_branch", "  master"]

    process = subprocess.Popen(
        ["git", "branch"], stdout=subprocess.PIPE, universal_newlines=True
    out, _ = process.communicate()

    assert process.returncode == 0
    assert out == "* fake_branch\n  master\n"

Unregistered commands

By default, when the fake_process fixture is being used, any attempt to run subprocess that has not been registered will raise the ProcessNotRegisteredError exception. To allow it, use fake_process.allow_unregistered(True), which will execute all unregistered processes with real subprocess, or use fake_process.pass_command("command") to allow just a single command.

def test_real_process(fake_process):
    with pytest.raises(pytest_subprocess.ProcessNotRegisteredError):
        # this will fail, as "ls" command is not registered"ls")

    # now it should be fine
    assert"ls") == 0

    # allow all commands to be called by real subprocess
    assert["ls", "-l"]) == 0

Differing results

Each register_subprocess() or pass_command() method call will register only one command execution. You can call those methods multiple times, to change the faked output on each subprocess run. When you call subprocess more times than registered command, the ProcessNotRegisteredError will be raised. To prevent that, call fake_process.keep_last_process(True), which will keep the last registered process forever.

def test_different_output(fake_process):
    # register process with output changing each execution
    fake_process.register_subprocess("test", stdout="first execution")
    # the second execution will return non-zero exit code
    fake_process.register_subprocess("test", stdout="second execution", returncode=1)

    assert subprocess.check_output("test") == b"first execution\n"
    second_process ="test", stdout=subprocess.PIPE)
    assert second_process.stdout == b"second execution\n"
    assert second_process.returncode == 1

    # 3rd time shall raise an exception
    with pytest.raises(pytest_subprocess.ProcessNotRegisteredError):

    # now, register two processes once again, but the last one will be kept forever
    fake_process.register_subprocess("test", stdout="first execution")
    fake_process.register_subprocess("test", stdout="second execution")

    # now the processes can be called forever
    assert subprocess.check_output("test") == b"first execution\n"
    assert subprocess.check_output("test") == b"second execution\n"
    assert subprocess.check_output("test") == b"second execution\n"
    assert subprocess.check_output("test") == b"second execution\n"

As a context manager

The fake_process fixture provides context() method that allows to use it as a context manager. It can be used to limit the scope when a certain command is allowed, e.g. to make sure that the code doesn’t want to execute it somewhere else.

def test_context_manager(fake_process):
    with pytest.raises(pytest_subprocess.ProcessNotRegisteredError):
        # command not registered, so will raise an exception

    with fake_process.context() as nested_process:
        nested_process.register_subprocess("test", occurrences=3)
        # now, we can call the command 3 times without error
        assert subprocess.check_call("test") == 0
        assert subprocess.check_call("test") == 0

    # the command was called 2 times, so one occurrence left, but since the
    # context manager has been left, it is not registered anymore
    with pytest.raises(pytest_subprocess.ProcessNotRegisteredError):


Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.


Distributed under the terms of the MIT license, “pytest-subprocess” is free and open source software


If you encounter any problems, please file an issue along with a detailed description.

This pytest plugin was generated with Cookiecutter along with @hackebrot’s cookiecutter-pytest-plugin template.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pytest-subprocess, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size pytest_subprocess-0.1.1-py3-none-any.whl (9.7 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pytest-subprocess-0.1.1.tar.gz (10.8 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page