Pytest.raises custom error message

[palaviv]

This PR change pytest.raises to accept custom made message that will be raised if no exception was raised. For example:

with pytest.raises(KeyError, message="I am expecting a KeyError to be raised"):
    pass
Failed: I am expecting a KeyError to be raised

The use case behind this feature is as follows:

for i in random.shuffle(["a", "b", "c"]):
   with pytest.raises(KeyError):
        if i == "b":
            raise KeyError

As you can see in this example I can't know at which input I have failed from the result of the test. The new message will allow me to change the test as follows:

for input in random.shuffle(["a", "b", "c"]):
   with pytest.raises(KeyError, message="Key error was not raised for input {}".format(i)):
        if input == "b":
            raise KeyError

Now I can know the exact input the test failed.

[coveralls]

Coverage increased (+0.003%) to 92.43% when pulling 8ddbca3 on palaviv:pytest.raises-message into 308396a on pytest-dev:features.

[The-Compiler]

accord -> occured

[palaviv]

done

[coveralls]

Coverage increased (+0.003%) to 92.43% when pulling e6ff01a on palaviv:pytest.raises-message into 308396a on pytest-dev:features.

[nicoddemus]

Hey @palaviv, may thanks for the PR!

I see one small issue with it thought: since it now accepts a message keyword argument, in the non-context manager usage, how can we differentiate if the keyword argument is meant to the underlying function or to pytest.raises? For example:

def display_warning(*, code, message):
    if not isinstance(code, int):
        raise TypeError
    if not isinstance(code, str):
        raise TypeError

def test_display_warning():
    pytest.raises(TypeError, display_warning, code=[], message='a warning')
    pytest.raises(TypeError, display_warning, code=123, message=[])    

So pytest.raises will always interpret message as the extra message, never forwarding it to the underlying function, which will be confusing and might break existing code.

I suggest we accept and handle the message keyword argument only in the context manager form... I think it is a valid trade-off.

@The-Compiler and @palaviv, what do you guys think?

[palaviv]

This sounds like a good suggestion.

[nicoddemus]

Please update the docstring to include this new keyword argument support; make sure to mention it is only valid in the context manager form. 😁

[palaviv]

done

[coveralls]

Coverage increased (+0.003%) to 92.43% when pulling ca09367 on palaviv:pytest.raises-message into 308396a on pytest-dev:features.

[coveralls]

Coverage increased (+0.003%) to 92.43% when pulling c29130d on palaviv:pytest.raises-message into 308396a on pytest-dev:features.

[nicoddemus]

Thanks!

One last thing, please add a versionadded directive before this paragraph:

.. versionadded:: 2.10

[palaviv]

shouldn't it be after the paragraph?

[palaviv]

Also wouldn't a versionchanged be more appropriate as the function was changed?

[nicoddemus]

Hmm that's a good question. The other places in pytest documentation which use this feature put it before the paragraph...

You are right, that's how Python's own documentation does it at least. 😁

[nicoddemus]

Also wouldn't a versionchanged be more appropriate as the function was changed?

Good point. I was thinking along the lines of adding a new parameter, but I think your suggestion makes more sense.

[palaviv]

I think then that I should keep with the project conventions. Consistency is more important.

[nicoddemus]

LGTM! @The-Compiler, if you are OK with it feel free to merge it. 😄

[coveralls]

Coverage increased (+0.003%) to 92.43% when pulling f8d4cad on palaviv:pytest.raises-message into 308396a on pytest-dev:features.

[The-Compiler]

costum -> custom, but I'll fix it up when merging

[The-Compiler]

Thanks!