.\" Man page generated from reStructuredText.
.
.TH "PYTEST-MPI" "1" "Mar 20, 2021" "0+unknown" "pytest-mpi"
.SH NAME
pytest-mpi \- pytest-mpi Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
\fIpytest\-mpi\fP provides a number of things to assist with using pytest with
MPI\-using code, specifically:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Displaying of the current MPI configuration (e.g. the MPI version, the
number of processes)
.IP \(bu 2
Sharing temporary files/folders across the MPI processes
.IP \(bu 2
Markers which allow for skipping or xfailing tests based on whether the
tests are being run under MPI
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Further features will be added in the future, and contribution of features is
very much welcomed.
.SH USAGE
.sp
The important thing to remember is that \fIpytest\-mpi\fP assists with running tests
when \fIpytest\fP is run under MPI, rather than launching \fIpytest\fP under MPI. To
actually run the tests under MPI, you will want to run something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ mpirun \-n 2 python \-m pytest \-\-with\-mpi
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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.
.sp
An simple test using the \fImpi\fP marker managed by \fIpytest\-mpi\fP is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import pytest
@pytest.mark.mpi
def test_size():
    from mpi4py import MPI
    comm = MPI.COMM_WORLD
    assert comm.size > 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This test will be automatically be skipped unless \fI\-\-with\-mpi\fP is used. We can
also specify a minimum number of processes required to run the test:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import pytest
@pytest.mark.mpi(min_size=2)
def test_size():
    from mpi4py import MPI
    comm = MPI.COMM_WORLD
    assert comm.size >= 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There are also \fImpi_skip\fP, for when a test should not be run under MPI (e.g. it
causes a lockup or segmentation fault), and \fImpi_xfail\fP, for when a test should
succeed when run normally, but fail when run under MPI.
.SH MARKERS
.INDENT 0.0
.TP
.B pytest.mark.mpi(min_size=None)
Mark that this test must be run under MPI.
.INDENT 7.0
.TP
.B Parameters
\fBmin_size\fP (\fI\%int\fP) \-\- 
.sp
Specify that this test requires at least \fImin_size\fP processes to run. If
there are insufficient processes, skip this test.
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import pytest

@pytest.mark.mpi(minsize=4)
def test_mpi_feature():
    ...
.ft P
.fi
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B pytest.mark.mpi_skip()
Mark that this test should be skipped when run under MPI.
.UNINDENT
.INDENT 0.0
.TP
.B pytest.mark.mpi_xfail()
Mark that this test should be xfailed when run under MPI.
.UNINDENT
.SH FIXTURES
.INDENT 0.0
.TP
.B pytest_mpi.mpi_file_name(tmpdir, request)
Provides a temporary file name which can be used under MPI from all MPI
processes.
.sp
This function avoids the need to ensure that only one process handles the
naming of temporary files.
.UNINDENT
.INDENT 0.0
.TP
.B pytest_mpi.mpi_tmp_path(tmp_path)
Wraps \fIpytest.tmp_path\fP so that it can be used under MPI from all MPI
processes.
.sp
This function avoids the need to ensure that only one process handles the
naming of temporary folders.
.UNINDENT
.INDENT 0.0
.TP
.B pytest_mpi.mpi_tmpdir(tmpdir)
Wraps \fIpytest.tmpdir\fP so that it can be used under MPI from all MPI
processes.
.sp
This function avoids the need to ensure that only one process handles the
naming of temporary folders.
.UNINDENT
.SH CHANGELOG
.SS 0.5
.INDENT 0.0
.IP \(bu 2
No codebase changes, only testing/CI changes needed to support pytest 6.
.IP \(bu 2
We use Azure Pipelines now for CI, rather than Travis
.IP \(bu 2
Autouploads to PyPI are done via Azure Pipelines
.IP \(bu 2
We test on both pytest<6 and pytest>=6, due to the need to support both for
now.
.UNINDENT
.SS 0.4
.INDENT 0.0
.IP \(bu 2
Added license and contributing details
.IP \(bu 2
Added fixtures to enable sharing code across files
.IP \(bu 2
Numerous testing fixes/improvements
.UNINDENT
.SS 0.3
.INDENT 0.0
.IP \(bu 2
Fixed pylint failures
.IP \(bu 2
Added testing of examples in documentation
.IP \(bu 2
Added proper tests
.IP \(bu 2
Fix bugs found via tests
.UNINDENT
.SS 0.2
.INDENT 0.0
.IP \(bu 2
Add proper documentation of features
.IP \(bu 2
Display more MPI related information on test run
.IP \(bu 2
Add \fImpi_skip\fP and \fImpi_xfail\fP markers
.IP \(bu 2
Add \fImpi_tmpdir\fP and \fImpi_tmp_path\fP
.UNINDENT
.SS 0.1.1
.INDENT 0.0
.IP \(bu 2
Fix plugin as the pytest command line parsing logic needs to be outside main
plugin class
.UNINDENT
.SS 0.1
.sp
Initial version
.SH CONTRIBUTING TO PYTEST-MPI
.sp
We welcome contributions to pytest\-mpi, subject to our
\fI\%code of conduct\fP
whether it is improvements to the documentation or examples, bug reports or code
improvements.
.SS Reporting Bugs
.sp
Bugs should be reported to \fI\%https://github.com/aragilar/pytest\-mpi\fP\&. 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.
.SS Patches and Pull Requests
.sp
The main repository is \fI\%https://github.com/aragilar/pytest\-mpi\fP, 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).
.SS Running the tests
.sp
pytest\-mpi uses \fI\%tox\fP to run its tests. See \fI\%https://tox.readthedocs.io/en/latest/\fP
for more information about tox, but the simplest method is to run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
in the top level of the git repository.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you want to run pytest directly, remember to include \fB\-p pytester\fP, as
pytester needs to be manually activated.
.UNINDENT
.UNINDENT
.SS Making a release
.sp
Current minimal working method (this doesn\(aqt produce a release commit, deal
with DOIs needing to be preregistered, not automated, not signed etc.):
.INDENT 0.0
.IP 1. 3
Checkout the latest commit on the \fBmaster\fP branch on the main repository
locally. Ensure the work directory is clean
(\fBgit purge\fP/\fBgit clean \-xfd\fP).
.IP 2. 3
Tag this commit with an annotated tag, with the format being \fBv*.*.*\fP
(\fBgit tag \-a v*.*.*\fP; I should sign these...). The tag should mention the
changes in this release.
.IP 3. 3
Push tag to github.
.IP 4. 3
Create a release on github using the web interface, copying the content of
the tag.
.IP 5. 3
Build sdist and wheel (\fBpython setup.py sdist bdist_wheel\fP), and upload to
PyPI (\fBtwine upload dist/*\fP).
.UNINDENT
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
modindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
James Tocknell
.SH COPYRIGHT
2021, James Tocknell
.\" Generated by docutils manpage writer.
.