Skip to content

pytest.mark.parametrize: Table-Driven Python Tests

  • How @pytest.mark.parametrize turns one test function into one test per case, and why that beats a loop of asserts.
  • How pytest builds test IDs, and how to make them readable with ids= and pytest.param(..., id=...).
  • How to mark a single case (xfail, skip), stack decorators for a cross product, and parametrize a whole class.
  • How indirect=True routes values through a fixture, and how to mix valid and invalid inputs in one table.
  • The pytest 9 changes that matter: keyword-only ids/indirect/scope (9.2), strict duplicate IDs and subtests (9.0).

@pytest.mark.parametrize(argnames, argvalues) runs the decorated test once per entry in argvalues, each as an independent test item with its own ID, result and traceback. It is pytest’s built-in way to write table-driven tests. It is current and stable in pytest 9.2.0 (the latest release on PyPI at the time of writing), which supports Python 3.10 and later.

OrdersPortal charges shipping by subtotal, destination and speed. The obvious first test loops over a table of cases. The samples on this page are pytest test modules: install pytest into a virtual environment (pip install pytest), save the files side by side and run pytest -v in that folder. They were run with pytest 9.2.0 on CPython 3.14.6; header lines and long tracebacks are trimmed from the output.

The module under test has a bug: free shipping should start at 50.00, but the code uses >.

# shipping.py (buggy version)
from decimal import Decimal
FREE_SHIPPING_FROM = Decimal("50.00")
def shipping_fee(subtotal: Decimal, country: str, *, express: bool = False) -> Decimal:
fee = Decimal("0.00") if subtotal > FREE_SHIPPING_FROM else Decimal("4.99") # bug: should be >=
if country != "US":
fee += Decimal("10.00")
if express:
fee += Decimal("15.00")
return fee
# test_shipping_loop.py: before
from decimal import Decimal
from shipping import shipping_fee
CASES = [
(Decimal("20.00"), "US", False, Decimal("4.99")),
(Decimal("50.00"), "US", False, Decimal("0.00")), # exactly at the threshold
(Decimal("50.00"), "DE", False, Decimal("10.00")), # threshold, international
(Decimal("80.00"), "CA", True, Decimal("25.00")),
]
def test_shipping_fee_all_cases():
for subtotal, country, express, expected in CASES:
assert shipping_fee(subtotal, country, express=express) == expected
$ pytest -q test_shipping_loop.py
E AssertionError: assert Decimal('4.99') == Decimal('0.00')
E + where Decimal('4.99') = shipping_fee(Decimal('50.00'), 'US', express=False)
FAILED test_shipping_loop.py::test_shipping_fee_all_cases - AssertionError: a...
1 failed in 0.01s

One test, one failure. The loop stopped at the second row, so you cannot tell whether the third and fourth rows pass. Now the same table, parametrized:

# test_shipping.py: after
from decimal import Decimal
import pytest
from shipping import shipping_fee
@pytest.mark.parametrize(
"subtotal, country, express, expected",
[
(Decimal("20.00"), "US", False, Decimal("4.99")),
(Decimal("50.00"), "US", False, Decimal("0.00")),
(Decimal("50.00"), "DE", False, Decimal("10.00")),
(Decimal("80.00"), "CA", True, Decimal("25.00")),
],
)
def test_shipping_fee(subtotal, country, express, expected):
assert shipping_fee(subtotal, country, express=express) == expected
$ pytest -v --tb=line test_shipping.py
test_shipping.py::test_shipping_fee[subtotal0-US-False-expected0] PASSED [ 25%]
test_shipping.py::test_shipping_fee[subtotal1-US-False-expected1] FAILED [ 50%]
test_shipping.py::test_shipping_fee[subtotal2-DE-False-expected2] FAILED [ 75%]
test_shipping.py::test_shipping_fee[subtotal3-CA-True-expected3] PASSED [100%]
...
E AssertionError: assert Decimal('4.99') == Decimal('0.00')
E AssertionError: assert Decimal('14.99') == Decimal('10.00')
========================= 2 failed, 2 passed in 0.01s ==========================

