测试指南#

简介#

在 1.15 版本之前，NumPy 使用 nose 测试框架，现在使用 pytest 框架。为了支持使用旧 NumPy 框架的下游项目，旧框架仍然维护，但 NumPy 的所有测试都应该使用 pytest。

我们的目标是 NumPy 中的每个模块和包都应该有一套完整的单元测试。这些测试应该涵盖给定例程的全部功能，以及其对错误或意外输入参数的健壮性。具有良好覆盖率的精心设计的测试对重构的便利性有巨大的影响。每当在例程中发现新的错误时，您应该为该特定情况编写一个新的测试，并将其添加到测试套件中，以防止该错误在不知不觉中再次出现。

注意

SciPy 使用来自 numpy.testing 的测试框架，因此下面显示的所有 NumPy 示例也适用于 SciPy

测试 NumPy#

NumPy 可以通过多种方式进行测试，您可以选择您觉得舒适的任何方式。

从 Python 内部运行测试#

您可以通过 numpy.test 测试已安装的 NumPy，例如，要运行 NumPy 的完整测试套件，请使用以下命令

>>> import numpy
>>> numpy.test(label='slow')

测试方法可以接受两个或多个参数；第一个 label 是一个字符串，指定应该测试什么，第二个 verbose 是一个整数，给出输出详细程度的级别。有关详细信息，请参阅 numpy.test 的文档字符串。 label 的默认值是“fast” - 这将运行标准测试。“full”字符串将运行所有测试，包括那些被识别为运行缓慢的测试。如果 verbose 为 1 或更小，则测试只会显示有关正在运行的测试的信息消息；但如果它大于 1，则测试还将提供有关缺少测试的警告。因此，如果您想运行每个测试并获取有关哪些模块没有测试的消息

>>> numpy.test(label='full', verbose=2)  # or numpy.test('full', 2)

最后，如果您只对测试 NumPy 的子集感兴趣，例如 _core 模块，请使用以下命令

>>> numpy._core.test()

从命令行运行测试#

如果您想构建 NumPy 以便在 NumPy 本身工作，请使用 spin 实用程序。要运行 NumPy 的完整测试套件

$ spin test -m full

测试 NumPy 的子集

$ spin test -t numpy/_core/tests

有关测试的详细信息，请参阅测试构建

运行文档测试#

NumPy 文档包含代码示例，“文档测试”。要检查示例是否正确，请安装 scipy-doctest 包

$ pip install scipy-doctest

并运行以下命令之一

$ spin check-docs -v
$ spin check-docs numpy/linalg
$ spin check-docs -- -k 'det and not slogdet'

请注意，当您使用 spin test 时，不会运行文档测试。

其他运行测试的方法#

使用您喜欢的 IDE（如 vscode 或 pycharm）运行测试

编写您自己的测试#

如果您正在编写想要成为 NumPy 一部分的代码，请在开发代码时编写测试。NumPy 包目录中的每个 Python 模块、扩展模块或子包都应该有一个相应的 test_<name>.py 文件。Pytest 会检查这些文件中的测试方法（名为 test*）和测试类（名为 Test*）。

假设您有一个 NumPy 模块 numpy/xxx/yyy.py，其中包含一个函数 zzz()。要测试此函数，您需要创建一个名为 test_yyy.py 的测试模块。如果您只需要测试 zzz 的一个方面，您可以简单地添加一个测试函数

def test_zzz():
    assert zzz() == 'Hello from zzz'

通常，我们需要将多个测试分组在一起，因此我们创建一个测试类

import pytest

# import xxx symbols
from numpy.xxx.yyy import zzz
import pytest

class TestZzz:
    def test_simple(self):
        assert zzz() == 'Hello from zzz'

    def test_invalid_parameter(self):
        with pytest.raises(ValueError, match='.*some matching regex.*'):
            ...

在这些测试方法中，使用 assert 语句或专门的断言函数来测试某个假设是否有效。如果断言失败，则测试失败。常见的断言函数包括

numpy.testing.assert_equal 用于测试结果数组和参考之间的精确元素级相等性，
numpy.testing.assert_allclose 用于测试结果数组和参考之间的近似元素级相等性（即，具有指定的相对和绝对容差），以及
numpy.testing.assert_array_less 用于测试结果数组和参考之间的（严格）元素级排序。

默认情况下，这些断言函数只比较数组中的数值。考虑使用 strict=True 选项来检查数组的 dtype 和形状。

