I love @pytest.mark.parametrize1—so much so that I sometimes shoehorn my tests to fit into it. But the default style of writing tests with parametrize can quickly turn into an unreadable mess as the test complexity grows. For example:

import pytest
from math import atan2


def polarify(x: float, y: float) -> tuple[float, float]:
    r = (x**2 + y**2) ** 0.5
    theta = atan2(y, x)
    return r, theta


@pytest.mark.parametrize(
    "x, y, expected",
    [
        (0, 0, (0, 0)),
        (1, 0, (1, 0)),
        (0, 1, (1, 1.5707963267948966)),
        (1, 1, (2**0.5, 0.7853981633974483)),
        (-1, -1, (2**0.5, -2.356194490192345)),
    ],
)
def test_polarify(x: float, y: float, expected: tuple[float, float]) -> None:
    # pytest.approx helps us ignore floating point discrepancies
    assert polarify(x, y) == pytest.approx(expected)

The polarify function converts Cartesian coordinates to polar coordinates. We’re using @pytest.mark.parametrize in its standard form to test different conditions.

Here, the list of nested tuples with inputs and expected values becomes hard to read as the test suite grows larger. When the function under test has a more complex signature, I find myself needing to do more mental gymnastics to parse the positional input and expected values inside parametrize.

Also, how do you run a specific test case within the suite? For instance, what if you want to run only the third case where x, y, expected = (0, 1, (1, 1.5707963267948966))?

I used to set custom test IDs like below to be able to run individual test cases within parametrize:

# ... polarify implementation hasn't changed.


@pytest.mark.parametrize(
    "x, y, expected",
    [
        (0, 0, (0, 0)),
        (1, 0, (1, 0)),
        (0, 1, (1, 1.5707963267948966)),
        (1, 1, (2**0.5, 0.7853981633974483)),
        (-1, -1, (2**0.5, -2.356194490192345)),
    ],
    ids=[
        "origin",
        "positive_x_axis",
        "positive_y_axis",
        "first_quadrant",
        "third_quadrant",
    ],
)
def test_polarify(x: float, y: float, expected: tuple[float, float]) -> None:
    # pytest.approx helps us ignore floating point discrepancies
    assert polarify(x, y) == pytest.approx(expected)

This works, but mentally associating the IDs with the examples is cumbersome, and it doesn’t make things any easier to read.

TIL, pytest.param2 gives you a better syntax and more control to achieve the same. Observe:

# ... polarify implementation hasn't changed.


@pytest.mark.parametrize(
    "x, y, expected",
    [
        pytest.param(0, 0, (0, 0), id="origin"),
        pytest.param(1, 0, (1, 0), id="positive_x_axis"),
        pytest.param(0, 1, (1, 1.5707963267948966), id="positive_y_axis"),
        pytest.param(1, 1, (2**0.5, 0.7853981633974483), id="first_quadrant"),
        pytest.param(
            -1, -1, (2**0.5, -2.356194490192345), id="third_quadrant"
        ),
    ],
)
def test_polarify(x: float, y: float, expected: tuple[float, float]) -> None:
    # pytest.approx helps us ignore floating point discrepancies
    assert polarify(x, y) == pytest.approx(expected)

We’re setting the unique IDs inside pytest.param. Now, any test can be targeted with pytest’s -k flag like this:

pytest -k positive_x_axis

This will only run the second test case on the list.

Or,

pytest -k 'first or third'

This will run the last two tests.

But the test is still somewhat hard to read. I usually refactor mine to take a kwargs argument so that I can neatly tuck all the input and expected values associated with a test case in a single dictionary. Notice:

# ... polarify implementation hasn't changed.


@pytest.mark.parametrize(
    "kwargs",
    [
        pytest.param({"x": 0, "y": 0, "expected": (0, 0)}, id="origin"),
        pytest.param(
            {"x": 1, "y": 0, "expected": (1, 0)}, id="positive_x_axis"
        ),
        pytest.param(
            {"x": 0, "y": 1, "expected": (1, 1.5707963267948966)},
            id="positive_y_axis",
        ),
        pytest.param(
            {"x": 1, "y": 1, "expected": (2**0.5, 0.7853981633974483)},
            id="first_quadrant",
        ),
        pytest.param(
            {"x": -1, "y": -1, "expected": (2**0.5, -2.356194490192345)},
            id="third_quadrant",
        ),
    ],
)
def test_polarify(kwargs: dict[str, Any]) -> None:
    # Extract expected from kwargs
    expected = kwargs.pop("expected")
    # Unpack the remaining kwargs to the polarify function
    assert polarify(**kwargs) == pytest.approx(expected)

Everything associated with a single test case is passed to pytest.param in a single dictionary, eliminating the need to guess any positional arguments.

Using pytest.param also allows you to set custom test execution conditionals, which I’ve started to take advantage of recently:

# ... polarify implementation hasn't changed.


@pytest.mark.parametrize(
    "kwargs",
    [
        pytest.param(
            {"x": 0, "y": 1, "expected": (1, 1.5707963267948966)},
            id="positive_y_axis",
            marks=pytest.mark.xfail(
                reason="Known issue with atan2 in this quadrant"
            ),
        ),
        pytest.param(
            {"x": 1, "y": 1, "expected": (2**0.5, 0.7853981633974483)},
            id="first_quadrant",
        ),
        pytest.param(
            {
                "x": 1e10,
                "y": 1e10,
                "expected": (2**0.5 * 1e10, 0.7853981633974483),
            },
            id="too_large",
            marks=pytest.mark.skipif(
                lambda kwargs: kwargs["x"] > 1e6 or kwargs["y"] > 1e6,
                reason="Input values are too large",
            ),
        ),
    ],
)
def test_polarify(kwargs: dict[str, Any]) -> None:
    # Extract expected from kwargs
    expected = kwargs.pop("expected")
    # Unpack the remaining kwargs to the polarify function
    assert polarify(**kwargs) == pytest.approx(expected)

In the last block, pytest.param bundles test data with execution conditions. We’re using xfail to mark a test as expected to fail, while skipif skips tests based on conditions. This keeps all the logic for handling test cases, including failures and skips, directly alongside the test data.

  1. pytest.mark.parametrize ↩︎

  2. pytest.param ↩︎

Recent posts