Metadata-Version: 2.4
Name: pytest-jobserver
Version: 1.1.0
Summary: Limit parallel tests with posix jobserver.
Home-page: https://github.com/tommilligan/pytest-jobserver
Author: Tom Milligan
Author-email: code@tommilligan.net
Maintainer: Tom Milligan
Maintainer-email: code@tommilligan.net
License: Apache Software License 2.0
Keywords: pytest jobserver posix make cargo limit cap parallel limit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# pytest-jobserver

[![PyPI version](https://img.shields.io/pypi/v/pytest-jobserver.svg)](https://pypi.org/project/pytest-jobserver)
[![Python versions](https://img.shields.io/pypi/pyversions/pytest-jobserver.svg)](https://pypi.org/project/pytest-jobserver)
[![Code coverage](https://codecov.io/gh/tommilligan/pytest-jobserver/branch/master/graph/badge.svg)](https://codecov.io/gh/tommilligan/pytest-jobserver/branch/master)
[![Build status](https://img.shields.io/circleci/project/github/tommilligan/pytest-jobserver/master.svg)](https://circleci.com/gh/tommilligan/pytest-jobserver)

Limit parallel tests with posix jobserver.

## Installation

Install with pip:

```bash
pip install pytest-jobserver
```

The plugin officially supports Python `>= 3.6` on a Linux OS.
You may find other Python 3 versions/MacOS work as well.

## Usage

The plugin uses a [POSIX jobserver](https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html) to manage parallel test loading.

Pass the `--jobserver` argument with a path, where this path points to a named pipe acting as a jobserver.
You should probably also use `pytest-xdist` to enable parallelism in the first place:

```bash
pytest -n4 --jobserver /opt/jobserver
```

You can also pass this filepath via the `PYTEST_JOBSERVER` environment variable.

### `make`

The plugin can also listen for an existing jobserver as created by `make`.
If a jobserver is not configured by filepath, `pytest-jobserver` will check the following environment variables in order:

- `CARGO_MAKEFLAGS`
- `MAKEFLAGS`
- `MFLAGS`

**Please note:** it is not possible to use one of these environment variables with `pytest-xdist`. The `execnet` protocol used by `xdist` does not support passing file descriptors to remote child processes.

## Implementation

This plugin [wraps pytest's call to `pytest_runtest_protocol`](https://docs.pytest.org/en/latest/reference.html#_pytest.hookspec.pytest_runtest_protocol), which is called to actually run a collected item on the worker node.

## Development

See the top level `Makefile` and `.circleci/config.yml` for the development flow. But in essence:

- `make dev` to install deps
- `make lint` to lint code (will change files)
- `make test` to run lint/unit tests
- `make integrate` to run integration tests

### Release

Maintainers can cut a new release by pushing a `vX.Y.Z` tag to the repo.
