九、pytest -- 集成文档测试

目录

• 1. 集成doctest模块
  • 1.1. 经过指定文本文件的方式
  • 1.2. 经过编写文档字符串的方式
  • 1.3. 指定额外的选项
• 2. 失败时继续执行
• 3. 指定输出的格式
• 4. 文档测试中使用fixture
• 5. 文档测试的命名空间
• 6. 跳过文档测试

1. 集成doctest模块

doctest是python内置的一个标准库，它能够查找代码中相似交互式会话形式的注释，并检查它们是否正确；

1.1. 经过指定文本文件的方式

默认状况下，pytest会自动收集全部名称匹配test*.txt规则的文件，并调用doctest执行它们；

下面，咱们来看一个简单的例子：

# src/chapter-9/test_example.txt

>>> x = 3
>>> x
3

直接使用pytest命令就能够执行它：

λ pipenv run pytest src/chapter-9/test_example.txt
====================== test session starts ======================= 
platform win32 -- Python 3.7.3, pytest-5.1.3, py-1.8.0, pluggy-0.13.0
rootdir: D:\Personal Files\Projects\pytest-chinese-doc
collected 1 item

src\chapter-9\test_example.txt .                            [100%]

======================= 1 passed in 0.03s ========================

咱们也可使用命令行选项--doctest-glob添加文件名称的匹配规则；

例如，匹配rst格式的文件：

pytest --doctest-glob='*.rst'

注意：--doctest-glob能够屡次指定，它们之间是或者的关系，而且依旧支持默认的test*.txt规则；

1.1.1. 文本文件的编码

doctest文件的默认编码是UTF-8，你能够在pytest.ini中使用doctest_encoding选项指定新的编码；例如，使用latin1编码：

[pytest]
doctest_encoding = latin1

1.2. 经过编写文档字符串的方式

除了文本文件外，pytest还支持检查文档字符串中的注释；例如：

# src/chapter-9/test_module.py

def something():
    '''文档字符串示例
    
    >>> something()
    42
    '''
    return 42


def test_module():
    assert something() == 42

执行时，须要添加--doctest-modules命令行选项：

λ pipenv run pytest --doctest-modules src/chapter-9/test_module.py
====================== test session starts ======================= 
platform win32 -- Python 3.7.3, pytest-5.1.3, py-1.8.0, pluggy-0.13.0
rootdir: D:\Personal Files\Projects\pytest-chinese-doc
collected 2 items

src\chapter-9\test_module.py ..                             [100%]

======================= 2 passed in 0.03s ========================

--doctest-modules会查找全部名称匹配*.py的文件，收集文档字符串中相似交互式会话形式的注释，并把每个文档字符串做为一个用例来执行，因此上面咱们执行了两个测试，其中一个是文档测试；

若是想让pytest --doctest-modules正确收集到相关注释，需知足如下条件：

• 文件名称符合*.py规则，但无需知足test_*.py或者*_test.py规则；
• 文档字符串中的注释必须是相似python交互式会话形式的注释；

若是你不想每次执行都指定--doctest-modules选项，能够考虑在pytest.ini中添加以下配置：

[pytest]
addopts = --doctest-modules

文档字符串是一个多行字符串，使用'''或者"""包裹；通常推荐形式为，第一行简述功能，第二行空行，第三行具体描述；

而且，能够经过__doc__属性访问它；例如，上面例子的__doc__属性为：

>>> print(something.__doc__)
文档字符串示例

    >>> something()
    42

1.3. 指定额外的选项

1.3.1. doctest标准库自带的选项

python的doctest标准库自带一些选项，用于定义文档测试的模式，咱们一样能够在pytest.ini中使用这些功能；例如，忽略尾随的空格：

# src/chapter-9/pytest.ini

doctest_optionflags = NORMALIZE_WHITESPACE

另外，你也能够在行注释中使能这些选项；

例如，使用# doctest: +NORMALIZE_WHITESPACE一样能忽略尾随的空格：

def something():
    '''文档字符串示例
    
    >>> something()  # doctest: +NORMALIZE_WHITESPACE
    42 
    '''
    return 42

更多细节能够参考：https://docs.python.org/3/library/doctest.html#option-flags

1.3.2. pytest自有的选项

ALLOW_BYTES：在输出时，剔除字符串的b前缀；例如，如下文档测试是成功的：

# src/chapter-9/options.py

def str_bytes():
    '''返回字节编码

    >>> str_bytes()  # doctest: +ALLOW_BYTES
    'bytes'
    ''' 
    return b'bytes'

ALLOW_UNICODE：类似的，在输出时，剔除字符串的u前缀；

NUMBER：为了不出现如下致使测试失败的状况：

Expected:
    3.14
Got:
    3.141592653589793

咱们能够经过配置NUMBER选项，只比较列出的精度：

# src/chapter-9/options.py

def number():
    '''浮点数的精度

    >>> import math
    >>> math.pi  # doctest: +NUMBER
    3.14 
    '''
    return 1

注意：咱们并不建议在全局使能NUMBER选项，由于它会修改输出中全部的浮点数的精度，甚至是在字符串或者列表中；

例如，如下文档测试也是成功的：

# src/chapter-9/options.py

def str_number():
    '''浮点数字符串的精度

    >>> str_number()  # doctest: +NUMBER
    '3.14' 
    '''
    return '3.1415'

2. 失败时继续执行

默认状况下，对于一个给定的文档测试，pytest在遇到第一个失败点时退出执行；可是，咱们能够经过--doctest-continue-on-failure命令行选项，让其继续执行；

例如，对于如下文档字符串，包含两个测试点，pytest --doctest-continue-on-failure会报告两个错误（默认只会报告第一个错误）：

def str_bytes():
    '''返回字节编码

    >>> str_bytes()  
    'bytes' 
    >>> import math
    >>> math.pi  
    3.14 
    ''' 
    return b'bytes'

3. 指定输出的格式

文档测试失败时，你能够经过如下方式更改测试输出的格式：

pytest --doctest-modules --doctest-report none
pytest --doctest-modules --doctest-report udiff
pytest --doctest-modules --doctest-report cdiff
pytest --doctest-modules --doctest-report ndiff
pytest --doctest-modules --doctest-report only_first_failure

更多细节能够参考：https://docs.python.org/3/library/doctest.html#doctest.REPORT_UDIFF

4. 文档测试中使用fixture

经过getfixture可让你在文档字符串中使用fixture：

>>> tmp = getfixture('tmpdir')
>>> ...
>>>

5. 文档测试的命名空间

doctest_namespace fixture能够用于向运行doctest测试的命名空间中注入一些信息，它是一个标准的字典对象；

例如，咱们在conftest.py中定义一个方法，注入到doctest的命名空间中：

# src/chapter-9/conftest.py

import pytest


def func():
    return 42


@pytest.fixture(autouse=True)
def add_func(doctest_namespace):
    doctest_namespace['function'] = func

能够在文档字符串中直接使用它：

# src/chapter-9/func.txt

>>> function()
42

6. 跳过文档测试

pytest 4.4版本新增功能

咱们能够经过pytest.skip跳过文档测试；例如，跳过Windows系统上的文档测试：

>>> import sys, pytest
>>> if sys.platform.startswith('win'):
...     pytest.skip('this doctest does not work on Windows')
>>> function()
42

GitHub仓库地址：https://github.com/luizyao/pytest-chinese-doc