Every row ran, and the two failures (both “at threshold” rows) point straight at the boundary bug. IDs such as subtotal1 are not useful yet; the realistic example fixes that.

  • Argument names are a comma-separated string ("subtotal, country") or a list or tuple of strings. Each name must be a parameter of the test (or of a fixture, with indirect).
  • Argument values are a list. With several names, each entry is a tuple in the same order. With one name, each entry is the value itself, not a one-element tuple.
  • Collection time. pytest expands the table while collecting, before any test runs. Each case is its own item, selectable by node ID (pytest "test_shipping.py::test_shipping_fee[us-at-threshold]") or -k.
  • Values are passed as is, not copied. If a case holds a list or dict and the test mutates it, later tests see the mutation.
  • Empty tables are skipped by default; the empty_parameter_set_mark option can make them xfail or a collection error.

pytest builds an ID from each value: strings, numbers, booleans, None, enum members and compiled regexes appear as text, and classes and functions appear by __name__; other objects (such as Decimal) fall back to the argument name plus an index. Pass ids= as a list of strings or as a callable that receives each value, or wrap a single case in pytest.param(..., id="...").

test_ids.py
from decimal import Decimal
import pytest
# One argument name: the list holds plain values, not 1-tuples.
@pytest.mark.parametrize("status", ["pending", "paid", "shipped"])
def test_status_is_lowercase(status):
assert status == status.lower()
# Several names: a comma-separated string (or a tuple of strings) and one tuple per case.
@pytest.mark.parametrize(("order_id", "valid"), [("ORD-1001", True), ("ord-1001", False), ("", False)])
def test_order_id_format(order_id, valid):
assert (order_id.startswith("ORD-") and order_id[4:].isdigit()) is valid
# Objects without a readable default ID: pass ids= a list or a callable.
@pytest.mark.parametrize("amount", [Decimal("9.99"), Decimal("0")], ids=str)
def test_amount_not_negative(amount):
assert amount >= 0
# Apply to every test in a class.
@pytest.mark.parametrize("currency", ["USD", "EUR"])
class TestCurrency:
def test_three_letters(self, currency):
assert len(currency) == 3
def test_upper_case(self, currency):
assert currency.isupper()
$ pytest --collect-only -q test_ids.py
test_ids.py::test_status_is_lowercase[pending]
test_ids.py::test_status_is_lowercase[paid]
test_ids.py::test_status_is_lowercase[shipped]
test_ids.py::test_order_id_format[ORD-1001-True]
test_ids.py::test_order_id_format[ord-1001-False]
test_ids.py::test_order_id_format[-False]
test_ids.py::test_amount_not_negative[9.99]
test_ids.py::test_amount_not_negative[0]
test_ids.py::TestCurrency::test_three_letters[USD]
test_ids.py::TestCurrency::test_three_letters[EUR]
test_ids.py::TestCurrency::test_upper_case[USD]
test_ids.py::TestCurrency::test_upper_case[EUR]
12 tests collected in 0.01s

All 12 pass when run. To parametrize every test in a module, assign the mark to a module-level pytestmark variable.

If two cases produce the same ID, pytest appends _0, _1 (test_sku[A-1_0], test_sku[A-1_1]). Since pytest 9.0 the strict_parametrization_ids option (also turned on by strict = true) makes duplicates a collection error that names the duplicate and suggests ids= or pytest.param(id=...). pytest 9.2 added parametrize_long_str_id_strategy for string values longer than 100 characters, which by default now fall back to name plus index.

ids, indirect and scope are keyword-only since pytest 9.2.0. Passing ids as a third positional argument now fails at collection:

E TypeError: Metafunc.parametrize() takes 3 positional arguments but 4 positional arguments (and 1 keyword-only argument) were given

Routing values through a fixture: indirect

Section titled “Routing values through a fixture: indirect”

With indirect=True (or a list of names), pytest hands each value to the fixture of the same name as request.param, and the test receives whatever the fixture returns. Use it when each case needs real setup. Fixtures themselves are covered on the pytest fixtures page.

test_indirect.py
import pytest
@pytest.fixture
def customer(request):
# With indirect=True, each parameter value arrives here as request.param.
tier = request.param
return {"id": f"C-{tier}", "tier": tier, "discount_pct": {"standard": 0, "gold": 10}[tier]}
@pytest.mark.parametrize("customer", ["standard", "gold"], indirect=True)
def test_discount_never_exceeds_cap(customer):
assert 0 <= customer["discount_pct"] <= 10
test_indirect.py::test_discount_never_exceeds_cap[standard] PASSED [ 50%]
test_indirect.py::test_discount_never_exceeds_cap[gold] PASSED [100%]

