Asserting with the assert statement{#assert with the assert statement}{#assertfeedback} {#assert}
pytest allows you to use the standard python assert for verifying
expectations and values in Python tests. For example, you can write the
following:
# content of test_assert1.py
def f():
return 3
def test_function():
to assert that your function returns a certain value. If this assertion
fails you will see the return value of the function call:
$ pytest test_assert1.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 1 item
test_assert1.py F [100%]
______________________________ test_function _______________________________
def test_function():
E + where 3 = f()
test_assert1.py:6: AssertionError
pytest has support for showing the values of the most common
subexpressions including calls, attributes, comparisons, and binary and
unary operators. (See tbreportdemo{.interpreted-text role=“ref”}).
This allows you to use the idiomatic python constructs without
boilerplate code while not losing introspection information.
However, if you specify a message with the assertion like this:
then no assertion introspection takes places at all and the message will
be simply shown in the traceback.
See assert-details{.interpreted-text role=“ref”} for more information
on assertion introspection.
Assertions about expected exceptions {#assertraises}
In order to write assertions about raised exceptions, you can use
pytest.raises{.interpreted-text role=“func”} as a context manager like
this:
import pytest
def test_zero_division():
with pytest.raises(ZeroDivisionError):
1 / 0
and if you need to have access to the actual exception info you may use:
def test_recursion_depth():
with pytest.raises(RuntimeError) as excinfo:
def f():
f()
f()
assert "maximum recursion" in str(excinfo.value)
excinfo is an ExceptionInfo instance, which is a wrapper around the
actual exception raised. The main attributes of interest are .type,
.value and .traceback.
You can pass a match keyword parameter to the context-manager to test
that a regular expression matches on the string representation of an
exception (similar to the TestCase.assertRaisesRegexp method from
unittest):
import pytest
def myfunc():
raise ValueError("Exception 123 raised")
def test_match():
with pytest.raises(ValueError, match=r".* 123 .*"):
myfunc()
The regexp parameter of the match method is matched with the
re.search function, so in the above example match='123' would have
worked as well.
There's an alternate form of the pytest.raises{.interpreted-text
role=“func”} function where you pass a function that will be executed
with the given *args and **kwargs and assert that the given
exception is raised:
pytest.raises(ExpectedException, func, *args, **kwargs)
The reporter will provide you with helpful output in case of failures
such as no exception or wrong exception.
Note that it is also possible to specify a "raises" argument to
pytest.mark.xfail, which checks that the test is failing in a more
specific way than just having any exception raised:
@pytest.mark.xfail(raises=IndexError)
def test_f():
f()
Using pytest.raises{.interpreted-text role=“func”} is likely to be
better for cases where you are testing exceptions your own code is
deliberately raising, whereas using @pytest.mark.xfail with a check
function is probably better for something like documenting unfixed bugs
(where the test describes what "should" happen) or bugs in
dependencies.
Assertions about expected warnings {#assertwarns}
You can check that code raises a particular warning using
pytest.warns <warns>{.interpreted-text role=“ref”}.
Making use of context-sensitive comparisons {#newreport}
pytest has rich support for providing context-sensitive information
when it encounters comparisons. For example:
# content of test_assert2.py
def test_set_comparison():
set1 = set("1308")
set2 = set("8035")
if you run this module:
$ pytest test_assert2.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 1 item
test_assert2.py F [100%]
___________________________ test_set_comparison ____________________________
def test_set_comparison():
set1 = set("1308")
set2 = set("8035")
E Extra items in the left set:
E '1'
E Extra items in the right set:
E '5'
E Use -v to get the full diff
test_assert2.py:6: AssertionError
FAILED test_assert2.py::test_set_comparison - AssertionError: assert {'0'...
Special comparisons are done for a number of cases:
- comparing long strings: a context diff is shown
- comparing long sequences: first failing indices
- comparing dicts: different entries
See the reporting demo <tbreportdemo>{.interpreted-text role=“ref”}
for many more examples.
Defining your own explanation for failed assertions
It is possible to add your own detailed explanations by implementing the
pytest_assertrepr_compare hook.
::: {.autofunction noindex=“”}
_pytest.hookspec.pytest_assertrepr_compare
:::
As an example consider adding the following hook in a
conftest.py <conftest.py>{.interpreted-text role=“ref”} file which
provides an alternative explanation for Foo objects:
# content of conftest.py
from test_foocompare import Foo
def pytest_assertrepr_compare(op, left, right):
return [
"Comparing Foo instances:",
" vals: {} != {}".format(left.val, right.val),
]
now, given this test module:
# content of test_foocompare.py
class Foo:
def __init__(self, val):
self.val = val
def __eq__(self, other):
def test_compare():
f1 = Foo(1)
f2 = Foo(2)
you can run the test module and get the custom output defined in the
conftest file:
$ pytest -q test_foocompare.py
F [100%]
_______________________________ test_compare _______________________________
def test_compare():
f1 = Foo(1)
f2 = Foo(2)
E assert Comparing Foo instances:
E vals: 1 != 2
test_foocompare.py:12: AssertionError
FAILED test_foocompare.py::test_compare - assert Comparing Foo instances:
1 failed in 0.12s
Assertion introspection details{#assert-details} {#assert introspection}
Reporting details about a failing assertion is achieved by rewriting
assert statements before they are run. Rewritten assert statements put
introspection information into the assertion failure message. pytest
only rewrites test modules directly discovered by its test collection
process, so asserts in supporting modules which are not themselves
test modules will not be rewritten.
You can manually enable assertion rewriting for an imported module by
calling
register_assert_rewrite
before you import it (a good place to do that is in your root
conftest.py).
For further information, Benjamin Peterson wrote up Behind the scenes
of pytest's new assertion
rewriting.
Assertion rewriting caches files on disk
pytest will write back the rewritten modules to disk for caching. You
can disable this behavior (for example to avoid leaving stale .pyc
files around in projects that move files around a lot) by adding this to
the top of your conftest.py file:
import sys
sys.dont_write_bytecode = True
Note that you still get the benefits of assertion introspection, the
only change is that the .pyc files won't be cached on disk.
Additionally, rewriting will silently skip caching if it cannot write
new .pyc files, i.e. in a read-only filesystem or a zipfile.
Disabling assert rewriting
pytest rewrites test modules on import by using an import hook to
write new pyc files. Most of the time this works transparently.
However, if you are working with the import machinery yourself, the
import hook may interfere.
If this is the case you have two options:
- Disable rewriting for a specific module by adding the string
PYTEST_DONT_REWRITEto its docstring. - Disable rewriting for all modules by using
--assert=plain.