当您需要自定义断言时，请使用 Python assert 语句。请注意，pytest 在内部重写 assert 语句，以便在失败时提供信息性输出，因此应该优先于旧版本的 numpy.testing.assert_。虽然在使用 -O 以优化模式运行 Python 时会忽略普通的 assert 语句，但这在使用 pytest 运行测试时不是问题。

类似地，pytest 函数 pytest.raises 和 pytest.warns 应该优先于其旧版本的 numpy.testing.assert_raises 和 numpy.testing.assert_warns，后者使用更广泛。这些版本还接受一个 match 参数，该参数应始终用于精确地定位预期的警告或错误。

请注意，test_ 函数或方法不应该有文档字符串，因为这使得很难从使用 verbose=2（或类似详细级别设置）运行测试套件的输出中识别测试。请使用普通注释（#）来描述测试的意图，并帮助不熟悉的读者解释代码。

此外，由于 NumPy 的大部分是最初编写时没有单元测试的旧代码，因此仍然有几个模块没有测试。请随意选择其中一个模块并为其开发测试。

在测试中使用 C 代码#

NumPy 公开了一个丰富的 C-API。这些 API 使用 C 扩展模块进行测试，这些模块编写时“仿佛”它们对 NumPy 的内部结构一无所知，而是仅使用官方的 C-API 接口。此类模块的示例包括 _rational_tests 中用户定义的 rational dtype 的测试，或者 _umath_tests 中的 ufunc 机制测试，它们都是二进制发行版的一部分。从 1.21 版本开始，您还可以在测试中编写 C 代码片段，这些代码片段将在本地编译为 C 扩展模块并加载到 Python 中。

numpy.testing.extbuild.build_and_import_extension(modname, functions, *, prologue='', build_dir=None, include_dirs=[], more_init='')#

从函数片段列表 functions 构建并导入 C 扩展模块 modname。

参数:

functions片段列表: 每个片段都是 func_name、调用约定、代码片段的序列。
prologue字符串: 位于其余代码之前的代码，通常是额外的 #include 或 #define 宏。
build_dirpathlib.Path: 构建模块的位置，通常是一个临时目录
include_dirs列表: 编译时查找包含文件的额外目录
more_init字符串: 出现在模块 PyMODINIT_FUNC 中的代码

返回:

out: 模块: 模块已被加载，可以随时使用

示例

>>> functions = [("test_bytes", "METH_O", """
    if ( !PyBytesCheck(args)) {
        Py_RETURN_FALSE;
    }
    Py_RETURN_TRUE;
""")]
>>> mod = build_and_import_extension("testme", functions)
>>> assert not mod.test_bytes('abc')
>>> assert mod.test_bytes(b'abc')

标记测试#

像上面这样的未标记测试在默认的 numpy.test() 运行中执行。如果您想将测试标记为慢速测试，并因此保留给完整的 numpy.test(label='full') 运行，您可以使用 pytest.mark.slow 进行标记。

import pytest

@pytest.mark.slow
def test_big(self):
    print('Big, slow test')

方法也是如此

class test_zzz:
    @pytest.mark.slow
    def test_simple(self):
        assert_(zzz() == 'Hello from zzz')

更简单的 setup 和 teardown 函数/方法#

测试会按名称查找模块级或类方法级的 setup 和 teardown 函数；因此

def setup_module():
    """Module-level setup"""
    print('doing setup')

def teardown_module():
    """Module-level teardown"""
    print('doing teardown')


class TestMe:
    def setup_method(self):
        """Class-level setup"""
        print('doing setup')

    def teardown_method():
        """Class-level teardown"""
        print('doing teardown')

函数和方法的 Setup 和 teardown 函数称为“fixtures”，应谨慎使用。 pytest 在各种作用域中支持更通用的 fixture，这些 fixture 可以通过特殊参数自动使用。例如，特殊参数名称 tmpdir 在测试中用于创建临时目录。

参数化测试#

pytest 的一个非常好的功能是可以使用 pytest.mark.parametrize 装饰器轻松地测试一系列参数值。例如，假设您希望测试 linalg.solve 在三种数组大小和两种数据类型的所有组合中的表现

@pytest.mark.parametrize('dimensionality', [3, 10, 25])
@pytest.mark.parametrize('dtype', [np.float32, np.float64])
def test_solve(dimensionality, dtype):
    np.random.seed(842523)
    A = np.random.random(size=(dimensionality, dimensionality)).astype(dtype)
    b = np.random.random(size=dimensionality).astype(dtype)
    x = np.linalg.solve(A, b)
    eps = np.finfo(dtype).eps
    assert_allclose(A @ x, b, rtol=eps*1e2, atol=0)
    assert x.dtype == np.dtype(dtype)

