跳到内容

测试套件

信息

关于 Rust 测试套件的更多信息将在稍后添加到此页面。

py-polars/tests 文件夹包含 Polars 的主测试套件。本页包含有关测试套件各个组件的一些信息，以及编写新测试的指导方针。

测试套件包含四个主要组件，每个组件都位于各自的文件夹中：单元测试、参数化测试、基准测试和文档测试。

请注意，此测试套件也间接负责测试 Rust Polars。Rust 测试套件保持较小，以减少编译时间。许多 Rust 功能在此处进行测试。

单元测试

unit 文件夹包含所有常规单元测试。这些测试旨在确保所有 Polars 功能按预期工作。

运行单元测试

通过在 py-polars 文件夹中运行 make test 来运行单元测试。这将编译 Rust 绑定，然后运行单元测试。

如果您只在 Python 代码中工作，可以通过在您的虚拟环境中直接运行 pytest 来避免每次都重新编译。

默认情况下，对于本地测试运行，会跳过“慢速”测试和“仅限 CI”测试。此类测试使用自定义 pytest 标记进行标记。要专门运行这些测试，您可以运行 pytest -m slow、pytest -m ci_only、pytest -m slow ci_only 或运行 pytest -m "" 来运行所有测试，无论标记如何。

请注意，“仅限 CI”测试可能需要您运行 make requirements-all 来获取默认 Polars 开发环境中未安装的其他依赖项（例如 torch）。

通过运行 pytest -n auto 可以并行运行测试。并行化由 pytest-xdist 处理。

编写单元测试

每当您添加新功能时，也应添加匹配的单元测试。将您的测试添加到 unit 文件夹中适当的测试模块。需要牢记的一些准则：

  • 尝试完全覆盖所有您能想到的可能输入和边缘情况。
  • 在适当的情况下，利用 pytest 工具，如 fixture 和 parametrize。
  • 由于许多测试都需要首先定义一些数据，因此在单个测试中运行多个检查可能很高效。这也可以通过使用 pytest fixtures 来解决。
  • 单元测试不应依赖外部因素，否则测试并行化将失效。

参数化测试

parametric 文件夹包含使用 Hypothesis 框架编写的参数化测试。这些测试旨在通过生成大量随机数据点来发现和测试边缘情况。

运行参数化测试

通过运行 pytest -m hypothesis 来运行参数化测试。

请注意，在运行 pytest 时，参数化测试默认被排除。您必须明确指定 -m hypothesis 才能运行它们。

这些测试将在计算测试覆盖率时包含，并且也将作为 make test-all make 命令的一部分运行。

文档测试

docs 文件夹包含一个用于运行 doctest 的脚本。此文件夹不包含任何实际的测试——相反，该脚本检查 Polars 包中所有文档字符串的 Examples 部分，运行代码示例，并验证输出。

运行 doctest 的目的是确保我们文档字符串中的 Examples 部分有效，并与代码更改保持同步。

运行 doctest

要在 py-polars 文件夹中运行 doctest 模块，请运行 make doctest。您也可以直接从您的虚拟环境运行该脚本。

请注意，文档测试不使用 pytest 运行。尽管 pytest 确实具有运行文档示例的能力，但其配置选项对于我们的目的来说过于有限。

文档测试不计入测试覆盖率。它们不能替代单元测试，而是旨在向用户传达 Polars API 的预期用法。

编写文档示例

几乎所有属于 Polars 公共 API 的类/方法/函数都应在其文档字符串中包含代码示例。这些示例帮助用户理解基本用法，也允许我们说明更高级的概念。编写好的文档字符串 Examples 部分的一些指导原则：

  • 从展示默认功能的最小示例开始。
  • 展示其参数的效果。
  • 展示与其他代码结合时的任何特殊交互。
  • 保持简洁，避免多个示例展示相同内容。

已经有许多出色的文档字符串示例，如果您需要灵感，只需查看其他代码即可！

除了编写文档测试时可用的常规选项外，脚本配置还允许使用新的 IGNORE_RESULT 指令。如果您想确保代码运行，但输出可能设计为随机或不值得检查，请使用此指令。

>>> df.sample(n=2)  # doctest: +IGNORE_RESULT

基准测试

benchmark 文件夹包含用于运行各种基准测试的代码。测试套件这部分的目标是发现代码中的性能退化，并验证 Polars 功能在发布版本或大规模运行时是否按预期工作。

Polars 使用 CodSpeed 来跟踪基准测试的性能。

生成数据

对于大多数测试，必须首先生成一个相对较大的数据集。这是作为 pytest 设置过程的一部分完成的。

数据生成逻辑取自 H2O.ai 数据库基准测试，这是许多基准测试的基础。

运行基准测试

基准测试可以使用 pytest 运行。运行 pytest -m benchmark --durations 0 -v 来运行这些测试并报告运行持续时间。

请注意，在运行 pytest 时，基准测试默认被排除。您必须明确指定 -m benchmark 才能运行它们。它们在计算测试覆盖率时也将被排除。

这些测试将作为 make test-all make 命令的一部分运行。