Skip to main content

Pytest plugin for testing console scripts

Project description

See Build Status on Travis CI

Pytest-console-scripts is a Pytest plugin for testing python scripts installed via console_scripts entry point of It can run the scripts under test in a separate process or using the interpreter that’s running the test suite. The former mode ensures that the script will run in an environment that is identical to normal execution whereas the latter one allows much quicker test runs during development while simulating the real runs as much as possible.


  • Python 2.7 or 3.4+, or PyPy,
  • Pytest 3.0 or newer.


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

$ pip install pytest-console-scripts


Imagine we have a python package foo with the following

        'console_scripts': ['foobar=foo:bar']

We could use pytest-console-scripts to test the foobar script:

def test_foo_bar(script_runner):
    ret ='foobar', '--version')
    assert ret.success
    # just for example, let's assume that foobar --version
    # should output 3.2.1
    assert ret.stdout == '3.2.1\n'
    assert ret.stderr == ''

This would use the script_runner fixture provided by the plugin to run the script and capture it’s output.

The arguments of are the command name of the script and any command line arguments that should be passed to it. Additionally the following keyword arguments can be used:

  • cwd - set the working directory of the script under test.
  • stdin - a file-like object that will be piped to standard input of the script.

Configuring script execution mode

In the example above the foobar script would run in in-process mode. This is fast and good for quick iteration during development. After we’re happy with the functionality, it’s time to run the script in subprocess mode to simulate real invocation more closely. There are several ways to do this. We can configure it via pytest configuration (for example in tox.ini):

script_launch_mode = subprocess

We can give a command line option to pytest (this will override the configuration file):

$ py.test --script-launch-mode=subprocess

We can also mark individual tests to run in a specific mode:

def test_foobar(script_runner):

Between these three methods the marking of the tests has priority before the command line option that in turn overrides the configuration setting. All three can take three possible values: “inprocess” (which is the default), “subprocess”, and “both” (which will cause the test to be run twice: in inprocess and in subprocess modes).


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-console-scripts” is free and open source software.


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

Pytest-console-scripts was initially 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.

Filename, size & hash SHA256 hash help File type Python version Upload date
pytest-console-scripts-0.1.8.tar.gz (9.2 kB) Copy SHA256 hash SHA256 Source None

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