pytest-accept

pytest-accept 是一个pytest插件，用于自动更新doctest输出。它运行doctests，观察生成的输出，并将它们写入doctests的文档化输出。

它针对以下受众设计

• 使用doctests的人，他们不喜欢手动从pytest错误日志复制粘贴输出到doctests的文档化输出。pytest-accept会为您完成这项工作。
• 那些通常觉得编写任何测试都有些烦人，更喜欢通过“运行代码看看它是否工作”来开发的人。这个库旨在让测试成为开发循环中愉快的部分。

pytest-accept 与它所工作的doctests解耦——它可以与现有的doctests一起使用，它编辑的doctests与正常的doctests没有区别。

Jesse，这是怎么回事？

以下是一个pytest-accept的示例：给定一个包含不正确的文档化输出的文件，如 add.py

def add(x, y):
    """
    Adds two values.

    >>> add(1, 1)
    3

    >>> add("ab", "c")
    'bac'
    """

    return x + y

...使用pytest运行doctests并传递 --accept 将现有不正确的值替换为正确值

pytest --doctest-modules examples/add.py --accept

diff --git a/examples/add.py b/examples/add.py
index 10a71fd..c2c945f 100644
--- a/examples/add.py
+++ b/examples/add.py
@@ -3,10 +3,10 @@ def add(x, y):
     Adds two values.

     >>> add(1, 1)
-    3
+    2

     >>> add("ab", "c")
-    'bac'
+    'abc'
     """

     return x + y

这种测试风格在某些语言中已经相当成熟，尽管仍然没有得到应有的关注，并且历史上在Python中支持得并不好。

令人困惑的是，它被称为“快照测试”、“回归测试”、“期望测试”、“文档测试”或“验收测试”。关于这种测试风格的最好解释来自 @yminsky 在 Jane Street 博客文章 中。 @matklad 在他的博客文章 如何测试 中也有出色的总结。

安装

pip install pytest-accept

pytest 测试怎么办？

在 assert_plugin.py 中的先前尝试试图为 assert 语句做这件事，该文件包含了一些关于这项努力的说明。最大的问题是 pytest 在每个测试中的第一个 assert 失败时就会停止，这非常有限。（ whereas pytest 可以配置为在 doctest 失败时继续，这个库就是利用了这个功能。）

在这里，可能可以改变 pytest 的行为 ，但这需要对 pytest 代码库进行重大努力。

• 可以使用像 pytest-regtest 这样的现有库，它提供文件快照测试（即非内联）。
• 我们可以编写一个特定的函数/固件，如 accept(result, "abc")，类似于 rust 的优秀框架 insta（我为它开发了一些功能），或者 ocaml 的 ppx_expect。
  • 但这有一个缺点，就是将测试与插件耦合起来：无法独立于插件运行测试，或者在没有插件的情况下使用插件进行通用 assert 测试。而 pytest 的一个伟大之处就是它对正常 assert 语句的延期。
• 这种测试感觉像是写一个笔记本并对其进行测试。 pytest-notebook 完全实现了这一点。

还有其他什么吗？

没有什么突破性的东西！一些说明

• 如果文档字符串使用了转义字符，如 \n，Python 将将其解释为转义字符而不是字面值。使用原始字符串以便将其解释为字面值。例如，这会失败

  def raw_string():
      """
      >>> "\n"
      '\n'
      """
  

  但使用这种方式则成功

  def raw_string():
  -    """
  +    r"""
      >>> "\n"
      '\n'
  

  pytest-accept 可能在这里做更多——例如改变文档字符串的格式。但这不是一件小事，可能过于侵入。

• 该库尝试确认文件在测试的开始和结束时没有变化，并在检测到有变化时不会覆盖文件。这对于在人们在工作文件的同时在后台反复运行测试的工作流程很有帮助（例如使用类似 watchexec 的东西），或者当测试花费很长时间时，可能是因为 --pdb。为了加倍小心，传递 --accept-copy 将导致插件创建一个名为 {file}.py.new 的文件而不是在任意 doctest 失败时覆盖文件。

  • 它将覆盖现有的已记录值，尽管这些值本身通常没有太大用处——它们是为了匹配生成的代码而设计的。唯一可能有用的情况是它们已被人工整理（例如，删除像哈希这样的易变输出），在这种情况下，最好可以从版本控制中恢复它们。或者如上所述，传递 --accept-copy 以保持保守。

• 这还处于早期阶段，主要由我和 xarray 使用，可能存在一些小错误。请告诉我任何相关信息，我将尝试修复它们。

• 它目前不会影响测试结果的打印；doctests 仍然会打印为失败。

  • TODO：未来的版本可以打印一些关于它们已被修复的信息。

• Python 的 doctest 库并不完美

  • 它不能处理缩进，以及其他一些东西。
    • 我们修改输出以匹配doctest格式；例如，使用空白行。如果生成的输出不足以使doctest通过，并且存在某种足够的形式输出，请报告为错误。
  • .*的语法是省略号...，它也是继续代码行的语法，因此行首必须始终指定。
  • 所有指令的语法可能都不太美观。
  • 它没有漂亮的打印选项，因此测试必须使用pprint(x)自己进行漂亮的打印，这是冗长的。
  • 在某些情况下，它报告行号不正确——两个由延续字符\分隔的docstring行被视为一行，这意味着此库将无法访问doctest输入和输出的正确行号。