pytest.mark.parametrize: Table-Driven Python Tests
What you’ll learn
Section titled “What you’ll learn”- How
@pytest.mark.parametrizeturns 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=andpytest.param(..., id=...). - How to mark a single case (
xfail,skip), stack decorators for a cross product, and parametrize a whole class. - How
indirect=Trueroutes 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).
Summary
Section titled “Summary”@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.
The problem it solves
Section titled “The problem it solves”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: beforefrom 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.pyE 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.01sOne 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: afterfrom 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.pytest_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.
How it works
Section titled “How it works”- 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, withindirect). - 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_markoption can make themxfailor a collection error.
Test IDs
Section titled “Test IDs”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="...").
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.pytest_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.01sAll 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.
Keyword-only options (pytest 9.2)
Section titled “Keyword-only options (pytest 9.2)”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 givenRouting 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.
import pytest
@pytest.fixturedef 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"] <= 10test_indirect.py::test_discount_never_exceeds_cap[standard] PASSED [ 50%]test_indirect.py::test_discount_never_exceeds_cap[gold] PASSED [100%]Realistic example
Section titled “Realistic example”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 feefrom contextlib import nullcontext as does_not_raisefrom 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 -vtest_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=Trueon thexfailmeans the day someone builds the promo, the test reportsXPASS(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.nullcontextfor rows that must not raise; pytest.raises coversmatch=. Use it only when valid and invalid rows share the same call.
Common mistakes
Section titled “Common mistakes”- 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 usepytest.paramIDs. - One-element tuples for a single name. With
"status", write["paid", "shipped"]. Writing[("paid",), ...]passes the tuple("paid",)into the test. - Passing
idsorindirectpositionally. Since pytest 9.2 that is aTypeErrorat 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 thenullcontextpattern above. - Expensive work at collection. A table built from an API call runs on every collection, including IDE discovery.
When to use it and when not to
Section titled “When to use it and when not to”| 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 |
Compatibility
Section titled “Compatibility”@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).
Interview questions
Section titled “Interview questions”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.
Key takeaways
Section titled “Key takeaways”@pytest.mark.parametrizeturns a case table into independent tests that all run and report separately.- Give cases readable IDs with
pytest.param(..., id=...)orids=; pytest 9 can make duplicate IDs an error. - Mark individual cases with
pytest.param(..., marks=...); stack decorators only for meaningful cross products. indirect=Truesends values through a fixture; passids,indirectandscopeby keyword (required since pytest 9.2).- Tables are built at collection time; use subtests or fixtures when values are only known at run time.
Related pages
Section titled “Related pages”- pytest fixtures:
request.param, parametrized fixtures and scopes. - pytest.raises: asserting exceptions,
match=and exception groups. - unittest.mock.patch: replacing dependencies in parametrized tests.
- Context managers: why
nullcontext()andpytest.raises()are interchangeable in a table. - Python tools: installing and running pytest alongside other tools.