pytest03 The writing and reporting of assertions in tests

Posted on 2019-06-16 In 技术 , pytest Views: Word count in article: 8.9k Reading time ≈ 8 mins.

断言，pytest.raises，pytest.mark.xfail，pytest_assertrepr_compare，断言自省详细信息，禁用断言重写

Asserting with the `assert` statement

断言 assert 陈述

pytest 允许你使用标准的python assert 用于验证Python测试中的期望和值。例如，可以编写以下内容：

# content of test_assert1.py
def f():
    return 3

def test_function():
    assert f() == 4

断言函数会返回某个值。如果此断言失败，你将看到函数调用的返回值：

$ pytest test_assert1.py
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 1 item

test_assert1.py F                                                    [100%]

================================= FAILURES =================================
______________________________ test_function _______________________________

    def test_function():
>       assert f() == 4
E       assert 3 == 4
E        +  where 3 = f()

test_assert1.py:5: AssertionError
========================= 1 failed in 0.12 seconds =========================

pytest 支持显示最常见的子表达式的值，包括调用、属性、比较以及二进制和一元运算符。（见用pytest演示python失败报告）这允许你在不丢失自省信息的情况下使用不带样板代码的惯用python构造。

但是，如果使用如下断言指定消息：

1	assert a % 2 == 0, "value was odd, should be even"

这样根本不进行断言内省，消息将简单地显示在追溯中。

Assertions about expected exceptions

关于预期异常的断言

为了编写有关引发的异常的断言，可以使用 pytest.raises 作为这样的上下文管理器：

import pytest

def test_zero_division():
    with pytest.raises(ZeroDivisionError):
        1 / 0

如果你需要访问实际的异常信息，可以使用：

def test_recursion_depth():
    with pytest.raises(RuntimeError) as excinfo:
        def f():
            f()
        f()
    assert 'maximum recursion' in str(excinfo.value)

excinfo 是一个 ExceptionInfo 实例，它是引发的实际异常的包装。感兴趣的主要特征是 .type ， .value 和 .traceback .

你可以通过给上下文管理器传递一个match关键字参数，用于测试正则表达式是否匹配异常的字符串表示形式（类似于 unittest 中的 TestCase.assertRaisesRegexp 方法）：

import pytest

def f():
    raise ValueError("Exception 123 raised")

def test_match():
    with pytest.raises(ValueError, match=r'.* 123 .*'):
        myfunc()

match 方法的regexp参数与 re.search 函数相同，因此在上面的示例中 match='123' 也会起作用的。

在这个例子中，test_match 使用 pytest.raises 来检查 f() 是否抛出了 ValueError。
如果 f() 抛出了 ValueError，测试通过。
如果 f() 没有抛出任何异常，测试失败。
如果 f() 抛出了其他异常，测试失败。

有另一种形式的 pytest.raises 函数，其中传递的函数将用给定的 *args 和 **kwargs 并断言引发了给定的异常：

1	pytest.raises(ExpectedException, func, args, *kwargs)

如果出现故障，如 no exception or wrong exception ，这份报告将为你提供有益的输出。

请注意，也可以将“引发”参数指定为 pytest.mark.xfail ，它检查测试是否以比引发任何异常更具体的方式失败。

pytest.mark.xfail 是一个标记，用于标记一个测试函数，表示这个测试预计会失败。如果测试确实失败了，那么 pytest 会报告这个测试为“xfail”（预期失败），而不是失败。
使用 pytest.raises 对于测试自己代码中故意引发的异常的情况，可能会更好。而使用 @pytest.mark.xfail 使用check函数可能更适合记录未修复的错误（测试描述了“应该”发生的情况）或依赖项中的错误。

举例：

1
2
3

@pytest.mark.xfail(raises=IndexError)
def test_f():
    f()

在这个例子中，test_f 被标记为 xfail，并且预期 f() 会抛出 IndexError 异常。
如果 f() 抛出了 IndexError，测试会被标记为“xfail”。
如果 f() 没有抛出任何异常，测试会被标记为“xpass”（意外通过）。
如果 f() 抛出了其他异常，测试会被标记为“failed”。

假设你有一个函数 process_data，在处理某些数据时会抛出 ValueError，但你知道这是一个已知的问题，尚未修复：

def process_data(data):
    if not data:
        raise ValueError("Data cannot be empty")
    # 处理数据的逻辑
    return data

