Metadata-Version: 2.4
Name: pytest-isolate
Version: 0.0.8
Summary: Run pytest tests in isolated subprocesses 
Project-URL: Documentation, https://github.com/gilfree/pytest-isolate#readme
Project-URL: Issues, https://github.com/gilfree/pytest-isolate/issues
Project-URL: Source, https://github.com/gilfree/pytest-isolate
Author-email: gilfree <gilfree@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.7
Requires-Dist: dill
Requires-Dist: filelock
Requires-Dist: pytest
Requires-Dist: tblib
Provides-Extra: gpu
Requires-Dist: pynvml; extra == 'gpu'
Description-Content-Type: text/markdown

# pytest-isolate

[![Python package](https://github.com/gilfree/pytest-isolate/actions/workflows/python-package.yml/badge.svg)](https://github.com/gilfree/pytest-isolate/actions/workflows/python-package.yml)

[![PyPI - Version](https://img.shields.io/pypi/v/pytest-isolate.svg)](https://pypi.org/project/pytest-isolate)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pytest-isolate.svg)](https://pypi.org/project/pytest-isolate)

Isolate each test in a subprocess - pytest forked replacement, based on pytest-forked.

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

## Features

* Run each test in an forked, isolated subprocess
* Captures stdout & stderr of crashing processes
* Add Timeout to a forked test
* Limit memory used by test
* Limit CPU time used by test
* Manage GPU resources with CUDA_VISIBLE_DEVICES
* Plays nice with pytest-xdist
* Shows warnings, even with xdist!
* *Create visual timeline of test execution (isolated or not)*

## Requirements

* pytest

### Optional Dependencies

For GPU resource management:

* pynvml (optional, for automatic GPU detection)

## Installation

You can install "pytest-isolate" via `pip` from `PyPI`

    pip install pytest-isolate

For GPU resource management support:

    pip install pytest-isolate[gpu]

## Usage

    pytest --isolate

To run every test in its own **forked** subprocess.

Or:

    pytest --isolate-timeout 10 --isolate-mem-limit 1000000 --isolate-cpu-limit 10

To set a timeout to every test in addition to forking, and limit to 10 cpu seconds.

Or:

    pytest --timeline

With possible combination of the above, to generate a timeline of test execution. The
timeline can be viewed in chrome://tracing.

> Note:
>
> Since this plugin uses `fork`, it will not work on  operating systems without `fork` support (e.g. Windows).

The flags `--timeout` or `--forked` will also be respected such that `pytest-isolate` is a drop-in replacement forked pytest forked and pytest timeout.

If `pytest-forked` or `pytest-timeout` are installed, then
they will take precedence. Uninstall them to use `pytest-isolate`.

Unlike `pytest-timeout`, timeout in `pytest-isolate` is implemented by forking the test to a separate subprocess, and setting timeout for that subprocess.

### Using the isolate marker

You can use a mark to isolate or time limit the memory and/or cpu usage test:

```python
@pytest.mark.isolate(timeout=10, mem_limit=10**6, cpu_limit=10)
def test_something():
    pass
```

The `isolate` marker can also be used to request gpus for a test on a gpu machine:

```python
# Request 2 GPUs for this test
@pytest.mark.isolate(resources={'gpu': 2})
def test_with_gpus():
    # The test will have CUDA_VISIBLE_DEVICES set to the allocated GPU IDs
    assert len(os.environ.get("CUDA_VISIBLE_DEVICES").split(",")) == 2
```

### Configuration Options

The options can be set in an pytest configuration file, e.g:

```toml
[tool.pytest.ini_options]
isolate_timeout=10
isolate_mem_limit=1000000
isolate_cpu_limit=10
```

## CUDA_VISIBLE_DEVICES Handling

If `CUDA_VISIBLE_DEVICES` is already set when pytest starts, the plugin will respect this setting and only allocate from the GPUs specified there. This works even without pynvml installed.

For example:

* If `CUDA_VISIBLE_DEVICES=0,1,2` is set, tests will only use GPUs 0, 1, and 2.
* If `CUDA_VISIBLE_DEVICES=` is set (empty), no GPUs will be used.

## Contributing

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.

## License

Distributed under the terms of the `MIT`, `pytest-isolate` is free and open source software

## Issues

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