Dict form for parametrize -- shorthand for stacked decorators

[youtux]

Proposal: dict form for parametrize as shorthand for stacked decorators

Summary

Allow pytest.mark.parametrize to accept a dict[str, Sequence], where each key is a parameter name and each value is the list of values for that parameter. The result is the cartesian product of all value lists — identical to stacking multiple @pytest.mark.parametrize decorators.

# Current
@pytest.mark.parametrize("author__first_name", ["Alice", "Bob"])
@pytest.mark.parametrize("author__last_name", ["Smith"])
@pytest.mark.parametrize("author__role", ["admin", "reader"])
def test_publish(author):
    ...

# Proposed
@pytest.mark.parametrize({
    "author__first_name": ["Alice", "Bob"],
    "author__last_name": ["Smith"],
    "author__role": ["admin", "reader"],
})
def test_publish(author):
    ...

Purely syntactic sugar. No new behaviour.

Motivation

Codebases that use declarative fixture overrides — most notably through pytest-factoryboy — routinely parametrise many attributes on the same test. A complex scenario can easily accumulate 10+ stacked decorators:

@pytest.mark.parametrize("author__first_name", ["Alice", "Bob"])
@pytest.mark.parametrize("author__last_name", ["Smith"])
@pytest.mark.parametrize("author__role", ["admin", "reader"])
@pytest.mark.parametrize("author__country", ["UK"])
@pytest.mark.parametrize("author__is_active", [True])
@pytest.mark.parametrize("second_author__first_name", ["Charlie"])
@pytest.mark.parametrize("second_author__last_name", ["Jones"])
@pytest.mark.parametrize("second_author__role", ["reader"])
@pytest.mark.parametrize("second_author__country", ["US", "DE"])
@pytest.mark.parametrize("second_author__is_active", [True, False])
def test_publish(author, second_author):
    ...

Where does author end and second_author begin? You have to read every line to find out.

The existing multi-argument form groups parameters into one decorator, but separates names from values:

@pytest.mark.parametrize(
    [
        "author__first_name",
        "author__last_name",
        "author__role",
        "author__country",
        "author__is_active",
    ],
    [
        (
            "Alice",
            "Smith",
            "admin",
            "UK",
            True,
        ),
    ],
)
@pytest.mark.parametrize(
    [
        "second_author__first_name",
        "second_author__last_name",
        "second_author__role",
        "second_author__country",
        "second_author__is_active",
    ],
    [
        (
            "Charlie",
            "Jones",
            "reader",
            "US",
            True,
        ),
    ],
)
def test_publish(author, second_author):
    ...

The names and values are in two separate lists — you have to count positions and mentally match the 5th value to the 5th name. This is error-prone, and it only expresses zipped combinations — not a cartesian product.

Neither form scales well when a test parametrises multiple fixtures.

The dict form solves both problems

@pytest.mark.parametrize({
    "author__first_name": ["Alice", "Bob"],
    "author__last_name": ["Smith"],
    "author__role": ["admin", "reader"],
    "author__country": ["UK"],
    "author__is_active": [True],
})
@pytest.mark.parametrize({
    "second_author__first_name": ["Charlie"],
    "second_author__last_name": ["Jones"],
    "second_author__role": ["reader"],
    "second_author__country": ["US", "DE"],
    "second_author__is_active": [True, False],
})
def test_publish(author, second_author):
    ...

• Each parameter name sits right next to its values — no positional counting.
• The two fixtures are visually grouped into two distinct blocks.
• The cartesian product is expressed declaratively, without enumerating combinations by hand.
• Adding or removing a parameter is a one-line change.

Semantics

The dict is expanded into multiple stacked parametrize calls internally — one per key. Ordering follows dict insertion order (Python 3.7+): first key varies slowest, last key varies fastest. Stacking two dict-form decorators works exactly like stacking two regular ones.

Relationship to prior proposals

• #7568 — list of dicts as argvalues (each dict is one test case). Different shape: it changes how values are passed, not how parameters are declared.
• #2855 — keyword-args form (params(x=[1,2], y=[3,4])). Closest in spirit, but introduced a new decorator. Was rejected and became the pytest-parametrized plugin. The dict form proposed here works within the existing pytest.mark.parametrize API — no new decorator, no new concept to learn.
• #5487, #10518 — dict keys as test IDs. Different goal entirely.

Open questions

These can be deferred if the core idea is of interest:

• indirect — could accept a list of keys to pass through as fixtures.
• ids — auto-generated IDs would combine values across keys, same as stacked decorators do today.
• pytest.param() — values in the lists could be pytest.param(...) for attaching marks or custom IDs.
• scope — could be passed as a keyword argument.

Implementation sketch

A dict is expanded into multiple parametrize calls — one per key. This can be done in 6 lines at the top of Metafunc.parametrize(), before any existing logic runs:

# _pytest/python.py

class Metafunc:
    ...

    def parametrize(self, argnames, argvalues=None, *, indirect=False, ids=None, scope=None, ...):
        # Dict form: expand into one parametrize call per key (cartesian product).
        if isinstance(argnames, dict):
            for name, values in argnames.items():
                self.parametrize(name, values, indirect=indirect, scope=scope)
            return

        # ... existing implementation unchanged ...

No changes to test collection, reporting, or node IDs — the expansion happens before any of that machinery runs.

[RonnyPfannschmidt]

1. This must use a new name
2. This targets factoryboy factories im not. Comfortable with putting a experiment for its configuration into core