@pytest.mark.xfail(raises=ValueError)
def test_process_data():
    process_data([])

python -m pytest .\test_xfail.py
============================================================================== test session starts =============================================================================== 
platform win32 -- Python 3.12.0, pytest-7.0.1, pluggy-1.0.0
rootdir: D:\Developer\pytest_learning\pytest\3.The writing and reporting of assertions in tests
plugins: allure-pytest-2.9.43, Faker-13.3.0, assume-2.4.3
collected 1 item                                                                                                                                                                   

test_xfail.py x                                                                                                                                                             [100%] 

=============================================================================== 1 xfailed in 0.12s ===============================================================================

在这个测试中，test_process_data 被标记为 xfail，并且预期 process_data([]) 会抛出 ValueError。如果 process_data([]) 抛出了 ValueError，测试会被标记为“xfail”。如果 process_data([]) 没有抛出任何异常，测试会被标记为“xpass”。

使用场景：

**pytest.raises**：适用于测试你自己代码中故意引发的异常的情况。例如，你有一个函数在某些条件下会抛出特定的异常，你希望确保这些异常被正确抛出。
**@pytest.mark.xfail**：更适合记录未修复的错误（测试描述了“应该”发生的情况）或依赖项中的错误。例如，你知道某个测试在当前环境下会失败，但你希望在未来修复这个问题后，测试能够通过。如果是 process_data(1)，这个用例就会执行成功。

Making use of context-sensitive comparisons

利用上下文相关的比较

当遇到比较时pytest 对提供上下文敏感信息具有丰富的支持。例如：

# content of test_assert2.py

def test_set_comparison():
    set1 = set("1308")
    set2 = set("8035")
    assert set1 == set2

运行此模块：

$ pytest test_assert2.py
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 1 item

test_assert2.py F                                                    [100%]

================================= FAILURES =================================
___________________________ test_set_comparison ____________________________

    def test_set_comparison():
        set1 = set("1308")
        set2 = set("8035")
>       assert set1 == set2
E       AssertionError: assert {'0', '1', '3', '8'} == {'0', '3', '5', '8'}
E         Extra items in the left set:
E         '1'
E         Extra items in the right set:
E         '5'
E         Use -v to get the full diff

test_assert2.py:5: AssertionError
========================= 1 failed in 0.12 seconds =========================

对一些情况进行特殊比较：

比较长字符串：显示文本差异
比较长序列：第一个失败下标
比较字典：不同的条目

Defining your own explanation for failed assertions

为失败的断言定义自己的解释

可以通过执行 pytest_assertrepr_compare 钩子来增加自己细节解释。

pytest_assertrepr_compare(config, op, left, right)

返回失败的断言表达式中比较解释。如果没有自定义解释，则返回“None”，否则返回字符串列表。字符串将由换行符联接，但任何字符串中的换行符将被转义。请注意，除了第一行之外，其他所有行都将略微缩进，目的是为了将第一行作为摘要。

例如，考虑在 conftest.py 中增加如下的钩子，来为Foo对象提供替代解释：

# content of conftest.py
from test_foocompare import Foo
def pytest_assertrepr_compare(op, left, right):
    if isinstance(left, Foo) and isinstance(right, Foo) and op == "==":
        return ['Comparing Foo instances:',
                '   vals: %s != %s' % (left.val, right.val)]

现在，假设这个测试模块：

# content of test_foocompare.py
class Foo(object):
    def __init__(self, val):
        self.val = val

    def __eq__(self, other):
        return self.val == other.val

def test_compare():
    f1 = Foo(1)
    f2 = Foo(2)
    assert f1 == f2

你可以运行测试模块并在conftest文件中定义自定义输出：

$ pytest -q test_foocompare.py
F                                                                    [100%]
================================= FAILURES =================================
_______________________________ test_compare _______________________________

    def test_compare():
        f1 = Foo(1)
        f2 = Foo(2)
>       assert f1 == f2
E       assert Comparing Foo instances:
E            vals: 1 != 2

test_foocompare.py:11: AssertionError
1 failed in 0.12 seconds

Assertion introspection details

断言自省详细信息

通过在运行断言语句之前重写它们，可以获得有关失败断言的报告详细信息。重写的断言语句将自省信息放入断言失败消息中。 pytest 只重写由其测试收集过程直接发现的测试模块，因此 支持模块中的断言（本身不是测试模块）将不会被重写 .

