pytest的内置插件盘点21. doctest

本文系《pytest源码剖析》系列内容

插件路径：_pytest.doctes

实现的 hook

调用的 hook

无

定义的 fixture

doctest_namespace

插件功能

创建了一系列命令行参数和 ini 配置，用于控制 doctests 的收集和执行

调用 doctest 收集用例，并生成 DoctestItem 作为用例

创建 doctest.DebugRunner 的子类，作为 runner 执行用例

代码片段

@fixture(scope="session")def doctest_namespace() -> Dict[str, Any]: return dict()

插件创建了一个全局的，返回可变对象的 fixture，可以实现一个命名空间。各个用例可利用这个命名空间，共享数据。

简评

doctests 是 python 内置的测试框架之一（另一个是 unittest）, 它将文档字符串中的使用示例，作为测试用例进行执行

这是一个简单的示例

def add(a,b): """ 加法函数

>>> add(1,2) 3>>> add(2,2) 4

:param a: 整数 :param b: 整数 :return: 整数，a与b的相加结果 """

return a + b

其中的>>>会被视为用例执行步骤，下一行会被视为预期结果

通过下面的命令执行用例

python -m docstest test_add.py -v

执行结果：

...

doctest_namespace 是一个 session 级的 fixture，返回session级的字典，从而实现了一个命名空间，各个用例可利用这个命名空间进行共享数据

这一个很好的技巧，值得大家记住

...

doctest 更适合单元测试，在开发Python程序时，随手把文档字符串写好，

文档字符串既充当了文档，又实现了用例。

不过说实话，我写了近 10 年 python，完全没有用过它

和同为标准库的 unittest 相比，功能性和便捷性上差距还是很大的

...

doctest 和 unittest、nose 一样，是 pytest 对其他测试框架的兼容，

降低用户从其他测试框架迁移 pytest 的门槛

在我看来，doctest 插件最重要的不它的代码内容，体现了 pytest 良好的产品思维：

做好阶梯和通道，被人使用、被人更方便地使用，才能让一个产品成长壮大