文档测试#

文档测试是记录函数行为并同时测试该行为的一种便捷方法。交互式 Python 会话的输出可以包含在函数的文档字符串中，并且测试框架可以运行该示例并将实际输出与预期输出进行比较。

可以通过将 doctests 参数添加到 test() 调用来运行文档测试；例如，要运行 numpy.lib 的所有测试（包括文档测试）

>>> import numpy as np
>>> np.lib.test(doctests=True)

文档测试的运行方式就像它们位于一个新的 Python 实例中，该实例已执行 import numpy as np。作为 NumPy 子包一部分的测试将已导入该子包。例如，对于 numpy/linalg/tests/ 中的测试，将创建命名空间，以便 from numpy import linalg 已经执行。

`tests/`#

我们没有将代码和测试放在同一个目录中，而是将给定子包的所有测试放在 tests/ 子目录中。对于我们的示例，如果它尚不存在，则需要在 numpy/xxx/ 中创建一个 tests/ 目录。因此，test_yyy.py 的路径是 numpy/xxx/tests/test_yyy.py。

一旦编写了 numpy/xxx/tests/test_yyy.py，就可以通过转到 tests/ 目录并键入来运行测试

python test_yyy.py

或者，如果您将 numpy/xxx/tests/ 添加到 Python 路径，则可以在解释器中以交互方式运行测试，如下所示

>>> import test_yyy
>>> test_yyy.test()

`init.py` 和 `setup.py`#

但是，通常不希望将 tests/ 目录添加到 Python 路径。相反，最好直接从模块 xxx 调用测试。为此，只需将以下行放在包的 __init__.py 文件的末尾即可

...
def test(level=1, verbosity=1):
    from numpy.testing import Tester
    return Tester().test(level, verbosity)

您还需要在 setup.py 的配置部分中添加 tests 目录

...
def configuration(parent_package='', top_path=None):
    ...
    config.add_subpackage('tests')
    return config
...

现在您可以执行以下操作来测试您的模块

>>> import numpy
>>> numpy.xxx.test()

此外，在调用整个 NumPy 测试套件时，将会找到并运行您的测试

>>> import numpy
>>> numpy.test()
# your tests are included and run automatically!

提示与技巧#

已知失败和跳过测试#

有时您可能希望跳过某个测试或将其标记为已知失败，例如在测试套件在要测试的代码之前编写时，或者如果测试仅在特定架构上失败。

要跳过测试，只需使用 skipif

import pytest

@pytest.mark.skipif(SkipMyTest, reason="Skipping this test because...")
def test_something(foo):
    ...

如果 SkipMyTest 的计算结果为非零，则测试标记为已跳过，并且详细测试输出中的消息是提供给 skipif 的第二个参数。类似地，可以通过使用 xfail 将测试标记为已知失败

import pytest

@pytest.mark.xfail(MyTestFails, reason="This test is known to fail because...")
def test_something_else(foo):
    ...

当然，可以通过分别使用没有参数的 skip 或 xfail 来无条件地跳过测试或将其标记为已知失败。

跳过和已知失败的测试总数显示在测试运行结束时。跳过的测试在测试结果中标记为 'S'（或对于 verbose > 1 标记为 'SKIPPED'），已知失败的测试标记为 'x'（或如果 verbose > 1 则标记为 'XFAIL'）。

随机数据测试#

对随机数据进行测试是好的，但由于测试失败旨在暴露新的错误或回归，因此在没有代码更改的情况下大部分时间通过但偶尔失败的测试没有帮助。通过在生成随机数据之前设置随机数种子来使随机数据具有确定性。根据随机数的来源，使用 Python 的 random.seed(some_number) 或 NumPy 的 numpy.random.seed(some_number)。

或者，您可以使用 Hypothesis 来生成任意数据。Hypothesis 为您管理 Python 和 Numpy 的随机种子，并提供了一种非常简洁有效的方法来描述数据（包括 hypothesis.extra.numpy，例如，用于一组相互广播的形状）。

与随机生成相比，其优势包括无需固定种子即可重放和共享失败的工具、报告每个失败的最小示例以及触发错误的优于朴素随机的技术。

`numpy.test` 的文档#

numpy.test(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, durations=-1, tests=None)#

Pytest 测试运行器。

测试函数通常像这样添加到包的 __init__.py 中

from numpy._pytesttester import PytestTester
test = PytestTester(__name__).test
del PytestTester

调用此测试函数会查找并运行与该模块及其所有子模块关联的所有测试。