From f18780ed8af9692264d239238617bfaafd5cdf0e Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Wed, 16 Aug 2017 14:28:34 -0300 Subject: [PATCH] Update docs: ``match`` keyword was introduced in 3.1 Also update the text to recommend using the context-manager over the callable/string forms. --- _pytest/python_api.py | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/_pytest/python_api.py b/_pytest/python_api.py index 457d30a10..b73e0457c 100644 --- a/_pytest/python_api.py +++ b/_pytest/python_api.py @@ -493,7 +493,8 @@ def raises(expected_exception, *args, **kwargs): ... >>> assert exc_info.type == ValueError - Or you can use the keyword argument ``match`` to assert that the + + Since version ``3.1`` you can use the keyword argument ``match`` to assert that the exception matches a text or regex:: >>> with raises(ValueError, match='must be 0 or None'): @@ -502,7 +503,12 @@ def raises(expected_exception, *args, **kwargs): >>> with raises(ValueError, match=r'must be \d+$'): ... raise ValueError("value must be 42") - Or you can specify a callable by passing a to-be-called lambda:: + **Legacy forms** + + The forms below are fully supported but are discouraged for new code because the + context manager form is regarded as more readable and less error-prone. + + It is possible to specify a callable by passing a to-be-called lambda:: >>> raises(ZeroDivisionError, lambda: 1/0) @@ -516,11 +522,14 @@ def raises(expected_exception, *args, **kwargs): >>> raises(ZeroDivisionError, f, x=0) - A third possibility is to use a string to be executed:: + It is also possible to pass a string to be evaluated at runtime:: >>> raises(ZeroDivisionError, "f(0)") + The string will be evaluated using the same ``locals()`` and ``globals()`` + at the moment of the ``raises`` call. + .. autoclass:: _pytest._code.ExceptionInfo :members: