Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# How to use `unittest`-based tests with pytest

`pytest` supports running Python `unittest`-based tests out of the box. It's meant for leveraging existing `unittest`-based test suites to use pytest as a test runner and also allow to incrementally adapt the test suite to take full advantage of pytest's features.

To run an existing `unittest`-style test suite using `pytest`, type:

    pytest tests

pytest will automatically collect `unittest.TestCase` subclasses and their `test` methods in `test_*.py` or `*_test.py` files.

Almost all `unittest` features are supported:

- `@unittest.skip` style decorators;

- `setUp/tearDown`;

- `setUpClass/tearDownClass`;

- `setUpModule/tearDownModule`;

Additionally, subtests are supported by the pytest-subtests plugin.

Up to this point pytest does not have support for the following features:

- load_tests protocol;

## Benefits out of the box

By running your test suite with pytest you can make use of several features, in most cases without having to modify existing code:

- Obtain more informative tracebacks;

- stdout and stderr capturing;

- Test selection options using `-k` and `-m` flags;

- Stopping after the first (or N) failures;

- --pdb command-line option for debugging on test failures (see note below);

- Distribute tests to multiple CPUs using the pytest-xdist plugin;

- Use plain assert-statements instead of `self.assert*` functions (unittest2pytest is immensely helpful in this);

## pytest features in `unittest.TestCase` subclasses

The following pytest features work in `unittest.TestCase` subclasses:

- Marks: skip, skipif, xfail;

- Auto-use fixtures;

The following pytest features do not work, and probably never will due to different design philosophies:

- Fixtures (except for `autouse` fixtures, see below);

- Parametrization;

- Custom hooks;

Third party plugins may or may not work well, depending on the plugin and the test suite.

## Mixing pytest fixtures into `unittest.TestCase` subclasses using marks

Running your unittest with `pytest` allows you to use its fixture mechanism with `unittest.TestCase` style tests. Assuming you have at least skimmed the pytest fixture features, let's jump-start into an example that integrates a pytest `db_class` fixture, setting up a class-cached database object, and then reference it from a unittest-style test:

    # content of conftest.py

    # we define a fixture function below and it will be "used" by
    # referencing its name from tests

    import pytest

    @pytest.fixture(scope="class")
    def db_class(request):
        class DummyDB:
            pass

        # set a class attribute on the invoking test context
        request.cls.db = DummyDB()

This defines a fixture function `db_class` which - if used - is called once for each test class and which sets the class-level `db` attribute to a `DummyDB` instance. The fixture function achieves this by receiving a special `request` object which gives access to the requesting test context such as the `cls` attribute, denoting the class from which the fixture is used. This architecture de-couples fixture writing from actual test code and allows reuse of the fixture by a minimal reference, the fixture name. So let's write an actual `unittest.TestCase` class using our fixture definition:

    # content of test_unittest_db.py

    import unittest

    import pytest

    @pytest.mark.usefixtures("db_class")
    class MyTest(unittest.TestCase):
        def test_method1(self):
            assert hasattr(self, "db")
            assert 0, self.db  # fail for demo purposes

        def test_method2(self):
            assert 0, self.db  # fail for demo purposes

The `@pytest.mark.usefixtures("db_class")` class-decorator makes sure that the pytest fixture function `db_class` is called once per class. Due to the deliberately failing assert statements, we can take a look at the `self.db` values in the traceback:

    $ pytest test_unittest_db.py
    =========================== test session starts ============================
    platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y
    rootdir: /home/sweet/project
    collected 2 items

    test_unittest_db.py FF                                               [100%]

    ================================= FAILURES =================================
    ___________________________ MyTest.test_method1 ____________________________

    self = <test_unittest_db.MyTest testMethod=test_method1>

        def test_method1(self):
            assert hasattr(self, "db")
    >       assert 0, self.db  # fail for demo purposes
    E       AssertionError: <conftest.db_class.<locals>.DummyDB object at 0xdeadbeef0001>
    E       assert 0

    test_unittest_db.py:11: AssertionError
    ___________________________ MyTest.test_method2 ____________________________

    self = <test_unittest_db.MyTest testMethod=test_method2>

        def test_method2(self):
    >       assert 0, self.db  # fail for demo purposes
    E       AssertionError: <conftest.db_class.<locals>.DummyDB object at 0xdeadbeef0001>
    E       assert 0

    test_unittest_db.py:14: AssertionError
    ========================= short test summary info ==========================
    FAILED test_unittest_db.py::MyTest::test_method1 - AssertionError: <conft...
    FAILED test_unittest_db.py::MyTest::test_method2 - AssertionError: <conft...
    ============================ 2 failed in 0.12s =============================

This default pytest traceback shows that the two test methods share the same `self.db` instance which was our intention when writing the class-scoped fixture function above.

## Using autouse fixtures and accessing other fixtures

Although it's usually better to explicitly declare use of fixtures you need for a given test, you may sometimes want to have fixtures that are automatically used in a given context. After all, the traditional style of unittest-setup mandates the use of this implicit fixture writing and chances are, you are used to it or like it.

You can flag fixture functions with `@pytest.fixture(autouse=True)` and define the fixture function in the context where you want it used. Let's look at an `initdir` fixture which makes all test methods of a `TestCase` class execute in a temporary directory with a pre-initialized `samplefile.ini`. Our `initdir` fixture itself uses the pytest builtin `tmp_path` fixture to delegate the creation of a per-test temporary directory:

    # content of test_unittest_cleandir.py
    import unittest

    import pytest

    class MyTest(unittest.TestCase):
        @pytest.fixture(autouse=True)
        def initdir(self, tmp_path, monkeypatch):
            monkeypatch.chdir(tmp_path)  # change to pytest-provided temporary directory
            tmp_path.joinpath("samplefile.ini").write_text("# testdata", encoding="utf-8")

        def test_method(self):
            with open("samplefile.ini", encoding="utf-8") as f:
                s = f.read()
            assert "testdata" in s

Due to the `autouse` flag the `initdir` fixture function will be used for all methods of the class where it is defined. This is a shortcut for using a `@pytest.mark.usefixtures("initdir")` marker on the class like in the previous example.

Running this test module ...:

    $ pytest -q test_unittest_cleandir.py
    .                                                                    [100%]
    1 passed in 0.12s

... gives us one passed test because the `initdir` fixture function was executed ahead of the `test_method`.

Note

`unittest.TestCase` methods cannot directly receive fixture arguments as implementing that is likely to inflict on the ability to run general unittest.TestCase test suites.

The above `usefixtures` and `autouse` examples should help to mix in pytest fixtures into unittest suites.

You can also gradually move away from subclassing from `unittest.TestCase` to plain asserts and then start to benefit from the full pytest feature set step by step.

Note

Due to architectural differences between the two frameworks, setup and teardown for `unittest`-based tests is performed during the `call` phase of testing instead of in `pytest`'s standard `setup` and `teardown` stages. This can be important to understand in some situations, particularly when reasoning about errors. For example, if a `unittest`-based suite exhibits errors during setup, `pytest` will report no errors during its `setup` phase and will instead raise the error during `call`.