PYTEST-MPI(7)

💖 NAME 💖

okay so pytest-mpi — hear me out bestie, this is the pytest-mpi Documentation and it's literally your new fave.

pytest-mpi is a lil toolkit that helps you use pytest with your MPI-using code. More specifically, it gives you:

• displaying of the current MPI configuration ✨ (like, the MPI version, the number of processes, all of it)
• sharing temporary files/folders across the MPI processes 🎀
• markers that let you skip or xfail tests depending on whether they're being run under MPI

and fr fr, more features are coming in the future, and contributions of features are very much welcomed 🫶

---

🌸 USAGE 🌸

The one thing you gotta remember, no cap: pytest-mpi assists with running tests when pytest is run under MPI — it does not launch pytest under MPI for you. So to actually run the tests under MPI, you're gonna run something like:

$ mpirun -n 2 python -m pytest --with-mpi

heads up bestie: by default the MPI tests are not run — and honestly that's the vibe, because it means you can run the non-MPI parts of a test suite without ever worrying about installing MPI and mpi4py 💅

Here's a simple little test using the mpi marker, all managed by pytest-mpi:

import pytest
@pytest.mark.mpi
def test_size():
    from mpi4py import MPI
    comm = MPI.COMM_WORLD
    assert comm.size > 0

This test will automatically be skipped unless --with-mpi is used. iconic behaviour honestly.

And you 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's also mpi_skip, for when a test should not be run under MPI (like, say, it causes a lockup or a segmentation fault 😭 — do not run that one bestie), 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. periodt.

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. (iykyk — that coordination is a whole thing and this just handles it 💅)

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's improvements to the documentation or examples, bug reports, or code improvements. all of it, we want it 🫶

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 🌈

2019, James Tocknell

---

and that's the whole page bestie 💖 this was version 0.6, dated Sep 03, 2025, and you're all caught up. slay, go run some MPI tests 🧚✨