Pytest Parametrize: Data-Driven Tests, Custom IDs, and the Cartesian Trap

Most Python test suites start clean. Then someone needs to check an edge case, so they copy a test function and change one number. Then another edge case appears. Six months later you have forty near-identical functions where a single input change means editing forty places. The useful takeaway: @pytest.mark.parametrize replaces that duplication with generated test cases, but only if you control how those cases are named and how many combinations you create.

How parametrize turns one function into many test nodes

Pytest collects tests before it runs them. When it encounters @pytest.mark.parametrize, it reads the parameter names and the iterable of values, then creates a separate test node for each entry. A node is simply a single runnable test case with its own name and outcome.

Here is a minimal example. Save it as test_math.py in your project root:

import pytest

@pytest.mark.parametrize("a, b, expected", [
    (2, 3, 5),
    (10, -4, 6),
    (0, 0, 0),
])
def test_add(a, b, expected):
    assert a + b == expected

Run pytest --collect-only from your terminal (no special permissions required). You should see three nodes instead of one function. The default generated names look like test_add[2-3-5], test_add[10--4-6], and test_add[0-0-0]. If you use pytest-xdist and pass an unpicklable object as a parameter value, collection can fail because workers receive serialized data.

Naming cases so they are selectable

Default IDs are mechanical. They work, but they are hard to read in verbose output and impossible to target with -k expressions. The ids argument or pytest.param lets you attach a human-readable label and optional marks to each case.

@pytest.mark.parametrize("value, expected", [
    pytest.param(1, True, id="positive"),
    pytest.param(-1, False, id="negative"),
    pytest.param(0, False, marks=pytest.mark.xfail, id="zero-boundary"),
])
def test_is_positive(value, expected):
    assert (value > 0) == expected

Run pytest -v and you will see test_is_positive[positive], test_is_positive[negative], and test_is_positive[zero-boundary]. You can then run a single case with pytest -k positive. One limitation: custom IDs must be unique. If two cases share an ID, pytest raises a collection error before any test executes.

The Cartesian trap and fixture interaction

Parametrize is most valuable when it varies one behavior dimension. Stacking multiple decorators creates a Cartesian product—every value from the first decorator is paired with every value from the second.

@pytest.mark.parametrize("x", [1, 2])
@pytest.mark.parametrize("y", ["a", "b"])
def test_xy(x, y):
    assert f"{x}{y}"

This generates four nodes, not two. Three stacked decorators with five values each produce 125 nodes. The count grows multiplicatively, and a suite that once ran in seconds can silently become slow. When you need multiple dimensions, prefer a single decorator with tuple arguments or pytest.param so the combinations are explicit.

Fixtures interact orthogonally. A parametrized test can still request a fixture, and a fixture can itself be parametrized:

@pytest.fixture(params=["local", "staging"])
def env(request):
    return request.param

@pytest.mark.parametrize("path", ["/health", "/ready"])
def test_endpoint(env, path):
    assert client(env).get(path).status_code == 200

Here the fixture contributes two values and the test contributes two, yielding four nodes. That is usually what you want, but it compounds the same multiplication risk.

A second limitation: mutable parameter values such as lists or dictionaries are shared across test nodes. If a test mutates its input, later cases may see the modified object. Use immutable data or copy the value inside the test.

Check the result before you trust it

Before you commit a parametrized suite, run pytest --co -q from your project root. This lists every generated node without executing the tests. Scan the output: if the count is far larger than the number of meaningful scenarios you intended, you have a Cartesian explosion. If the names are unreadable, add ids or pytest.param labels. If any node name is duplicated, fix the ID collision first. Parametrize is a tool for clarity, not just volume—use it to replace copy-paste, not to multiply it.