你可以手动使能断言，为一个导入的模块重写，这个模块在导入前通过register_assert_rewrite调用。（一个很好的地方是在您的根目录中 conftest.py ）

示例

假设你有一个支持模块 utils.py，其中包含一些辅助函数，并且你在测试模块中使用了这些函数。

1
2
3

# utils.py
def check_positive(num):
    assert num > 0, "Number must be positive"

# test_utils.py
import pytest
from utils import check_positive

def test_check_positive():
    check_positive(10)  # 应该通过
    check_positive(-1)  # 应该失败

默认行为

默认情况下，pytest 不会重写 utils.py 中的断言，因此 test_check_positive 失败时，你只会看到一个简单的 AssertionError，而不会看到详细的自省信息，部分如下：

test_utils.py:3 (test_check_positive)
def test_check_positive():
        check_positive(10)  # 应该通过
>       check_positive(-1)  # 应该失败

test_utils.py:6: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

num = -1

    def check_positive(num):
>       assert num > 0, "Number must be positive"
E       AssertionError: Number must be positive

..\..\utils\__init__.py:2: AssertionError

手动启用断言重写

为了在 utils.py 中启用断言的重写，你可以在 conftest.py 中调用 pytest.register_assert_rewrite。

# conftest.py
import pytest

def pytest_configure(config):
    pytest.register_assert_rewrite('utils')

运行测试

现在，当你运行 pytest 时，utils.py 中的断言也会被重写，你将获得详细的自省信息：

test_utils.py:3 (test_check_positive)
-1 != 0

Expected :0
Actual   :-1
<Click to see difference>

def test_check_positive():
        check_positive(10)  # 应该通过
>       check_positive(-1)  # 应该失败

总结

断言自省：pytest 通过重写断言语句来提供详细的错误信息。
默认行为：pytest 只重写测试模块中的断言。
手动启用：通过 pytest.register_assert_rewrite 可以在支持模块中启用断言的重写。
最佳实践：在 conftest.py 中调用 pytest.register_assert_rewrite 来注册需要重写的模块。

Assertion rewriting caches files on disk

断言重写将文件缓存在磁盘上

pytest 会将重写的模块写回磁盘进行缓存（可以提高后续测试运行的性能，因为不需要每次都重新编译和重写模块）。

可以通过设置 sys.dont_write_bytecode = True，来禁用 .pyc 文件的缓存。

例如，为了避免在经常移动文件的项目中留下过时的.pyc文件。在一些项目中，文件经常被移动或重命名。如果 pytest 将重写后的模块缓存到磁盘上，可能会导致旧的 .pyc 文件残留，从而引起问题，比如重命名重跑用例会有意想不到的问题。禁用缓存可以避免这种情况。

1
2
3

import sys

sys.dont_write_bytecode = True

请注意，你仍然可以获得断言内省的好处，唯一的变化是 .pyc 文件不会缓存在磁盘上。

此外，如果重写无法写入新的 .pyc 文件，它将自动跳过缓存，即只读文件系统或压缩文件中的文件。

Disabling assert rewriting

禁用断言重写

pytest 通过使用导入钩子hook的方式写入新的 pyc 文件夹，在导入时重写测试模块。大多数时候这是透明的。但是，如果你自己操作导入机制，导入钩子可能会产生干扰。假设你有一个项目，其中包含自定义的导入机制。在这种情况下，pytest 的断言重写机制可能会干扰你的自定义导入。

如果是这种情况，你有两个选择：

通过添加字符串PYTEST_DONT_REWRITE 到它的docstring，禁用特定模块的重写。
通过使用 --assert=plain ，禁用所有模块的重写.
- 添加断言重写作为一个可替换的自省机制
- 介绍 --assert 选项。不赞成使用 --no-assert 和 --nomagic .
- 移除 --no-assert 和 --nomagic 选项。移除 --assert=reinterp 选项。

假设你有一个自定义的导入器 custom_importer.py，它修改了 sys.meta_path：

# custom_importer.py
import sys

class CustomImporter:
    def find_spec(self, fullname, path, target=None):
        # 自定义的导入逻辑
        print(f"CustomImporter: Finding spec for {fullname}")
        return None

sys.meta_path.insert(0, CustomImporter())

测试模块

假设你有一个测试模块 test_module.py，其中包含一个简单的测试：

# test_module.py
import pytest

def test_example():
    assert 1 + 1 == 2