From 8b34d981fc378f06b65d0866e6bd2c66d29680b3 Mon Sep 17 00:00:00 2001 From: Peter Schutt Date: Tue, 7 May 2019 09:56:13 +1000 Subject: [PATCH] Clarify docs for pytest.raises `match`. For #5208. Document explicit behavior of `match` and brief note on how to handle matching a string that may contain special re chars. --- src/_pytest/python_api.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/_pytest/python_api.py b/src/_pytest/python_api.py index 84fffd7aa..ae466a063 100644 --- a/src/_pytest/python_api.py +++ b/src/_pytest/python_api.py @@ -558,7 +558,13 @@ def raises(expected_exception, *args, **kwargs): Assert that a code block/function call raises ``expected_exception`` or raise a failure exception otherwise. - :kwparam match: if specified, asserts that the exception matches a text or regex + :kwparam match: if specified, a string containing a regular expression, + or a regular expression object, that is tested against the string + representation of the exception using ``re.match``. To match a literal + string that may contain ``special characters``__, the pattern can + first be escaped with ``re.escape``. + + __ https://docs.python.org/3/library/re.html#regular-expression-syntax :kwparam message: **(deprecated since 4.1)** if specified, provides a custom failure message if the exception is not raised. See :ref:`the deprecation docs ` for a workaround.