Meaning
Decorates a test function to run it multiple times with different argument sets, treating each combination as a distinct test case. It addresses the pain point of duplicating test logic for different inputs and expected outputs. Reach for it when you need to verify a function's behavior across a matrix of inputs.
Primary Function
Test parameterization
Communicative Purpose
Enables running the same test logic against multiple input-output pairs without duplicating code.
Pattern
@pytest.mark.parametrize(argnames, argvalues, ids=test_ids)
Core Structure
@pytest.mark.parametrize(..., ..., ids=...)
Função primária
Test parameterization
Propósito comunicativo
Enables running the same test logic against multiple input-output pairs without duplicating code.
Situações de gatilho
Unit testing: validating a function against a matrix of inputs and expected outputs. Data-driven testing: running the same assertion logic with varying datasets. Test suite maintenance: reducing duplicated test functions that only differ in test data.
Contextos
pytest, Python testing, automated test suites, data-driven testing
Padrão
@pytest.mark.parametrize(argnames, argvalues, ids=test_ids)
Estrutura central
@pytest.mark.parametrize(..., ..., ids=...)
Slots de substituição
argnames: comma-separated string of parameter names, argvalues: list of tuples or list of values, test_ids: list of string identifiers for each case
Colocados típicos
- pytest.fixture
- assert
- pytest.raises
- pytest.mark.xfail
Substituições comuns
- pytest_generate_tests: dynamic parameterization at collection time (more complex but flexible for large data sets). unittest.TestCase.subTest: standard library alternative (less declarative
- no separate test IDs).
Erros comuns
Mismatching the number of names in argnames and values in argvalues tuples: causes ValueError at collection time. Forgetting to import pytest: causes NameError. Using mutable objects in argvalues without proper isolation: leads to shared state between test runs. Passing argnames as separate strings instead of a comma-separated string: causes incorrect parameter binding.
Similar / contraste
pytest.fixture (setup/teardown, not data-driven), unittest.TestCase.subTest (imperative subtests, not separate test items), hypothesis (property-based, not example-based)
Interferências
Coming from unittest: may try to use loops with assert inside a single test — parametrize creates separate test items that are reported independently.
Família do chunk
- pytest.mark.parametrize
- pytest.fixture
- pytest.mark.xfail
- pytest.mark.skipif
Nuance
When NOT to use: when test cases require entirely different setup logic, not just different inputs. Performance: large argvalues lists can slow down test collection time. Boundary condition: ids must match the length of argvalues, or be a callable, otherwise pytest raises an error.
Efeito pragmático
Provides granular pass/fail reporting per input case, preventing one bad input from masking the success of others.
Dica de memória
Like a vending machine button panel: one test function, but it runs once for every snack (data point) you select.
Nota
argnames can also be passed as a list of strings instead of a comma-separated string.
Upgrade path
pytest_generate_tests for dynamic parameterization based on external data or command-line options.
Log in to save chunks.