# Welcome to pytest-xprocess’s documentation!

A pytest plugin for managing processes. It will make sure external processes on which your application depends are up during every pytest run without the need of manual start-up.

## Quickstart

Install plugin via `pip`:

    $ pip install pytest-xprocess

Define your process fixture in `conftest.py`:

    # content of conftest.py

    import pytest
    from xprocess import ProcessStarter

    @pytest.fixture
    def myserver(xprocess):
        class Starter(ProcessStarter):
            # startup pattern
            pattern = "PATTERN"

            # command to start process
            args = ['command', 'arg1', 'arg2']

        # ensure process is running and return its logfile
        logfile = xprocess.ensure("myserver", Starter)

        conn = # create a connection or url/port info to the server
        yield conn

        # clean up whole process tree afterwards
        xprocess.getinfo("myserver").terminate()

Now you can use this fixture in any test functions where `myserver` needs to be up and `xprocess` will take care of it for you!

- Starter Class
  - Matching process output with `pattern`
  - Controlling Startup Wait Time with `timeout`
  - Customizing process initialization with `popen_kwargs`
  - Automatic clean-up with `terminate_on_interrupt`
  - Limiting number of lines searched for pattern with `max_read_lines`
  - Making sure your process is ready with `startup_check`
  - Customizing process execution environment with `env`
  - Overriding Wait Behavior
  - An Important Note Regarding Stream Buffering
- Info Object
  - Terminating Processes and Process Trees
  - Checking a Process Status
- Command Line Options
  - Listing Long-running Processes with `--xshow`
  - Terminating Long-running Processes with `--xkill`
- How to contribute
  - How to report issues
  - Setting up your development environment
  - Start Coding
  - How to run tests
  - Checking Test Coverage
- Changes
  - 0.22.2 (2023-01-05)
  - 0.21.0 (2022-11-27)
  - 0.20.0 (2022-08-29)
  - 0.19.0 (2022-05-23)
  - 0.18.1 (2021-07-27)
  - 0.18.0 (2021-07-21)
  - 0.17.1 (2021-02-28)
  - 0.17.0 (2020-11-26)
  - 0.16.0 (2020-10-29)
  - 0.15.0 (2020-10-03)
  - 0.14.0 (2020-09-24)
  - 0.13.1 (2020-01-29)
  - 0.13.0 (UNRELEASED)
  - 0.12.1 (2017-06-07)
  - 0.12.0 (2017-06-06)
  - 0.11.1 (2017-05-31)
  - 0.11 (2017-05-18)
  - 0.10 (2017-05-15)
  - 0.9.1 (2015-07-15)
  - 0.9 (2015-07-15)
  - 0.8.0 (2013-10-04)
  - 0.7.0 (2013-04-05)
- Contact Channels