Provided by: python-pytest-mpi-doc_0.6-3_all 
NAME
pytest-mpi - pytest-mpi Documentation
pytest-mpi provides a number of things to assist with using pytest with MPI-using code,
specifically:
• Displaying of the current MPI configuration (e.g. the MPI version, the number of
processes)
• Sharing temporary files/folders across the MPI processes
• Markers which allow for skipping or xfailing tests based on whether the tests are
being run under MPI
Further features will be added in the future, and contribution of features is very much
welcomed.
USAGE
The important thing to remember is that pytest-mpi assists with running tests when pytest
is run under MPI, rather than launching pytest under MPI. To actually run the tests under
MPI, you will want to run something like:
$ mpirun -n 2 python -m pytest --with-mpi
Note that by default the MPI tests are not run—this makes it easy to run the non-MPI parts
of a test suite without having to worry about installing MPI and mpi4py.
An simple test using the mpi marker managed by pytest-mpi is:
import pytest
@pytest.mark.mpi
def test_size():
from mpi4py import MPI
comm = MPI.COMM_WORLD
assert comm.size > 0
This test will be automatically be skipped unless --with-mpi is used. We can also specify
a minimum number of processes required to run the test:
import pytest
@pytest.mark.mpi(min_size=2)
def test_size():
from mpi4py import MPI
comm = MPI.COMM_WORLD
assert comm.size >= 2
There are also mpi_skip, for when a test should not be run under MPI (e.g. it causes a
lockup or segmentation fault), and mpi_xfail, for when a test should succeed when run
normally, but fail when run under MPI.
MARKERS
pytest.mark.mpi(min_size=None)
Mark that this test must be run under MPI.
Parameters
min_size (int) --
Specify that this test requires at least min_size processes to run. If there
are insufficient processes, skip this test.
For example:
import pytest
@pytest.mark.mpi(minsize=4)
def test_mpi_feature():
...
pytest.mark.mpi_skip()
Mark that this test should be skipped when run under MPI.
pytest.mark.mpi_xfail()
Mark that this test should be xfailed when run under MPI.
FIXTURES
pytest_mpi.mpi_file_name(tmpdir, request)
Provides a temporary file name which can be used under MPI from all MPI processes.
This function avoids the need to ensure that only one process handles the naming of
temporary files.
pytest_mpi.mpi_tmp_path(tmp_path)
Wraps pytest.tmp_path so that it can be used under MPI from all MPI processes.
This function avoids the need to ensure that only one process handles the naming of
temporary folders.
pytest_mpi.mpi_tmpdir(tmpdir)
Wraps pytest.tmpdir so that it can be used under MPI from all MPI processes.
This function avoids the need to ensure that only one process handles the naming of
temporary folders.
CHANGELOG
0.6
• Again no codebase changes, testing/CI and packaging fixes only.
• Update Azure Pipelines to use latest images (so CI runs again)
• Update versioneer to work on future Python versions.
• Fix doctests infrastructure
0.5
• No codebase changes, only testing/CI changes needed to support pytest 6.
• We use Azure Pipelines now for CI, rather than Travis
• Autouploads to PyPI are done via Azure Pipelines
• We test on both pytest<6 and pytest>=6, due to the need to support both for now.
0.4
• Added license and contributing details
• Added fixtures to enable sharing code across files
• Numerous testing fixes/improvements
0.3
• Fixed pylint failures
• Added testing of examples in documentation
• Added proper tests
• Fix bugs found via tests
0.2
• Add proper documentation of features
• Display more MPI related information on test run
• Add mpi_skip and mpi_xfail markers
• Add mpi_tmpdir and mpi_tmp_path
0.1.1
• Fix plugin as the pytest command line parsing logic needs to be outside main plugin
class
0.1
Initial version
CONTRIBUTING TO PYTEST-MPI
We welcome contributions to pytest-mpi, subject to our code of conduct whether it is
improvements to the documentation or examples, bug reports or code improvements.
Reporting Bugs
Bugs should be reported to https://github.com/aragilar/pytest-mpi. Please include what
version of Python this occurs on, as well as which operating system. Information about
your h5py and HDF5 configuration is also helpful.
Patches and Pull Requests
The main repository is https://github.com/aragilar/pytest-mpi, please make pull requests
against that repository, and the branch that pull requests should be made on is master
(backporting fixes will be done separately if necessary).
Running the tests
pytest-mpi uses tox to run its tests. See https://tox.readthedocs.io/en/latest/ for more
information about tox, but the simplest method is to run:
tox
in the top level of the git repository.
NOTE:
If you want to run pytest directly, remember to include -p pytester, as pytester needs
to be manually activated.
Making a release
Current minimal working method (this doesn't produce a release commit, deal with DOIs
needing to be preregistered, not automated, not signed etc.):
1. Checkout the latest commit on the master branch on the main repository locally. Ensure
the work directory is clean (git purge/git clean -xfd).
2. Tag this commit with an annotated tag, with the format being v*.*.* (git tag -a
v*.*.*; I should sign these...). The tag should mention the changes in this release.
3. Push tag to github.
4. Create a release on github using the web interface, copying the content of the tag.
5. Build sdist and wheel (python setup.py sdist bdist_wheel), and upload to PyPI (twine
upload dist/*).
• Index
• Module Index
• Search Page
AUTHOR
James Tocknell
COPYRIGHT
2022, James Tocknell