With the threshold fixed (>=) and input validation added, OrdersPortal’s shipping tests use three parametrize patterns: a named case table with one known-broken case marked xfail, an invariant checked over a grid built by stacking decorators, and one table that mixes valid and invalid input.

# shipping.py (fixed)
from decimal import Decimal
FREE_SHIPPING_FROM = Decimal("50.00")
SUPPORTED_COUNTRIES = {"US", "CA", "DE"}
def shipping_fee(subtotal: Decimal, country: str, *, express: bool = False) -> Decimal:
if subtotal < 0:
raise ValueError("subtotal must not be negative")
if country not in SUPPORTED_COUNTRIES:
raise ValueError(f"unsupported country: {country!r}")
fee = Decimal("0.00") if subtotal >= FREE_SHIPPING_FROM else Decimal("4.99")
if country != "US":
fee += Decimal("10.00")
if express:
fee += Decimal("15.00")
return fee
test_shipping.py
from contextlib import nullcontext as does_not_raise
from decimal import Decimal
import pytest
from shipping import shipping_fee
# 1. A readable case table: each row has an ID that says what it covers.
FEE_CASES = [
pytest.param("20.00", "US", False, "4.99", id="us-below-threshold"),
pytest.param("50.00", "US", False, "0.00", id="us-at-threshold"),
pytest.param("50.00", "DE", False, "10.00", id="de-at-threshold"),
pytest.param("80.00", "CA", True, "25.00", id="ca-express"),
pytest.param(
"60.00", "CA", False, "0.00", id="ca-promo",
marks=pytest.mark.xfail(reason="CA free-shipping promo not built yet", strict=True),
),
]
@pytest.mark.parametrize(("subtotal", "country", "express", "expected"), FEE_CASES)
def test_shipping_fee(subtotal, country, express, expected):
assert shipping_fee(Decimal(subtotal), country, express=express) == Decimal(expected)
# 2. An invariant over a grid: stacked decorators give the cross product (3 x 3 = 9 tests).
@pytest.mark.parametrize("country", ["US", "CA", "DE"])
@pytest.mark.parametrize("subtotal", ["0.00", "49.99", "50.00"])
def test_express_adds_flat_surcharge(subtotal, country):
standard = shipping_fee(Decimal(subtotal), country)
express = shipping_fee(Decimal(subtotal), country, express=True)
assert express - standard == Decimal("15.00")
# 3. Valid and invalid input in one table: the expectation is a context manager.
@pytest.mark.parametrize(
("subtotal", "country", "expectation"),
[
pytest.param("10.00", "US", does_not_raise(), id="valid"),
pytest.param("-1.00", "US", pytest.raises(ValueError, match="negative"), id="negative"),
pytest.param("10.00", "FR", pytest.raises(ValueError, match="unsupported country"), id="fr"),
],
)
def test_input_validation(subtotal, country, expectation):
with expectation:
shipping_fee(Decimal(subtotal), country)
$ pytest -v
test_shipping.py::test_shipping_fee[us-below-threshold] PASSED [ 5%]
test_shipping.py::test_shipping_fee[us-at-threshold] PASSED [ 11%]
test_shipping.py::test_shipping_fee[de-at-threshold] PASSED [ 17%]
test_shipping.py::test_shipping_fee[ca-express] PASSED [ 23%]
test_shipping.py::test_shipping_fee[ca-promo] XFAIL (CA free-shippin...) [ 29%]
test_shipping.py::test_express_adds_flat_surcharge[0.00-US] PASSED [ 35%]
test_shipping.py::test_express_adds_flat_surcharge[0.00-CA] PASSED [ 41%]
test_shipping.py::test_express_adds_flat_surcharge[0.00-DE] PASSED [ 47%]
test_shipping.py::test_express_adds_flat_surcharge[49.99-US] PASSED [ 52%]
test_shipping.py::test_express_adds_flat_surcharge[49.99-CA] PASSED [ 58%]
test_shipping.py::test_express_adds_flat_surcharge[49.99-DE] PASSED [ 64%]
test_shipping.py::test_express_adds_flat_surcharge[50.00-US] PASSED [ 70%]
test_shipping.py::test_express_adds_flat_surcharge[50.00-CA] PASSED [ 76%]
test_shipping.py::test_express_adds_flat_surcharge[50.00-DE] PASSED [ 82%]
test_shipping.py::test_input_validation[valid] PASSED [ 88%]
test_shipping.py::test_input_validation[negative] PASSED [ 94%]
test_shipping.py::test_input_validation[fr] PASSED [100%]
======================== 16 passed, 1 xfailed in 0.03s =========================

