A convenience wrapper for warnings.catch_warnings() that makes it
easier to test that a warning was correctly raised. It is approximately
equivalent to calling warnings.catch_warnings(record=True) with
warnings.simplefilter() set to always and with the option to
automatically validate the results that are recorded.
check_warnings accepts 2-tuples of the form ("message regexp",
WarningCategory) as positional arguments. If one or more filters are
provided, or if the optional keyword argument quiet is False,
it checks to make sure the warnings are as expected: each specified filter
must match at least one of the warnings raised by the enclosed code or the
test fails, and if any warnings are raised that do not match any of the
specified filters the test fails. To disable the first of these checks,
set quiet to True.
If no arguments are specified, it defaults to:
check_warnings(("", Warning), quiet=True)
In this case all warnings are caught and no errors are raised.
On entry to the context manager, a WarningRecorder instance is
returned. The underlying warnings list from
catch_warnings() is available via the recorder object’s
warnings attribute. As a convenience, the attributes of the object
representing the most recent warning can also be accessed directly through
the recorder object (see example below). If no warning has been raised,
then any of the attributes that would otherwise be expected on an object
representing a warning will return None.
The recorder object also has a reset() method, which clears the
warnings list.
The context manager is designed to be used like this:
with check_warnings(("assertion is always true", SyntaxWarning),
("", UserWarning)):
exec('assert(False, "Hey!")')
warnings.warn(UserWarning("Hide me!"))
In this case if either warning was not raised, or some other warning was
raised, check_warnings() would raise an error.
When a test needs to look more deeply into the warnings, rather than
just checking whether or not they occurred, code like this can be used:
with check_warnings(quiet=True) as w:
warnings.warn("foo")
assert str(w.args[0]) == "foo"
warnings.warn("bar")
assert str(w.args[0]) == "bar"
assert str(w.warnings[0].args[0]) == "foo"
assert str(w.warnings[1].args[0]) == "bar"
w.reset()
assert len(w.warnings) == 0
Here all warnings will be caught, and the test code tests the captured
warnings directly.
Changed in version 2.7: New optional arguments filters and quiet.