pytest-mpi

0.6 verified Mon Apr 27 auth: no python

pytest-mpi is a pytest plugin that provides fixtures and markers for tests requiring MPI (Message Passing Interface) support, enabling parallel test execution across multiple processes. Version 0.6 is the latest, with infrequent releases.

pip install pytest-mpi

Common errors

error ModuleNotFoundError: No module named 'pytest_mpi' ↓

cause The plugin is not installed or the import path is wrong.

fix

Run 'pip install pytest-mpi' and ensure you import from 'pytest_mpi' (underscore, not dot).

error pytest: error: unrecognized arguments: --mpi ↓

cause pytest-mpi is not installed or the plugin is not activated.

fix

Install pytest-mpi: pip install pytest-mpi. Also check that you are running pytest with the plugin enabled; it should auto-register.

error ValueError: The MPI library failed to initialize ↓

cause MPI runtime (e.g., OpenMPI, MPICH) is not installed or not configured correctly.

fix

Install an MPI implementation (e.g., 'sudo apt install openmpi-bin' on Ubuntu) and ensure 'mpirun' is in PATH.

Warnings

gotcha The @mpi_skip decorator must be placed before @pytest.mark.parametrize to avoid skipping incorrectly. ↓

fix Always put @mpi_skip as the outermost decorator (right above def).

deprecated The 'mpi' fixture may return a different MPI communicator object in future versions; currently it returns the MPI.COMM_WORLD. ↓

fix Use mpi fixture directly; check version changelogs for changes.

breaking pytest-mpi 0.5 removed support for MPI_Gather and MPI_Allgather fixtures; use mpi_skip with custom MPI calls instead. ↓

fix Replace @mpi_gather and @mpi_allgather with @mpi_skip and manual MPI calls.

Imports

mpi_skip
wrong
```
from pytest.mpi import mpi_skip
```
correct
```
from pytest_mpi import mpi_skip
```
Common mistake: using 'pytest.mpi' instead of 'pytest_mpi'.
mpi
wrong
```
from pytest import mpi
```
correct
```
from pytest_mpi import mpi
```
The fixture 'mpi' is provided by the plugin, not by pytest itself.

Quickstart

Simple test using mpi fixture and mpi_skip decorator.

import pytest
from pytest_mpi import mpi_skip

@mpi_skip(reason="Requires MPI")
def test_mpi_example(mpi):
    rank = mpi.Get_rank()
    size = mpi.Get_size()
    assert size > 0
    print(f"Hello from rank {rank} out of {size}")

# Run with: mpirun -n 4 pytest -v test_mpi.py