Pytest-unittest.TestCase Support

开源项目
,
1

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;

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

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 <tbreportdemo>{.interpreted-text
    role=“ref”};
  • stdout and stderr <captures>{.interpreted-text role=“ref”}
    capturing;
  • Test selection options <select-tests>{.interpreted-text
    role=“ref”} using -k and -m flags;
  • maxfail{.interpreted-text role=“ref”};
  • --pdb <pdb-option>{.interpreted-text role=“ref”} command-line
    option for debugging on test failures (see
    note <pdb-unittest-note>{.interpreted-text role=“ref”} below);
  • Distribute tests to multiple CPUs using the
    pytest-xdist plugin;
  • Use plain assert-statements <assert>{.interpreted-text role=“ref”}
    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 <mark>{.interpreted-text role=“ref”}:
    skip <skip>{.interpreted-text role=“ref”},
    skipif <skipif>{.interpreted-text role=“ref”},
    xfail <xfail>{.interpreted-text role=“ref”};
  • Auto-use fixtures <mixing-fixtures>{.interpreted-text role=“ref”};

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

  • Fixtures <fixture>{.interpreted-text role=“ref”} (except for
    autouse fixtures, see below <mixing-fixtures>{.interpreted-text
    role=“ref”});
  • Parametrization <parametrize>{.interpreted-text role=“ref”};
  • Custom hooks <writing-plugins>{.interpreted-text role=“ref”};

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 {#mixing-fixtures}

Running your unittest with pytest allows you to use its
fixture mechanism <fixture>{.interpreted-text role=“ref”} 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 <request-context>{.interpreted-text
role=“ref”} 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 re-use 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
platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-0.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 2 items

test_unittest_db.py FF                                               [100%]

___________________________ 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 0xdeadbeef>
E       assert 0

test_unittest_db.py:10: 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 0xdeadbeef>
E       assert 0

test_unittest_db.py:13: AssertionError
FAILED test_unittest_db.py::MyTest::test_method1 - AssertionError: <conft...
FAILED test_unittest_db.py::MyTest::test_method2 - AssertionError: <conft...

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
tmpdir <tmpdir>{.interpreted-text role=“ref”} fixture to delegate the
creation of a per-test temporary directory:

# content of test_unittest_cleandir.py
import pytest
import unittest


class MyTest(unittest.TestCase):
    @pytest.fixture(autouse=True)
    def initdir(self, tmpdir):
        tmpdir.chdir()  # change to pytest-provided temporary directory
        tmpdir.join("samplefile.ini").write("# testdata")

    def test_method(self):
        with open("samplefile.ini") 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}
::: {.title}
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.
:::

::: {#pdb-unittest-note}
::: {.note}
::: {.title}
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.
:::
:::