pytest-raises

pytest.plugin的实现，将pytest.raises作为pytest.mark.fixture。

内容

• 特性
• 要求
• 安装
• 用法
  • 可用的标记
  • 标记的限制
  • 可用的参数
  • @pytest.mark.raises 示例
  • @pytest.mark.setup_raises 示例
• 许可证
• 问题

特性

为标记测试添加了使用pytest.mark.raises fixture的功能，其功能与使用with pytest.raises类似

要求

• python 2.7或更高版本
• pytest 2.8.1或更高版本

安装

您可以通过从PyPI使用pip安装"pytest-raises"

$ pip install pytest-raises

用法

使用@pytest.mark.raises或@pytest.mark.setup_raises标记测试将标记测试执行的代码 预期 会引发错误。这与@pytest.mark.xfail不同，它并不意味着测试本身可能会失败，而是表示测试的“通过”条件是代码引发错误。

它将允许引发错误的测试通过。主要用途是断言引发特定类型的错误。

如果测试被标记为@pytest.mark.raises或@pytest.mark.setup_raises并且它在适当的测试阶段没有引发错误，则测试将失败。

可用的标记

此扩展为不同的pytest阶段提供两个标记

• @pytest.mark.raises：用于在pytest_runtest_call阶段标记应引发函数。
  • 此装饰器可以用作with pytest.raises(...)上下文管理器的替代。
• @pytest.mark.setup_raises：用于标记在pytest_runtest_setup阶段应该抛出异常的函数。

标记的限制

1. 任何使用@pytest.mark.setup_raises装饰的测试函数都假定其函数体为空。

   @pytest.mark.setup_raises()
   def test_something():
       pass
   

   这是因为pytest_runtest_call可能仍然会根据抛出的内容执行。因此，测试函数体内的任何代码都可能引起错误（尤其是如果你使用 fixtures，因为 fixture 设置可能不完整）。

   有关更多信息，请参阅@pytest.mark.setup_raises的示例。

2. 由于假定任何使用@pytest.mark.setup_raises装饰的函数体为空，因此不支持同时使用@pytest.mark.raises和@pytest.mark.setup_raises装饰的测试函数。

   此限制的实现细节在_pytest_raises_validation函数中进一步说明。

可用的参数

这两个标记都接受以下可选参数：

• exception=<Some Exception Class>：期望抛出的确切异常class。
• message='some string'：期望在抛出的异常消息中出现的逐字消息。注意，当提供message时，执行检查实际上是message in exception_message。因此可以使用任何子串，但如果消息“过于简单”，可能会得到假阳性。
• match=r'some regular expression'：要匹配抛出异常消息中的正则表达式。注意使用的是re.match而不是re.search。这种行为与with pytest.raises上下文管理器相同。
• match_flags=<regular expression flags>：要与match参数一起使用的正则表达式flags。例如，match_flags=(re.IGNORECASE | re.DOTALL)。不会对指定的标志进行有效性检查，但如果你提供了无效的标志，将在执行匹配时收到错误（因为re模块将无法理解这些标志）。

注意：不得同时提供message和match参数。只能提供一个或另一个。

@pytest.mark.raises 示例

一个非常简单的示例是

import pytest

class SomeException(Exception):
    pass

class AnotherException(Exception):
    pass

@pytest.mark.raises(exception=SomeException)
def test_mark_raises_named():
    raise SomeException('the message')

@pytest.mark.raises()
def test_mark_raises_general():
    raise AnotherException('the message')

使用测试参数化的更有用的示例是

import pytest

class SomeException(Exception):
    pass

class AnotherException(Exception):
    pass

@pytest.mark.parametrize('error', [
    None,
    pytest.param(
        SomeException('the message'),
        marks=pytest.mark.raises(exception=SomeException)
    ),
    pytest.param(
        AnotherException('the message'),
        marks=pytest.mark.raises(exception=AnotherException)
    ),
    pytest.param(
        Exception('the message'),
        marks=pytest.mark.raises()
    )
])
def test_mark_raises_demo(error):
    if error:
        raise error

所有这些测试都通过了。这些示例是此插件的实际测试（精确的测试用例在test_pytest_raises_parametrize_demo测试中）。

@pytest.mark.setup_raises 示例

@pytest.mark.setup_raises装饰器的使用可能不常见，但需要时没有已知的替代方案。考虑以下人为构造的示例，在conftest.py中，我们有以下检查，针对我们关心的某些自定义标记

# in conftest.py
def pytest_runtest_setup(item):
    custom_marker = item.get_closest_marker('custom_marker')
    if custom_marker:
        valid = custom_marker.kwargs.get('valid', True)
        if not valid:
            raise ValueError('custom_marker.valid was False')

并使用此标记的两个测试

import pytest

@pytest.mark.custom_marker(valid=False)
@pytest.mark.setup_raises(
    exception=ValueError, match=r'.*was False$'
)
def test_mark_setup_raises_demo():
    pass

@pytest.mark.custom_marker(valid=True)
def test_all_good():
    pass

此示例在插件的测试中的test_pytest_mark_setup_raises_demo测试用例中。此示例可能有些尴尬，但其想法是你可以使用@pytest.mark.setup_raises来捕获在pytest_runtest_setup阶段出现的预期错误。因此，当我们使用custom_marker和valid=False时，pytest_runtest_setup将按预期抛出异常，但不是当valid=True时。

在现实生活中，@pytest.mark.setup_raises的实用性在于你可能无法完全控制 fixtures 的执行，或者想要对自定义标记或 fixtures 进行压力测试。考虑编写一个装饰器，它自动为给定的测试函数使用一个 fixture，但故意为 fixture 提供无效的参数。

简而言之：在大多数测试框架中，你可能不需要使用@pytest.mark.setup_raises。然而，如果你需要在pytest_runtest_setup阶段验证失败，这是一个非常有价值的工具。

提示：请注意，当使用@pytest.mark.setup_raises时，函数体应该正好是pass。pytest_runtest_setup阶段已经引发错误，意味着测试的设置不完整。除了空的测试函数体pass之外，此扩展不支持其他任何内容。

许可证

根据MIT许可协议分发，"pytest-raises"是免费和开源软件。

问题

如果你遇到任何问题，请提供详细描述并提交问题。