Points worth copying:

  • Values are strings in the table and converted in the test, so IDs stay readable.
  • strict=True on the xfail means the day someone builds the promo, the test reports XPASS(strict) as a failure and forces the mark to be removed.
  • The stacked grid tests a property (express always adds 15.00) instead of re-implementing the fee formula in the test.
  • The third table (pytest’s documented “conditional raising” pattern) uses contextlib.nullcontext for rows that must not raise; pytest.raises covers match=. Use it only when valid and invalid rows share the same call.
  • Names and tuples out of order. "country, subtotal" with rows written as (subtotal, country) passes the wrong values silently when the types happen to work. Keep the name string next to the table and use pytest.param IDs.
  • One-element tuples for a single name. With "status", write ["paid", "shipped"]. Writing [("paid",), ...] passes the tuple ("paid",) into the test.
  • Passing ids or indirect positionally. Since pytest 9.2 that is a TypeError at collection; always use keywords.
  • Generators as argvalues. They are exhausted after one pass; pytest 9.1 deprecated them. Pass a list or tuple.
  • Mutating a shared value. Parameter values are not copied. A test that appends to a list parameter changes it for every later test using the same object.
  • Unplanned cross products. Three stacked decorators of 5 values each are 125 tests. Stack only when every combination is meaningful.
  • Branching inside the test. if expected_error: ... else: ... in the body means the table mixes two behaviors. Split it into two tests, or use the nullcontext pattern above.
  • Expensive work at collection. A table built from an API call runs on every collection, including IDE discovery.
Situation Use Why
Same behavior, many input/output rows @pytest.mark.parametrize One body, one result per row
Each row needs setup or teardown parametrize(..., indirect=True) or a parametrized fixture Setup lives in the fixture
Every test using a resource must run against each variant (two databases, two API versions) Fixture with params= All dependent tests are multiplied automatically
Values only known while the test runs Subtests (subtests fixture, pytest 9.0) parametrize needs values at collection time
Different behaviors with different assertions Separate test functions A table with branches hides intent

@pytest.mark.parametrize and pytest.param work in every supported pytest release. Recent changes: ids, indirect and scope became keyword-only in pytest 9.2.0; strict_parametrization_ids, the strict option and built-in subtests arrived in pytest 9.0.0; parametrize_long_str_id_strategy arrived in 9.2.0. pytest 9 requires Python 3.10 or later (9.0.0 dropped Python 3.9).

1. Why is a parametrized test better than a loop of asserts in one test? Each case becomes its own test item. All cases run even when one fails, each has its own ID in the report, and you can rerun a single case by node ID. A loop stops at the first failing assert and hides the rest.

2. What is the difference between indirect=True and a fixture declared with params=? indirect lets one test choose the values and pass them through a fixture as request.param. A fixture with params= owns the values, and every test that requests the fixture is multiplied by them. Use indirect for per-test data and params= for “run the whole suite against each variant”.

3. When are parametrize values evaluated, and why does it matter? At collection time, when the decorator runs and pytest expands the test. Anything slow or stateful in building the table (network calls, reading large files, random data) runs before any test starts and on every collection, and values cannot depend on fixtures. Use subtests or a fixture when values are only known at run time.

4. Senior scenario: OrdersPortal’s tax suite has 4 stacked parametrize decorators (countries, product types, customer tiers, currencies) and takes 20 minutes. How do you cut it down without losing coverage that matters? First measure which combinations exercise different code paths; most of a cross product hits the same branch repeatedly. Replace the grid with an explicit table of boundary and representative rows (pairwise selection works well), keep small grids only for genuine invariants, and give every row an ID. Move expensive setup into a module- or session-scoped fixture so it is not rebuilt per case, enable strict_parametrization_ids to stop duplicate IDs creeping in, and run the full grid in a nightly job if the business still wants it.

  • @pytest.mark.parametrize turns a case table into independent tests that all run and report separately.
  • Give cases readable IDs with pytest.param(..., id=...) or ids=; pytest 9 can make duplicate IDs an error.
  • Mark individual cases with pytest.param(..., marks=...); stack decorators only for meaningful cross products.
  • indirect=True sends values through a fixture; pass ids, indirect and scope by keyword (required since pytest 9.2).
  • Tables are built at collection time; use subtests or fixtures when values are only known at run time.