unittest-parametrize 1.5.0

Provide argument names as separate strings

You can provide argument names as a sequence of strings instead:

from unittest_parametrize import parametrize
from unittest_parametrize import ParametrizedTestCase


class SquareTests(ParametrizedTestCase):
    @parametrize(
        ("x", "expected"),
        [
            (1, 1),
            (2, 4),
        ],
    )
    def test_square(self, x: int, expected: int) -> None:
        self.assertEqual(x**2, expected)

Use ParametrizedTestCase in your base test case class

ParametrizedTestCase does nothing if there aren’t any @parametrize-decorated tests within a class. Therefore you can include it in your project’s base test case class so that @parametrize works immediately in all test cases.

For example, within a Django project, you can create a set of project-specific base test case classes extending those provided by Django. You can do this in a module like example.test, and use the base classes throughout your test suite. To add ParametrizedTestCase to all your copies, use it in a custom SimpleTestCase and then mixin to others using multiple inheritance like so:

from django import test
from unittest_parametrize import ParametrizedTestCase


class SimpleTestCase(ParametrizedTestCase, test.SimpleTestCase):
    pass


class TestCase(SimpleTestCase, test.TestCase):
    pass


class TransactionTestCase(SimpleTestCase, test.TransactionTestCase):
    pass


class LiveServerTestCase(SimpleTestCase, test.LiveServerTestCase):
    pass

Custom test name suffixes

By default, test names are extended with an index, starting at zero. You can see these names when running the tests:

$ python -m unittest t.py -v
test_square_0 (t.SquareTests.test_square_0) ... ok
test_square_1 (t.SquareTests.test_square_1) ... ok

----------------------------------------------------------------------
Ran 2 tests in 0.000s

OK

You can customize these names by passing param objects, which contain the arguments and an optional ID for the suffix:

from unittest_parametrize import param
from unittest_parametrize import parametrize
from unittest_parametrize import ParametrizedTestCase


class SquareTests(ParametrizedTestCase):
    @parametrize(
        "x,expected",
        [
            param(1, 1, id="one"),
            param(2, 4, id="two"),
        ],
    )
    def test_square(self, x: int, expected: int) -> None:
        self.assertEqual(x**2, expected)

Yielding perhaps more natural names:

$ python -m unittest t.py -v
test_square_one (t.SquareTests.test_square_one) ... ok
test_square_two (t.SquareTests.test_square_two) ... ok

----------------------------------------------------------------------
Ran 2 tests in 0.000s

OK

Parameter IDs should be valid Python identifier suffixes.

Since parameter IDs are optional, you can provide them only for some tests:

from unittest_parametrize import param
from unittest_parametrize import parametrize
from unittest_parametrize import ParametrizedTestCase


class SquareTests(ParametrizedTestCase):
    @parametrize(
        "x,expected",
        [
            param(1, 1),
            param(20, 400, id="large"),
        ],
    )
    def test_square(self, x: int, expected: int) -> None:
        self.assertEqual(x**2, expected)

ID-free params fall back to the default index suffixes:

$ python -m unittest t.py -v
test_square_0 (example.SquareTests.test_square_0) ... ok
test_square_large (example.SquareTests.test_square_large) ... ok

----------------------------------------------------------------------
Ran 2 tests in 0.000s

OK

Alternatively, you can provide the id’s separately with the ids argument:

from unittest_parametrize import parametrize
from unittest_parametrize import ParametrizedTestCase


class SquareTests(ParametrizedTestCase):
    @parametrize(
        "x,expected",
        [
            (1, 1),
            (2, 4),
        ],
        ids=["one", "two"],
    )
    def test_square(self, x: int, expected: int) -> None:
        self.assertEqual(x**2, expected)

Use with other test decorators

@parametrize tries to ensure it is the top-most (outermost) decorator. This limitation exists to ensure that other decorators apply to each parametrized test. So decorators like @mock.patch need be beneath @parametrize:

from unittest import mock
from unittest_parametrize import parametrize
from unittest_parametrize import ParametrizedTestCase


class CarpentryTests(ParametrizedTestCase):
    @parametrize(
        "nails",
        [(11,), (17,)],
    )
    @mock.patch("example.hammer", autospec=True)
    def test_nail_a_board(self, mock_hammer, nails):
        ...

Also note that due to how mock.patch always adds positional arguments at the start, the parametrized arguments must come last. @parametrize always adds parameters as keyword arguments, so you can also use keyword-only syntax for parametrized arguments:

# ...
def test_nail_a_board(self, mock_hammer, *, nails):
    ...

Multiple @parametrize decorators

@parametrize is not stackable. To create a cross-product of tests, you can use nested list comprehensions:

from unittest_parametrize import parametrize
from unittest_parametrize import ParametrizedTestCase


class RocketTests(ParametrizedTestCase):
    @parametrize(
        "use_ions,hyperdrive_level",
        [
            (use_ions, hyperdrive_level)
            for use_ions in [True, False]
            for hyperdrive_level in [0, 1, 2]
        ],
    )
    def test_takeoff(self, use_ions, hyperdrive_level) -> None:
        ...

The above creates 2 * 3 = 6 versions of test_takeoff.

For larger combinations, itertools.product() may be more readable:

from itertools import product
from unittest_parametrize import parametrize
from unittest_parametrize import ParametrizedTestCase


class RocketTests(ParametrizedTestCase):
    @parametrize(
        "use_ions,hyperdrive_level,nose_colour",
        list(
            product(
                [True, False],
                [0, 1, 2],
                ["red", "yellow"],
            )
        ),
    )
    def test_takeoff(self, use_ions, hyperdrive_level, nose_colour) -> None:
        ...

The above creates 2 * 3 * 2 = 12 versions of test_takeoff.

Parametrizing multiple tests in a test case

@parametrize only works as a function decorator, not a class decorator. To parametrize all tests within a test case, create a separate decorator and apply it to each method:

from unittest_parametrize import parametrize
from unittest_parametrize import ParametrizedTestCase


parametrize_race = parametrize(
    "race",
    [("Human",), ("Halfling",), ("Dwarf",), ("Elf",)],
)


class StatsTests(ParametrizedTestCase):
    @parametrize_race
    def test_strength(self, race: str) -> None:
        ...

    @parametrize_race
    def test_dexterity(self, race: str) -> None:
        ...

    ...

Why not subtests?

TestCase.subTest() is unittest’s built-in “parametrization” solution. You use it in a loop within a single test method:

from unittest import TestCase


class SquareTests(TestCase):
    def test_square(self):
        tests = [
            (1, 1),
            (2, 4),
        ]
        for x, expected in tests:
            with self.subTest(x=x):
                self.assertEqual(x**2, expected)

This approach crams multiple actual tests into one test method, with several consequences:

• If a subtest fails, it prevents the next subtests from running. Thus, failures are harder to debug, since each test run can only give you partial information.

• Subtests can leak state. Without correct isolation, they may not test what they appear to.

• Subtests cannot be reordered by tools that detect state leakage, like pytest-randomly.

• Subtests skew test timings, since the test method runs multiple tests.

• Everything is indented two extra levels for the loop and context manager.

Parametrization avoids all these issues by creating individual test methods.